include pep8-compliant API alternative about h5netcdf

[shoyer]

Yes, I was pretty conflicted about the naming conventions to use. It pains me not to follow PEP8, but I also wanted to try to avoid forcing people to learn another approach.

It might make sense to have two different APIs:

• a cleaner PEP 8 compatible API accessible via import h5netcdf
• a legacy compatible API which is almost a drop-in replacement for netCDF4-python, importable like import h5netcdf.legacyapi as netCDF4.

But on the other hand, two API is twice the surface area for bugs....

For now, I leaned toward the later, given that in my opinion users should really use another interface like xray to write netCDF files instead of writing all the metadata themselves.

[shoyer]

As for docs, yes I need to write those :).

[mangecoeur]

I think two apis would not be such a big issue (with a handful of unit tests of course ;) - the number of function in the api is relatively limited and you can add straight aliases like underscore_fn_name = camelCaseFunctionName. Though personally I would simply break with the existing library, unless you have a strong preference for a drop-in replacement. I feel that this would be an opportunity to reconsider the existing API and see if it could be improved.

I don't think you can depend on higher level libraries to "hide" the API though - if (which is my use case) you need to create a netCDF file with a very specific metadata format you need to set it by hand and that's easiest to do directly with the netCDF library rather than a higher level wrapper.

[shoyer]

Just pushed changes implementing this feature to master. I'm thinking now that the main h5netcdf module will be more closely patterned off of h5py, with only the minimal adaptations necessary to make it make sense for netCDF files. If you have ideas about what the main API should look like, I'm also open to suggestions :).

The main reason I originally decided to keep with the existing API is to facilitate testing. So I'd like to keep around the legacyapi module, if only for that reason. It also makes it easier to test out this package, which is also a good thing.

I suppose you are correct that there will always be some users (e.g., library writers) who will want a lower level interface for writing netCDF files.