Rename public functions and stop exporting several public API methods

[musm]

Rename public functions and stop exporting most public API

Open to re-exporting API people think should be exported.

[jmert]

Should the modifying functions terminate with ! to better follow typical Julia naming? IO functions don't, but Dict functions do, so not sure which should be followed.

[musm]

A lot of these feel like we should just use multiple dispatch for, e.g.:

create_group(...) could all just be
create(HDF5.group, ....) et al. 

although the dispatch is messy because the function signatures vary quite a bit between them all.

[musm]

Should the modifying functions terminate with ! to better follow typical Julia naming? IO functions don't, but Dict functions do, so not sure which should be followed.

That's a good point, I don't have a very strong opinion on this either, but it might make sense to adopt the Dict like notion for some of the functions. In particular delete, which AFAIK doesn't have a IO function equivalent.

[musm]

although the dispatch is messy because the function signatures vary quite a bit between them all.

Eek, this in general might just be too confusing.

[musm]

Note so I don't forget: figure out what to do with name, filename

[musm]

I do think we should probably not export anything and make the public interface module scoped.

[musm]

If we are renaming these we should really decide what to unexport, otherwise it's going to be basically impossible to unexport the names if we want to do so in a deprecation friendly manner.

[musm]

One option is to basically unexport everything other than h5* functions. Then if we decide to export module scoped public API functions, it will at least be possible to do so.

[musm]

Another question, which form should we adopt:
(1) group_write or (2) write_group

(2)reads more naturally and is the scheme adopted by, e.g. h5py, and more consistent in general with Julia. OTOH, (1) allows you to hit <Tab> on group_ and easily discover all available methods.

[musm]

We should change this to @load and @save to align with JLD and JLD2.

[musm]

Probably follow up work.

[musm]

This should be ready for review now.

What do we think about #699 (comment) ?

In a follow up I propose we remove/refactor h5rewrite, h5writeattr, h5readattr

[jmert]

In a follow up I propose we remove/refactor h5rewrite, h5writeattr, h5readattr

👍

[musm]

Thanks for the review. Addressed the comments and fixed up the remaining issues.

Do you want to sign off on the updated export list?

(Should we export ishdf5?)

[jmert]

(Should we export ishdf5?)

I'm agnostic — I think there's no harm in exporting it, but I haven't actually personally found it necessary either. (I've been using FileIO.query on files and dispatching on FileIO.File{format"HDF5"}.)

[jmert]

Just as a note, I found I temporarily needed:

diff --git a/src/deprecated.jl b/src/deprecated.jl
index 04e204a..fa138f7 100644
--- a/src/deprecated.jl
+++ b/src/deprecated.jl
@@ -412,18 +412,18 @@ end
 @deprecate objinfo(obj::Union{File,Object}) object_info(obj)
 
 # - rename bindings
-@deprecate a_open    open_attribute
-@deprecate a_read    read_attribute
-@deprecate a_write   write_attribute
-@deprecate a_create  create_attribute
-@deprecate a_delete  delete_attribute
-@deprecate attrs     attributes
+@deprecate a_open                    open_attribute
+@deprecate a_read                    read_attribute
+@deprecate a_write(args...; kws...)  write_attribute(args...; kws...)
+@deprecate a_create(args...; kws...) create_attribute(args...; kws...)
+@deprecate a_delete                  delete_attribute
+@deprecate attrs                     attributes
 
-@deprecate d_open            open_dataset
-@deprecate d_read            read_dataset
-@deprecate d_write           write_dataset
-@deprecate d_create          create_dataset
-@deprecate d_create_external HDF5.create_external_dataset
+@deprecate d_open                    open_dataset
+@deprecate d_read                    read_dataset
+@deprecate d_write(args...; kws...)  write_dataset(args...; kws...)
+@deprecate d_create(args...; kws...) create_dataset(args...; kws...)
+@deprecate d_create_external         HDF5.create_external_dataset
 
 @deprecate g_open   open_group
 @deprecate g_create create_group
@@ -432,7 +432,7 @@ end
 @deprecate o_copy   copy_object
 @deprecate o_delete delete_object
 
-@deprecate p_create create_property
+@deprecate p_create(args...; kws...) create_property(args...; kws...)
 
 @deprecate t_create create_datatype
 @deprecate t_open   open_datatype

to work through updating my MAT.jl's HDF5_v0.14-branch for this PR because it was already updated to property syntax and the bare @deprecate doesn't add keywords automatically. I don't necessarily think this should be added, though, because it's not relevant for upgrading from the tagged v0.13.6 — rather just wanted to point it out as an interesting consequence of multiple rounds of deprecated changes.

[musm]

Ok great, thanks again!