Deprecate write-only file modes.

[joaander]

Description

Add file modes that mimic those in h5py.

Motivation and Context

GSD files must read the header and indices in order to write to the file, and files must be open in binary mode. Adopting the simplified set of file modes from h5py will make it easier for users to choose the correct mode. Work on #236 prompted this change, as the existence of the GSD_APPEND mode resulted in several bugs during development.

How Has This Been Tested?

Existing unit tests pass and provide the expected FutureWarning messages.

Change log

Added:

* File modes ``'r'``, ``'r+'``, ``'w'``, ``'x'``, and ``'a'``.
  (`#238 <https://github.com/glotzerlab/gsd/pull/238>`__).

Deprecated:

* File modes ``'wb'``, ``'wb+'``, ``'rb'``,  ``'rb+'``, ``'ab'``, ``'xb'``, and ``'xb+'``.  
  (`#238 <https://github.com/glotzerlab/gsd/pull/238>`__).
* [C API] ``GSD_APPEND`` file open mode.
  (`#238 <https://github.com/glotzerlab/gsd/pull/238>`__).

Checklist:

• I have reviewed the Contributor Guidelines.
• I agree with the terms of the GSD Contributor Agreement.
• My name is on the list of contributors (doc/credits.rst) in the pull request source branch.

[tommy-waltmann]

According to the documentation in gsd/hoomd.py there never were any write only file modes. The documentation for wb, xb, and ab all contain the phrase "reading and writing". In fact, the wb/wb+ (xb/xb+) modes have the same exact description.

[joaander]

Following the naming scheme in Python's open function, the modes without the '+' should be write only. In gsd, they are not - thus they should be removed to avoid confusion.

In GSD 1.x, these modes were effectively write only, even though they needed to open the file in read/write mode to accomplish this. I failed to remove the modes without '+' in the 2.x release - this deprecation will fix that in gsd v3.

[tommy-waltmann]

Thinking forward to version 3, should we support write mode strings where the characters w/x/a, b, and + can appear in any order like the python open function supports?

[joaander]

Thinking forward to version 3, should we support write mode strings where the characters w/x/a, b, and + can appear in any order like the python open function supports?

We could. Would you like to make the change on this branch?

[joaander]

Alternately, we could follow the pattern of h5py: https://docs.h5py.org/en/stable/high/file.html#file-open
Interestingly, h5py makes the 'a' mode read/write an existing file or create if needed. This is HOOMD-blue's behavior as well, but gsd 2.x provides no equivalent mode. This is an oversight.

@tommy-waltmann if I adopt the h5py scheme, would you still want to allow the characters in any order: e.g. 'r+' gives the same results as '+r'?

[tommy-waltmann]

@tommy-waltmann if I adopt the h5py scheme, would you still want to allow the characters in any order: e.g. 'r+' gives the same results as '+r'?

h5py doesn't support the + coming before the r, so I would enforce r+ and error on +r.

[tommy-waltmann]

I also like adopting the h5py convention that the b be left implicit.

[tommy-waltmann]

Just a couple of small comments.