Deprecate write-only file modes.

README.md

@@ -28,7 +28,7 @@ Create a hoomd gsd file.
 >>> s.particles.typeid = [0,0,1,1]
 >>> s.particles.position = [[0,0,0],[1,1,1], [-1,-1,-1], [1,-1,-1]]
 >>> s.configuration.box = [3, 3, 3, 0, 0, 0]
->>> traj = gsd.hoomd.open(name='test.gsd', mode='wb')
+>>> traj = gsd.hoomd.open(name='test.gsd', mode='wb+')
 >>> traj.append(s)
 ```
 
@@ -76,7 +76,7 @@ Slice frames:
 ## File layer examples
 
 ```python
-with gsd.fl.open(name='file.gsd', mode='wb') as f:
+with gsd.fl.open(name='file.gsd', mode='wb+') as f:
  f.write_chunk(name='position', data=numpy.array([[1,2,3],[4,5,6]], dtype=numpy.float32));
  f.write_chunk(name='angle', data=numpy.array([0, 1], dtype=numpy.float32));
  f.write_chunk(name='box', data=numpy.array([10, 10, 10], dtype=numpy.float32));

doc/fl-examples.rst

@@ -25,7 +25,7 @@ Open a gsd file
 .. ipython:: python
 
  f = gsd.fl.open(name="file.gsd",
- mode='wb',
+ mode='wb+',
  application="My application",
  schema="My Schema",
  schema_version=[1,0])
@@ -57,7 +57,7 @@ Write data
 .. ipython:: python
 
  f = gsd.fl.open(name="file.gsd",
- mode='wb',
+ mode='wb+',
  application="My application",
  schema="My Schema",
  schema_version=[1,0]);
@@ -176,23 +176,6 @@ Open a file in read/write mode
 
 Open a file in read/write mode to allow both reading and writing.
 
-Write a file in append mode
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. ipython:: python
- :okexcept:
-
- f = gsd.fl.open(name="file.gsd", mode='ab')
- f.write_chunk(name='int', data=numpy.array([10,20], dtype=numpy.int16));
- f.end_frame()
- f.nframes
- # Reads fail in append mode
- f.read_chunk(frame=2, name='double')
- f.close()
-
-Open a file in append mode to write additional chunks to an existing file,
-but prevent reading.
-
 Use as a context manager
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -236,7 +219,7 @@ Truncate
 
 .. ipython:: python
 
- f = gsd.fl.open(name="file.gsd", mode='ab')
+ f = gsd.fl.open(name="file.gsd", mode='rb+')
  f.nframes
  f.schema, f.schema_version, f.application
  f.truncate()

doc/hoomd-examples.rst

@@ -39,7 +39,7 @@ Create a hoomd gsd file
 
 .. ipython:: python
 
- f = gsd.hoomd.open(name='file.gsd', mode='wb')
+ f = gsd.hoomd.open(name='file.gsd', mode='wb+')
  @suppress
  f.close()
 
@@ -57,7 +57,7 @@ Write frames to a gsd file
  frame.particles.position = numpy.random.random(size=(4+i,3))
  return frame
 
- f = gsd.hoomd.open(name='example.gsd', mode='wb')
+ f = gsd.hoomd.open(name='example.gsd', mode='wb+')
  f.extend( (create_frame(i) for i in range(10)) )
  f.append( create_frame(10) )
  len(f)
@@ -139,7 +139,7 @@ Access logged data
 
 .. ipython:: python
 
- with gsd.hoomd.open(name='log-example.gsd', mode='wb') as f:
+ with gsd.hoomd.open(name='log-example.gsd', mode='wb+') as f:
  frame = gsd.hoomd.Frame()
  frame.particles.N = 4
  for i in range(10):
@@ -173,7 +173,7 @@ Read logged data from the ``log`` dictionary.
  .. ipython:: python
  :okexcept:
 
- with gsd.hoomd.open(name='example.gsd', mode='wb') as f:
+ with gsd.hoomd.open(name='example.gsd', mode='wb+') as f:
  frame = gsd.hoomd.Frame()
  frame.particles.N = 4
  frame.log['invalid'] = dict(a=1, b=5)

gsd/fl.pyx

@@ -16,6 +16,7 @@ import logging
 import numpy
 import os
 from pickle import PickleError
+import warnings
 from libc.stdint cimport uint8_t, int8_t, uint16_t, int16_t, uint32_t, int32_t,\
  uint64_t, int64_t
 from libc.errno cimport errno
@@ -205,11 +206,16 @@ def open(name, mode, application=None, schema=None, schema_version=None):
  ``application``, ``schema``, and ``schema_version`` are saved in the file
  and must not be None.
 
