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='w')
 >>> traj.append(s)
 ```
 
@@ -48,7 +48,7 @@ Append frames to a gsd file:
 
 Randomly index frames:
 ```python
->>> with gsd.hoomd.open('test.gsd', 'rb') as t:
+>>> with gsd.hoomd.open('test.gsd', 'r') as t:
 ... frame = t[5]
 ... print(frame.configuration.step)
 4
@@ -67,7 +67,7 @@ Randomly index frames:
 
 Slice frames:
 ```python
->>> with gsd.hoomd.open('test.gsd', 'rb') as t:
+>>> with gsd.hoomd.open('test.gsd', 'r') as t:
 ... for s in t[5:-2]:
 ... print(s.configuration.step, end=' ')
 4 5 6 7
@@ -76,15 +76,15 @@ 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='w') 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));
  f.end_frame()
 ```
 
 ```python
-with gsd.fl.open(name='file.gsd', mode='rb') as f:
+with gsd.fl.open(name='file.gsd', mode='r') as f:
  for i in range(1,f.nframes):
  position = f.read_chunk(frame=i, name='position');
  do_something(position);

doc/fl-examples.rst

@@ -25,7 +25,7 @@ Open a gsd file
 .. ipython:: python
 
  f = gsd.fl.open(name="file.gsd",
- mode='wb',
+ mode='w',
  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='w',
  application="My application",
  schema="My Schema",
  schema_version=[1,0]);
@@ -90,7 +90,7 @@ Read data
 
 .. ipython:: python
 
- f = gsd.fl.open(name="file.gsd", mode='rb')
+ f = gsd.fl.open(name="file.gsd", mode='r')
  f.read_chunk(frame=0, name='chunk1')
  f.read_chunk(frame=1, name='chunk2')
  f.close()
@@ -103,7 +103,7 @@ Test if a chunk exists
 
 .. ipython:: python
 
- f = gsd.fl.open(name="file.gsd", mode='rb')
+ f = gsd.fl.open(name="file.gsd", mode='r')
  f.chunk_exists(frame=0, name='chunk1')
  f.chunk_exists(frame=1, name='chunk2')
  f.chunk_exists(frame=2, name='chunk1')
@@ -117,7 +117,7 @@ Discover chunk names
 
 .. ipython:: python
 
- f = gsd.fl.open(name="file.gsd", mode='rb')
+ f = gsd.fl.open(name="file.gsd", mode='r')
  f.find_matching_chunk_names('')
  f.find_matching_chunk_names('chunk')
  f.find_matching_chunk_names('chunk1')
@@ -132,7 +132,7 @@ Read-only access
 .. ipython:: python
  :okexcept:
 
- f = gsd.fl.open(name="file.gsd", mode='rb')
+ f = gsd.fl.open(name="file.gsd", mode='r')
  if f.chunk_exists(frame=0, name='chunk1'):
  data = f.read_chunk(frame=0, name='chunk1')
  data
@@ -147,7 +147,7 @@ Access file metadata
 
 .. ipython:: python
 
- f = gsd.fl.open(name="file.gsd", mode='rb')
+ f = gsd.fl.open(name="file.gsd", mode='r')
  f.name
  f.mode
  f.gsd_version
@@ -165,7 +165,7 @@ Open a file in read/write mode
 .. ipython:: python
 
  f = gsd.fl.open(name="file.gsd",
- mode='wb+',
+ mode='w',
  application="My application",
  schema="My Schema",
  schema_version=[1,0])
@@ -176,29 +176,12 @@ 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
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. ipython:: python
 
- with gsd.fl.open(name="file.gsd", mode='rb') as f:
+ with gsd.fl.open(name="file.gsd", mode='r') as f:
  data = f.read_chunk(frame=0, name='double');
  data
 
@@ -211,7 +194,7 @@ Store string chunks
 .. ipython:: python
 
  f = gsd.fl.open(name="file.gsd",
- mode='wb+',
+ mode='w',
  application="My application",
  schema="My Schema",
  schema_version=[1,0])
@@ -236,7 +219,7 @@ Truncate
 
 .. ipython:: python
 
- f = gsd.fl.open(name="file.gsd", mode='ab')
+ f = gsd.fl.open(name="file.gsd", mode='r+')
  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='w')
  @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='w')
  f.extend( (create_frame(i) for i in range(10)) )
  f.append( create_frame(10) )
  len(f)
@@ -80,7 +80,7 @@ Randomly index frames
 
 .. ipython:: python
 
- f = gsd.hoomd.open(name='example.gsd', mode='rb')
+ f = gsd.hoomd.open(name='example.gsd', mode='r')
  frame = f[5]
  frame.configuration.step
  frame.particles.N
@@ -99,7 +99,7 @@ trajectory.
 
 .. ipython:: python
 
- f = gsd.hoomd.open(name='example.gsd', mode='rb')
+ f = gsd.hoomd.open(name='example.gsd', mode='r')
 
  for frame in f[5:-2]:
  print(frame.configuration.step, end=' ')
@@ -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='w') 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='w') as f:
  frame = gsd.hoomd.Frame()
  frame.particles.N = 4
  frame.log['invalid'] = dict(a=1, b=5)
@@ -190,7 +190,7 @@ Use multiprocessing
  t, frame_idx = args
  return len(t[frame_idx].particles.position)
 
- with gsd.hoomd.open(name='example.gsd', mode='rb') as t:
+ with gsd.hoomd.open(name='example.gsd', mode='r') as t:
  with multiprocessing.Pool(processes=multiprocessing.cpu_count()) as pool:
  result = pool.map(count_particles, [(t, frame_idx) for frame_idx in range(len(t))])
 

doc/python-api.rst

@@ -11,7 +11,7 @@ Submodules
 ----------
 
 .. toctree::
- :maxdepth: 3
+ :maxdepth: 1
 
  python-module-gsd.fl
  python-module-gsd.hoomd

gsd/__main__.py

@@ -68,7 +68,7 @@ def main_read(args):
  })
  attributes.update({"Number of frames": len(traj)})
  else:
- if args.mode not in ['rb', 'rb+', 'ab']:
+ if args.mode not in ['rb', 'rb+', 'a', 'r', 'r+']:
  raise ValueError("Unsupported schema for creating a file.")
  handle = fl.open(args.file, args.mode)
  local_ns.update({
@@ -116,13 +116,25 @@ def main():
  default='hoomd',
  choices=['hoomd', 'none'],
  help="The file schema.")
- parser_read.add_argument(
- '-m',
- '--mode',
- type=str,
- default='rb',
- choices=['rb', 'rb+', 'wb', 'wb+', 'xb', 'xb+', 'ab'],
- help="The file mode.")
+ parser_read.add_argument('-m',
+ '--mode',
+ type=str,
+ default='r',
+ choices=[
+ 'rb',
+ 'rb+',
+ 'wb',
+ 'wb+',
+ 'xb',
+ 'xb+',
+ 'ab',
+ 'w',
+ 'r',
+ 'r+',
+ 'x',
+ 'a',
+ ],
+ help="The file mode.")
  parser_read.set_defaults(func=main_read)
 
  # This is a hack, as argparse itself does not