Converters API

package/MDAnalysis/converters/__init__.py

@@ -0,0 +1 @@
+from . import accessors

package/MDAnalysis/converters/accessors.py

@@ -0,0 +1,187 @@
+# -*- 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.
+# doi: 10.25080/majora-629e541a-00e
+#
+# 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
+#
+
+"""AtomGroup accessors --- :mod:`MDAnalysis.lib.accessors`
+=============================================================
+
+The aim of this module is simply to link a wrapper class to an object in order
+to avoid cluttering the namespace of the object.
+
+Example
+-------
+
+.. code-block:: python
+
+    >>> class SpeechWrapper:
+    ...     def __init__(self, person):
+    ...         self.person = person
+    ...     def __call__(self, *args):
+    ...         print(self.person.name, "says", *args)
+    ...     def whoami(self):
+    ...         print("I am %s" % self.person.name)
+    ...
+    >>> class Person:
+    ...     def __init__(self, name):
+    ...         self.name = name
+    ...     say = Accessor(SpeechWrapper)
+    ...
+    >>> bob = Person("Bob")
+    >>> bob.say("hello")
+    Bob says hello
+    >>> bob.say.whoami()
+    I am Bob
+
+"""
+
+from functools import partial, update_wrapper
+
+from .. import _CONVERTERS
+
+
+class Accessor:
+    """Used to pass data between two classes
+
+    Parameters
+    ----------
+    name : str
+        Name of the property in the parent class
+    accessor : class
+        A class that needs access to its parent's instance
+
+    Example
+    -------
+    If you want the property to be named "convert_to" in the AtomGroup class,
+    use:
+
+    .. code-block:: python
+
+        >>> class AtomGroup:
+        >>>     # ...
+        >>>     convert_to = Accessor("convert_to", ConverterWrapper)
+
+    And when calling ``ag.convert_to.rdkit()``, the "rdkit" method of the
+    ConverterWrapper will be able to have access to "ag"
+    """
+
+    def __init__(self, name, accessor):
+        self._accessor = accessor
+        self._name = name
+
+    def __get__(self, obj, cls):
+        # instances the accessor class with the parent object as argument
+        wrapped = self._accessor(obj)
+        # replace the parent object's property with the wrapped instance
+        # so we avoid reinstantiating the accessor everytime `obj.<_name>`
+        # is called
+        object.__setattr__(obj, self._name, wrapped)
+        return wrapped
+
+
+class ConverterWrapper:
+    """Convert :class:`AtomGroup` to a structure from another Python
+    package.
+
+    The converters are accessible to any AtomGroup through the ``convert_to``
+    property. `ag.convert_to` will return this ConverterWrapper, which can be
+    called directly with the name of the destination package as a string
+    (similarly to the old API), or through custom methods named after the
+    package (in lowercase) that are automatically constructed thanks to
+    metaclass magic.
+
+    Example
+    -------
+    The code below converts a Universe to a :class:`parmed.structure.Structure`.
+
+    .. code-block:: python
+
+        >>> import MDAnalysis as mda
+        >>> from MDAnalysis.tests.datafiles import GRO
+        >>> u = mda.Universe(GRO)
+        >>> parmed_structure = u.atoms.convert_to('PARMED')
+        >>> parmed_structure
+        <Structure 47681 atoms; 11302 residues; 0 bonds; PBC (triclinic); NOT parametrized>
+
+    You can also directly use ``u.atoms.convert_to.parmed()``
+
+    Parameters
+    ----------
+    package: str
+        The name of the package to convert to, e.g. ``"PARMED"``
+    *args:
+        Positional arguments passed to the converter
+    **kwargs:
+        Keyword arguments passed to the converter
+
+    Returns
+    -------
+    output:
+        An instance of the structure type from another package.
+
+    Raises
+    ------
+    TypeError:
+        No converter was found for the required package
+
+
+    .. versionadded:: 1.0.0
+    .. versionchanged:: 2.0.0
+        Moved the ``convert_to`` method to its own class. The old API is still
+        available and is now case-insensitive to package names, it also accepts
+        positional and keyword arguments. Each converter function can also
+        be accessed as a method with the name of the package in lowercase, i.e.
+        `convert_to.parmed()`
+    """
+    _CONVERTERS = {}
+
+    def __init__(self, ag):
+        """
+        Parameters
+        ----------
+        ag : AtomGroup
+            The AtomGroup to convert
+        """
+        self._ag = ag
+        for lib, converter_cls in _CONVERTERS.items():
+            method_name = lib.lower()
+            # makes sure we always use the same instance of the converter
+            # no matter which atomgroup instance called it
+            try:
+                converter = self._CONVERTERS[method_name]
+            except KeyError:
+                converter = converter_cls().convert
+                # store in class attribute
+                self._CONVERTERS[method_name] = converter
+            # create partial function that passes ag to the converter
+            convert = partial(converter, self._ag)
+            # copy docstring and metadata to the partial function
+            # note: it won't work with help()
+            update_wrapper(convert, converter)
+            setattr(self, method_name, convert)
+
+    def __call__(self, package, *args, **kwargs):
+        try:
+            convert = getattr(self, package.lower())
+        except AttributeError:
+            raise TypeError(f"No {package!r} converter found. Available: "
+                            f"{' '.join(self._CONVERTERS.keys())}") from None
+        return convert(*args, **kwargs)

