add deprecation warnings for API changes

package/CHANGELOG

@@ -15,19 +15,20 @@ The rules for this file:
 ------------------------------------------------------------------------------
 
 
-mm/dd/17 richardjgowers, rathann, jbarnoud
+mm/dd/17 richardjgowers, rathann, jbarnoud, orbeckst
 
   * 0.16.2
 
-Enhancements
+Deprecations
+  * deprecated core.Timeseries module for 0.17.0 (Issue #1383)
+  * deprecated instant selectors for 1.0 (Issue #1377)
+  * deprecated the core.flag registry for 1.0 (Issue #782)
 
 Fixes
   * fixed GROWriter truncating long resids from the wrong end (Issue #1395)
   * Fixed dtype of numpy arrays to accomodate 32 bit architectures (Issue #1362)
   * Groups are hashable on python 3 (Issue #1397)
 
-Changes
-
 
 06/03/17 utkbansal, kain88-de, xiki-tempula, kaplajon, wouterboomsma,
          richardjgowers, Shtkddud123, QuantumEntangledAndy, orbeckst,

package/MDAnalysis/__init__.py

@@ -143,7 +143,7 @@
 """
 from __future__ import absolute_import
 
-__all__ = ['Timeseries', 'Universe', 'as_Universe', 'Writer', 'collection',
+__all__ = ['Universe', 'as_Universe', 'Writer', 'collection',
            'fetch_mmtf']
 
 import logging
@@ -192,14 +192,46 @@
 from . import units
 
 # Bring some often used objects into the current namespace
-from .core import Timeseries
 from .core.universe import Universe, as_Universe, Merge
 from .coordinates.core import writer as Writer
 
 # After Universe import
 from .coordinates.MMTF import fetch_mmtf
 
-collection = Timeseries.TimeseriesCollection()
+# REMOVE in 0.17.0
+class _MockTimeseriesCollection(object):
+    """When accessed the first time, emit warning and raise NotImplementedError.
+
+    This breaks existing code that relies on MDAnalysis.collection by
+    replacing ::
+
+      collection = Timeseries.TimeseriesCollection()
+
+    with::
+
+      collection = _MockTimeseriesCollection()
+
+    """
+
+    def __getattr__(self, name):
+        self._warn_and_die()
+
+    def __getitem__(self, index):
+        self._warn_and_die()
+
+    def _warn_and_die(self):
+        import logging
+        msg = "collection = Timeseries.TimeseriesCollection() will be removed in 0.17.0\n" \
+              "and MDAnalysis.collection has been disabled. If you want to use it, \n" \
+              "instantiate a collection yourself:\n\n" \
+              "   from MDAnalysis.core.Timeseries import TimeseriesCollection\n" \
+              "   collection = TimeseriesCollection()\n\n" \
+              "Note that release 0.16.2 is the LAST RELEASE with TimeseriesCollection."
+        logging.getLogger("MDAnalysis").warn(msg)
+        warnings.warn(msg, DeprecationWarning)
+        raise NotImplementedError("TimeseriesCollection will be REMOVED IN THE NEXT RELEASE 0.17.0")
+collection = _MockTimeseriesCollection()
+del _MockTimeseriesCollection
 
 from .migration.ten2eleven import ten2eleven
 

package/MDAnalysis/coordinates/DCD.py

@@ -81,6 +81,7 @@
 import os
 import errno
 import numpy as np
+from numpy.lib.utils import deprecate
 import struct
 import types
 import warnings
@@ -578,37 +579,39 @@ def timeseries(self, asel=None, start=None, stop=None, step=None, skip=None,
         # XXX needs to be implemented
         return self._read_timeseries(atom_numbers, start, stop, step, format)
 
+    @deprecate(message="This method will be removed in 0.17")
     def correl(self, timeseries, start=None, stop=None, step=None, skip=None):
-        """Populate a :class:`~MDAnalysis.core.Timeseries.TimeseriesCollection` object
-        with time series computed from the trajectory.
-
-        Calling this method will iterate through the whole trajectory and
-        perform the calculations prescribed in `timeseries`.
-
-        Parameters
-        ----------
-        timeseries : :class:`MDAnalysis.core.Timeseries.TimeseriesCollection`
-             The :class:`MDAnalysis.core.Timeseries.TimeseriesCollection` that defines what kind
-             of computations should be performed on the data in this trajectory.
-        start :  int (optional)
-             Begin reading the trajectory at frame index `start` (where 0 is the index
-             of the first frame in the trajectory); the default ``None`` starts
-             at the beginning.
-        stop : int (optional)
-             End reading the trajectory at frame index `stop`-1, i.e, `stop` is excluded.
-             The trajectory is read to the end with the default ``None``.
-        step : int (optional)
-             Step size for reading; the default ``None`` is equivalent to 1 and means to
-             read every frame.
+        """
+Populate a :class:`~MDAnalysis.core.Timeseries.TimeseriesCollection` object
+with time series computed from the trajectory.
+
+Calling this method will iterate through the whole trajectory and
+perform the calculations prescribed in `timeseries`.
+
+Parameters
+----------
+timeseries : :class:`MDAnalysis.core.Timeseries.TimeseriesCollection`
+     The :class:`MDAnalysis.core.Timeseries.TimeseriesCollection` that defines what kind
+     of computations should be performed on the data in this trajectory.
+start :  int (optional)
+     Begin reading the trajectory at frame index `start` (where 0 is the index
+     of the first frame in the trajectory); the default ``None`` starts
+     at the beginning.
+stop : int (optional)
+     End reading the trajectory at frame index `stop`-1, i.e, `stop` is excluded.
+     The trajectory is read to the end with the default ``None``.
+step : int (optional)
+     Step size for reading; the default ``None`` is equivalent to 1 and means to
+     read every frame.
 
-        Note
-        ----
-        The `correl` functionality is only implemented for DCD trajectories and
-        the :class:`DCDReader`.
+Note
+----
+The `correl` functionality is only implemented for DCD trajectories and
+the :class:`DCDReader`.
 
 
-        .. deprecated:: 0.16.0
-           `skip` has been deprecated in favor of the standard keyword `step`.
+.. deprecated:: 0.16.0
+   `skip` has been deprecated in favor of the standard keyword `step`.
 
         """
         if skip is not None:

package/MDAnalysis/coordinates/__init__.py

@@ -538,10 +538,6 @@ class can choose an appropriate reader automatically.
  ``timeseries(atomGroup, [start[,stop[,skip[,format]]]])``
      returns a subset of coordinate data
 
- ``correl(timeseriesCollection[,start[,stop[,skip]]])``
-     populate a :class:`MDAnalysis.core.Timeseries.TimeseriesCollection` object
-     with observable timeseries computed from the trajectory
-
 
 Attributes
 ..........

package/MDAnalysis/coordinates/memory.py

@@ -106,6 +106,8 @@
     universe2 = mda.Universe(PSF, coordinates, format=MemoryReader, order='afc')
 
 
+.. _create-in-memory-trajectory-with-AnalysisFromFunction:
+
 .. rubric:: Creating an in-memory trajectory with
             :func:`~MDAnalysis.analysis.base.AnalysisFromFunction`