+ .. deprecated:: 2.9.0
+
+ The following values to ``mode`` are deprecated: ``'ab'``, ``'xb'``,
+ and ``'wb'``.
+
  Example:
 
  .. ipython:: python
 
- with gsd.fl.open(name='file.gsd', mode='wb',
+ with gsd.fl.open(name='file.gsd', mode='wb+',
  application="My application", schema="My Schema",
  schema_version=[1,0]) as f:
  f.write_chunk(name='chunk1',
@@ -301,6 +307,8 @@ cdef class GSDFile:
  if mode == 'wb':
  c_flags = libgsd.GSD_OPEN_APPEND
  overwrite = 1
+ warnings.warn("The 'wb' mode is deprecated, use 'wb+'",
+ FutureWarning)
  elif mode == 'wb+':
  c_flags = libgsd.GSD_OPEN_READWRITE
  overwrite = 1
@@ -312,12 +320,16 @@ cdef class GSDFile:
  c_flags = libgsd.GSD_OPEN_APPEND
  overwrite = 1
  exclusive_create = 1
+ warnings.warn("The 'xb' mode is deprecated, use 'xb+'",
+ FutureWarning)
  elif mode == 'xb+':
  c_flags = libgsd.GSD_OPEN_READWRITE
  overwrite = 1
  exclusive_create = 1
  elif mode == 'ab':
  c_flags = libgsd.GSD_OPEN_APPEND
+ warnings.warn("The 'ab' mode is deprecated, use 'rb+'",
+ FutureWarning)
  else:
  raise ValueError("mode must be 'wb', 'wb+', 'rb', 'rb+', "
  "'xb', 'xb+', or 'ab'")
@@ -431,7 +443,7 @@ cdef class GSDFile:
  Example:
  .. ipython:: python
 
- with gsd.fl.open(name='file.gsd', mode='wb',
+ with gsd.fl.open(name='file.gsd', mode='wb+',
  application="My application",
  schema="My Schema", schema_version=[1,0]) as f:
  for i in range(10):
@@ -440,7 +452,7 @@ cdef class GSDFile:
  dtype=numpy.float32))
  f.end_frame()
 
- f = gsd.fl.open(name='file.gsd', mode='ab',
+ f = gsd.fl.open(name='file.gsd', mode='rb+',
  application="My application",
  schema="My Schema", schema_version=[1,0])
  f.nframes
@@ -476,7 +488,7 @@ cdef class GSDFile:
  Example:
  .. ipython:: python
 
- f = gsd.fl.open(name='file.gsd', mode='wb',
+ f = gsd.fl.open(name='file.gsd', mode='wb+',
  application="My application",
  schema="My Schema", schema_version=[1,0])
 
@@ -527,7 +539,7 @@ cdef class GSDFile:
  Example:
  .. ipython:: python
 
- f = gsd.fl.open(name='file.gsd', mode='wb',
+ f = gsd.fl.open(name='file.gsd', mode='wb+',
  application="My application",
  schema="My Schema", schema_version=[1,0])
 
@@ -636,7 +648,7 @@ cdef class GSDFile:
  Example:
  .. ipython:: python
 
- with gsd.fl.open(name='file.gsd', mode='wb',
+ with gsd.fl.open(name='file.gsd', mode='wb+',
  application="My application",
  schema="My Schema", schema_version=[1,0]) as f:
  f.write_chunk(name='chunk1',
@@ -703,7 +715,7 @@ cdef class GSDFile:
  .. ipython:: python
  :okexcept:
 
- with gsd.fl.open(name='file.gsd', mode='wb',
+ with gsd.fl.open(name='file.gsd', mode='wb+',
  application="My application",
  schema="My Schema", schema_version=[1,0]) as f:
  f.write_chunk(name='chunk1',
@@ -838,7 +850,7 @@ cdef class GSDFile:
  Example:
  .. ipython:: python
 
- with gsd.fl.open(name='file.gsd', mode='wb',
+ with gsd.fl.open(name='file.gsd', mode='wb+',
  application="My application",
  schema="My Schema", schema_version=[1,0]) as f:
  f.write_chunk(name='data/chunk1',

gsd/hoomd.py

@@ -1104,6 +1104,11 @@ def open(name, mode='rb'):
  | | writing. Does *not* create or overwrite |
  | | existing files. |
  +------------------+---------------------------------------------+
+
+ .. deprecated:: 2.9.0
+
+ The following values to ``mode`` are deprecated: ``'ab'``, ``'xb'``,
+ and ``'wb'``.
  """
  if fl is None:
  raise RuntimeError("file layer module is not available")