package/MDAnalysis/core/groups.py

@@ -103,6 +103,7 @@
 from ..lib import distances
 from ..lib import transformations
 from ..lib import mdamath
+from ..converters.accessors import Accessor, ConverterWrapper
 from ..selections import get_writer as get_selection_writer_for
 from . import selection
 from ..exceptions import NoDataError
@@ -3146,46 +3147,7 @@ def cmap(self):
                 "cmap only makes sense for a group with exactly 5 atoms")
         return topologyobjects.CMap(self.ix, self.universe)
 
-    def convert_to(self, package):
-        """
-        Convert :class:`AtomGroup` to a structure from another Python package.
-
-        Example
-        -------
-
-        The code below converts a Universe to a :class:`parmed.structure.Structure`.
-
-        .. code-block:: python
-
-            >>> import MDAnalysis as mda
-            >>> from MDAnalysis.tests.datafiles import GRO
-            >>> u = mda.Universe(GRO)
-            >>> parmed_structure = u.atoms.convert_to('PARMED')
-            >>> parmed_structure
-            <Structure 47681 atoms; 11302 residues; 0 bonds; PBC (triclinic); NOT parametrized>
-
-
-        Parameters
-        ----------
-        package: str
-            The name of the package to convert to, e.g. ``"PARMED"``
-
-
-        Returns
-        -------
-        output:
-            An instance of the structure type from another package.
-
-        Raises
-        ------
-        TypeError:
-            No converter was found for the required package
-
-
-        .. versionadded:: 1.0.0
-        """
-        converter = get_converter_for(package)
-        return converter().convert(self.atoms)
+    convert_to = Accessor("convert_to", ConverterWrapper)
 
     def write(self, filename=None, file_format=None,
               filenamefmt="{trjname}_{frame}", frames=None, **kwargs):

testsuite/MDAnalysisTests/converters/test_accessors.py

@@ -0,0 +1,50 @@
+# -*- 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.
+# doi: 10.25080/majora-629e541a-00e
+#
+# 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
+#
+import pytest
+import MDAnalysis as mda
+from MDAnalysisTests.util import import_not_available
+
+
+requires_rdkit = pytest.mark.skipif(import_not_available("rdkit"),
+                                    reason="requires RDKit")
+
+
+@requires_rdkit
+class TestConvertTo:
+    @pytest.fixture(scope="class")
+    def u(self):
+        return mda.Universe.from_smiles("CCO")
+
+    def test_convert_to_case_insensitive(self, u):
+        mol = u.atoms.convert_to("rdkit")
+
+    def test_convert_to_lib_as_method(self, u):
+        mol = u.atoms.convert_to.rdkit()
+
+    def test_convert_to_kwargs(self, u):
+        mol = u.atoms.convert_to("RDKIT", NoImplicit=False)
+        assert mol.GetAtomWithIdx(0).GetNoImplicit() is False
+
+    def test_convert_to_lib_method_kwargs(self, u):
+        mol = u.atoms.convert_to.rdkit(NoImplicit=False)
+        assert mol.GetAtomWithIdx(0).GetNoImplicit() is False