added READER_HINTS (#2533)

* added _READER_HINTS

allows Reader to interrogate object and return suitability

* added _TOPOLOGY_HINTS

Co-authored-by: Oliver Beckstein <[email protected]>

Author: richardjgowers

package/MDAnalysis/__init__.py

@@ -169,9 +169,11 @@
 # Registry of Readers, Parsers and Writers known to MDAnalysis
 # Metaclass magic fills these as classes are declared.
 _READERS = {}
+_READER_HINTS = {}
 _SINGLEFRAME_WRITERS = {}
 _MULTIFRAME_WRITERS = {}
 _PARSERS = {}
+_PARSER_HINTS = {}
 _SELECTION_WRITERS = {}
 _CONVERTERS = {}
 # Registry of TopologyAttributes

package/MDAnalysis/coordinates/MMTF.py

@@ -61,6 +61,14 @@ class MMTFReader(base.SingleFrameReaderBase):
     """Coordinate reader for the Macromolecular Transmission Format format (MMTF_)."""
     format = 'MMTF'
 
+    @staticmethod
+    def _format_hint(thing):
+        """Can this Reader read *thing*?
+
+        .. versionadded:: 1.0.0
+        """
+        return isinstance(thing, mmtf.MMTFDecoder)
+
     @due.dcite(
         Doi('10.1371/journal.pcbi.1005575'),
         description="MMTF Reader",

package/MDAnalysis/coordinates/ParmEd.py

@@ -87,6 +87,20 @@ class ParmEdReader(base.SingleFrameReaderBase):
     # Structure.coordinates always in Angstrom
     units = {'time': None, 'length': 'Angstrom'}
 
+    @staticmethod
+    def _format_hint(thing):
+        """Can this reader read *thing*?
+
+        .. versionadded:: 1.0.0
+        """
+        try:
+            import parmed as pmd
+        except ImportError:
+            # if we can't import parmed, it's probably not parmed
+            return False
+        else:
+            return isinstance(thing, pmd.Structure)
+
     def _read_first_frame(self):
         self.n_atoms = len(self.filename.atoms)
 

package/MDAnalysis/coordinates/__init__.py

@@ -279,30 +279,6 @@ class can choose an appropriate reader automatically.
 :mod:`MDAnalysis.coordinates.base`.
 
 
-History
-~~~~~~~
-
-- 2010-04-30 Draft [orbeckst]
-- 2010-08-20 added single frame writers to API [orbeckst]
-- 2010-10-09 added write() method to Writers [orbeckst]
-- 2010-10-19 use close() instead of close_trajectory() [orbeckst]
-- 2010-10-30 clarified Writer write() methods (see also `Issue 49`_)
-- 2011-02-01 extended call signature of Reader class
-- 2011-03-30 optional Writer() method for Readers
-- 2011-04-18 added time and frame managed attributes to Reader
-- 2011-04-20 added volume to Timestep
-- 2012-02-11 added _velocities to Timestep
-- 2012-05-24 multiframe keyword to distinguish trajectory from single frame writers
-- 2012-06-04 missing implementations of Reader.__getitem__ should raise :exc:`TypeError`
-- 2013-08-02 Readers/Writers must conform to the Python `Context Manager`_ API
-- 2015-01-15 Timestep._init_unitcell() method added
-- 2015-06-11 Reworked Timestep init.  Base Timestep now does Vels & Forces
-- 2015-07-21 Major changes to Timestep and Reader API (release 0.11.0)
-- 2016-04-03 Removed references to Strict Readers for PDBS [jdetle]
-
-.. _Issue 49: https://github.com/MDAnalysis/mdanalysis/issues/49
-.. _Context Manager: http://docs.python.org/2/reference/datamodel.html#context-managers
-
 Registry
 ~~~~~~~~
 
@@ -316,6 +292,13 @@ class can choose an appropriate reader automatically.
 defining the expected suffix.  To assign multiple suffixes to an I/O class, a
 list of suffixes can be given.
 
+In addition to this, a Reader may define a ``_format_hint`` staticmethod, which
+returns a boolean of if it can process a given object. E.g. the
+:class:`MDAnalysis.coordinates.memory.MemoryReader` identifies itself as
+capable of reading numpy arrays.  This functionality is used in
+:func:`MDAnalysis.core._get_readers.get_reader_for` when figuring out how to
+read an object (which was usually supplied to mda.Universe).
+
 To define that a Writer can write multiple trajectory frames, set the
 `multiframe` attribute to ``True``.  The default is ``False``.
 To define that a Writer *does not* support single frame writing the
@@ -489,6 +472,8 @@ class can choose an appropriate reader automatically.
  ``__exit__()``
      exit method of a `Context Manager`_, should call ``close()``.
 
+.. _Context Manager: http://docs.python.org/2/reference/datamodel.html#context-managers
+
 .. Note::
    a ``__del__()`` method should also be present to ensure that the
    trajectory is properly closed. However, certain types of Reader can ignore

package/MDAnalysis/coordinates/base.py

@@ -210,7 +210,7 @@
 from . import core
 from .. import NoDataError
 from .. import (
-    _READERS,
+    _READERS, _READER_HINTS,
     _SINGLEFRAME_WRITERS,
     _MULTIFRAME_WRITERS,
     _CONVERTERS
@@ -1362,6 +1362,11 @@ def __exit__(self, exc_type, exc_val, exc_tb):
 
 
 class _Readermeta(type):
+    """Automatic Reader registration metaclass
+
+    .. versionchanged:: 1.0.0
+       Added _format_hint functionality
+    """
     # Auto register upon class creation
     def __init__(cls, name, bases, classdict):
         type.__init__(type, name, bases, classdict)
@@ -1370,9 +1375,13 @@ def __init__(cls, name, bases, classdict):
         except KeyError:
             pass
         else:
-            for f in fmt:
-                f = f.upper()
-                _READERS[f] = cls
+            for fmt_name in fmt:
+                fmt_name = fmt_name.upper()
+                _READERS[fmt_name] = cls
+
+                if '_format_hint' in classdict:
+                    # isn't bound yet, so access __func__
+                    _READER_HINTS[fmt_name] = classdict['_format_hint'].__func__
 
 
 class ProtoReader(six.with_metaclass(_Readermeta, IOBase)):

package/MDAnalysis/coordinates/chain.py

@@ -52,6 +52,7 @@
 
 import numpy as np
 
+from ..lib import util
 from ..lib.util import asiterable
 from . import base
 from . import core
@@ -367,6 +368,16 @@ def __init__(self, filenames, skip=1, dt=None, continuous=False, **kwargs):
         self.ts = None
         self.rewind()
 
+    @staticmethod
+    def _format_hint(thing):
+        """Can ChainReader read the object *thing*
+
+        .. versionadded:: 1.0.0
+        """
+        return (not isinstance(thing, np.ndarray) and
+                util.iterable(thing) and
+                not util.isstream(thing))
+
     def _get_local_frame(self, k):
         """Find trajectory index and trajectory frame for chained frame `k`.
 

package/MDAnalysis/coordinates/memory.py

@@ -400,6 +400,14 @@ def __init__(self, coordinate_array, order='fac',
         self.ts.time = -1
         self._read_next_timestep()
 
+    @staticmethod
+    def _format_hint(thing):
+        """For internal use: Check if MemoryReader can operate on *thing*
+
+        .. versionadded:: 1.0.0
+        """
+        return isinstance(thing, np.ndarray)
+
     @staticmethod
     def parse_n_atoms(filename, order='fac', **kwargs):
         """Deduce number of atoms in a given array of coordinates

package/MDAnalysis/core/_get_readers.py

@@ -24,12 +24,10 @@
 
 import copy
 import inspect
-import mmtf
-import parmed as pmd
-import numpy as np
-from MDAnalysis.lib.util import isstream
 
-from .. import _READERS, _PARSERS, _MULTIFRAME_WRITERS, _SINGLEFRAME_WRITERS, _CONVERTERS
+from .. import (_READERS, _READER_HINTS,
+                _PARSERS, _PARSER_HINTS,
+                _MULTIFRAME_WRITERS, _SINGLEFRAME_WRITERS, _CONVERTERS)
 from ..lib import util
 
 
@@ -77,26 +75,23 @@ def get_reader_for(filename, format=None):
     :class:`~MDAnalysis.coordinates.chain.ChainReader` is returned and `format`
     passed to the :class:`~MDAnalysis.coordinates.chain.ChainReader`.
 
+    .. versionchanged:: 1.0.0
+       Added format_hint functionalityx
     """
     # check if format is actually a Reader
     if inspect.isclass(format):
         return format
 
     # ChainReader gets returned even if format is specified
-    if not isinstance(filename, np.ndarray) and util.iterable(filename) and not isstream(filename):
+    if _READER_HINTS['CHAIN'](filename):
         format = 'CHAIN'
     # Only guess if format is not specified
-    elif format is None:
-        # Checks for specialised formats
-        if isinstance(filename, np.ndarray):
-            # memoryreader slurps numpy arrays
-            format = 'MEMORY'
-        elif isinstance(filename, mmtf.MMTFDecoder):
-            # mmtf slurps mmtf object
-            format = 'MMTF'
-        elif isinstance(filename, pmd.Structure):
-            format = 'PARMED'
-        else:
+    if format is None:
+        for fmt_name, test in _READER_HINTS.items():
+            if test(filename):
+                format = fmt_name
+                break
+        else:  # hits else if for loop completes
             # else let the guessing begin!
             format = util.guess_format(filename)
     format = format.upper()
@@ -231,16 +226,18 @@ def get_parser_for(filename, format=None):
     ValueError
         If no appropriate parser could be found.
 
+    .. versionchanged:: 1.0.0
+       Added format_hint functionality
     """
     if inspect.isclass(format):
         return format
 
     # Only guess if format is not provided
     if format is None:
-        if isinstance(filename, mmtf.MMTFDecoder):
-            format = 'mmtf'
-        elif isinstance(filename, pmd.Structure):
-            format = 'PARMED'
+        for fmt_name, test in _PARSER_HINTS.items():
+            if test(filename):
+                format = fmt_name
+                break
         else:
             format = util.guess_format(filename)
     format = format.upper()
@@ -286,4 +283,4 @@ def get_converter_for(format):
     except KeyError:
         errmsg = 'No converter found for {} format'
         raise_from(TypeError(errmsg.format(format)), None)
-    return writer
+    return writer

package/MDAnalysis/topology/MMTFParser.py

@@ -152,6 +152,14 @@ def apply(self, group):
 class MMTFParser(base.TopologyReaderBase):
     format = 'MMTF'
 
+    @staticmethod
+    def _format_hint(thing):
+        """Can parser read *thing*?
+
+        .. versionadded:: 1.0.0
+        """
+        return isinstance(thing, mmtf.MMTFDecoder)
+
     @due.dcite(
         Doi('10.1371/journal.pcbi.1005575'),
         description="MMTF Parser",

package/MDAnalysis/topology/ParmEdParser.py

@@ -138,6 +138,19 @@ class ParmEdParser(TopologyReaderBase):
     """
     format = 'PARMED'
 
+    @staticmethod
+    def _format_hint(thing):
+        """Can this Parser read object *thing*?
+
+        .. versionadded:: 1.0.0
+        """
+        try:
+            import parmed as pmd
+        except ImportError:  # if no parmed, probably not parmed
+            return False
+        else:
+            return isinstance(thing, pmd.Structure)
+
     def parse(self, **kwargs):
         """Parse PARMED into Topology