deprecate Timestep argument to Writers (issue #2043)

- identified which Writers can currently use a ts (lots don't anyway)
- deprecated Timestep as argument to Writer.write
- Update package/MDAnalysis/coordinates/base.py
- Update package/MDAnalysis/coordinates/XYZ.py
- Update package/MDAnalysis/coordinates/GRO.py
- add test_writer_api.py
- removed obsolete test

package/MDAnalysis/coordinates/GRO.py

@@ -339,7 +339,7 @@ def write(self, obj):
 
         Parameters
         -----------
-        obj : AtomGroup or Universe or :class:`Timestep`
+        obj : AtomGroup or Universe
 
         Note
         ----
@@ -352,6 +352,8 @@ def write(self, obj):
            *resName* and *atomName* are truncated to a maximum of 5 characters
         .. versionchanged:: 0.16.0
            `frame` kwarg has been removed
+        .. versionchanged:: 0.19.1
+           Deprecated calling with Timestep, use AtomGroup or Universe
         """
         # write() method that complies with the Trajectory API
 
@@ -363,6 +365,10 @@ def write(self, obj):
 
         except AttributeError:
             if isinstance(obj, base.Timestep):
+                warnings.warn(
+                    'Passing a Timestep to write is deprecated, and will be removed in 1.0; '
+                    'use either an AtomGroup or Universe',
+                    DeprecationWarning)
                 ag_or_ts = obj.copy()
             else:
                 raise TypeError("No Timestep found in obj argument")

package/MDAnalysis/coordinates/XYZ.py

@@ -89,6 +89,7 @@
 import os
 import errno
 import numpy as np
+import warnings
 import logging
 logger = logging.getLogger('MDAnalysis.coordinates.XYZ')
 
@@ -202,6 +203,10 @@ def write(self, obj):
             atoms = obj.atoms
         except AttributeError:
             if isinstance(obj, base.Timestep):
+                warnings.warn(
+                    'Passing a Timestep to write is deprecated, and will be removed in 1.0; '
+                    'use either an AtomGroup or Universe',
+                    DeprecationWarning)
                 ts = obj
             else:
                 raise TypeError("No Timestep found in obj argument")

package/MDAnalysis/coordinates/base.py

@@ -2158,15 +2158,22 @@ def write(self, obj):
 
         Parameters
         ----------
-        obj : :class:`~MDAnalysis.core.groups.AtomGroup` or :class:`~MDAnalysis.core.universe.Universe` or a :class:`Timestep`
+        obj : :class:`~MDAnalysis.core.groups.AtomGroup` or :class:`~MDAnalysis.core.universe.Universe`
             write coordinate information associate with `obj`
 
         Note
         ----
         The size of the `obj` must be the same as the number of atoms provided
         when setting up the trajectory.
+
+        .. versionchanged:: 0.19.1
+           Deprecated the use of Timestep as arguments to write.  Use either a AtomGroup or Universe
         """
         if isinstance(obj, Timestep):
+            warnings.warn(
+                'Passing a Timestep to write is deprecated, and will be removed 1.0; '
+                'use either an AtomGroup or Universe',
+                DeprecationWarning)
             ts = obj
         else:
             try:
@@ -2177,7 +2184,7 @@ def write(self, obj):
                     ts = obj.trajectory.ts
                 except AttributeError:
                     raise TypeError("No Timestep found in obj argument")
-        return self.write_next_timestep(ts)
+        return self.write_next_timestep(obj)
 
     def __del__(self):
         self.close()

testsuite/MDAnalysisTests/coordinates/test_netcdf.py

@@ -474,11 +474,3 @@ def test_wrong_n_atoms(self, outfile):
             u = make_Universe(trajectory=True)
             with pytest.raises(IOError):
                 w.write(u.trajectory.ts)
-
-    def test_no_ts(self, outfile):
-        # no ts supplied at any point
-        from MDAnalysis.coordinates.TRJ import NCDFWriter
-
-        with NCDFWriter(outfile, 100) as w:
-            with pytest.raises(IOError):
-                w.write_next_timestep()

testsuite/MDAnalysisTests/coordinates/test_writer_api.py

@@ -0,0 +1,54 @@
+# -*- Mode: python; tab-width: 4; indent-tabs-mode:nil; coding:utf-8 -*-
+# vim: tabstop=4 expandtab shiftwidth=4 softtabstop=4 fileencoding=utf-8
+#
+# MDAnalysis --- https://www.mdanalysis.org
+# Copyright (c) 2006-2017 The MDAnalysis Development Team and contributors
+# (see the file AUTHORS for the full list of names)
+#
+# Released under the GNU Public Licence, v2 or any higher version
+#
+# Please cite your use of MDAnalysis in published work:
+#
+# R. J. Gowers, M. Linke, J. Barnoud, T. J. E. Reddy, M. N. Melo, S. L. Seyler,
+# D. L. Dotson, J. Domanski, S. Buchoux, I. M. Kenney, and O. Beckstein.
+# MDAnalysis: A Python package for the rapid analysis of molecular dynamics
+# simulations. In S. Benthall and S. Rostrup editors, Proceedings of the 15th
+# Python in Science Conference, pages 102-109, Austin, TX, 2016. SciPy.
+#
+# N. Michaud-Agrawal, E. J. Denning, T. B. Woolf, and O. Beckstein.
+# MDAnalysis: A Toolkit for the Analysis of Molecular Dynamics Simulations.
+# J. Comput. Chem. 32 (2011), 2319--2327, doi:10.1002/jcc.21787
+#
+from __future__ import absolute_import
+
+import itertools
+import pytest
+
+import MDAnalysis as mda
+
+
+# grab all known writers
+# sort so test order is predictable for parallel tests
+writers = sorted(set(mda._MULTIFRAME_WRITERS.values()) |
+                 set(mda._SINGLEFRAME_WRITERS.values()),
+                 key=lambda x: x.__name__)
+known_ts_haters = [
+    mda.coordinates.MOL2.MOL2Writer,
+    mda.coordinates.PDB.PDBWriter,
+    mda.coordinates.PDB.MultiPDBWriter,
+    mda.coordinates.PQR.PQRWriter,
+    mda.coordinates.PDBQT.PDBQTWriter,
+    mda.coordinates.LAMMPS.DATAWriter,
+    mda.coordinates.CRD.CRDWriter,
+]
+
+@pytest.mark.parametrize('writer', [w for w in writers
+                                    if not w in known_ts_haters])
+def test_ts_deprecated(writer, tmpdir):
+    u = mda.Universe.empty(10, trajectory=True)
+
+    fn = str(tmpdir.join('out.traj'))
+
+    with writer(fn, n_atoms=10) as w:
+        with pytest.warns(DeprecationWarning):
+            w.write(u.trajectory.ts)