Merge pull request #176 from stevenhua0320/deprecate-getParser

chore: deprecate getParser method across all parsers format.

Author: sbillinge

news/deprecate-getParser.rst

@@ -0,0 +1,39 @@
+**Added:**
+
+* Added ``get_parser`` method in ``p_auto.py``
+* Added ``get_parser`` method in ``p_cif.py``
+* Added ``get_parser`` method in ``p_discus.py``
+* Added ``get_parser`` method in ``p_pdb.py``
+* Added ``get_parser`` method in ``p_pdffit.py``
+* Added ``get_parser`` method in ``p_rawxyz.py``
+* Added ``get_parser`` method in ``p_xcfg.py``
+* Added ``get_parser`` method in ``p_xyz.py``
+* Added ``get_parser`` method in ``parsers/__init__.py``
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* Deprecated ``getParser`` method in ``p_auto.py`` for removal in version 4.0.0
+* Deprecated ``getParser`` method in ``p_cif.py`` for removal in version 4.0.0
+* Deprecated ``getParser`` method in ``p_discus.py`` for removal in version 4.0.0
+* Deprecated ``getParser`` method in ``p_pdb.py`` for removal in version 4.0.0
+* Deprecated ``getParser`` method in ``p_pdffit.py`` for removal in version 4.0.0
+* Deprecated ``getParser`` method in ``p_rawxyz.py`` for removal in version 4.0.0
+* Deprecated ``getParser`` method in ``p_xcfg.py`` for removal in version 4.0.0
+* Deprecated ``getParser`` method in ``p_xyz.py`` for removal in version 4.0.0
+* Deprecated ``getParser`` method in ``parsers/__init__.py`` for removal in version 4.0.0
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/structure/__init__.py

@@ -39,7 +39,7 @@
 import diffpy.structure as _structure
 from diffpy.structure.atom import Atom
 from diffpy.structure.lattice import Lattice
-from diffpy.structure.parsers import getParser
+from diffpy.structure.parsers import get_parser
 from diffpy.structure.pdffitstructure import PDFFitStructure
 from diffpy.structure.structure import Structure
 from diffpy.structure.structureerrors import LatticeError, StructureFormatError, SymmetryError
@@ -97,7 +97,7 @@ def loadStructure(filename, fmt="auto", **kw):
         and 'discus' formats.
     """
 
-    p = getParser(fmt, **kw)
+    p = get_parser(fmt, **kw)
     rv = p.parse_file(filename)
     return rv
 

src/diffpy/structure/parsers/__init__.py

@@ -33,14 +33,48 @@
 from diffpy.structure.parsers.parser_index_mod import parser_index
 from diffpy.structure.parsers.structureparser import StructureParser
 from diffpy.structure.structureerrors import StructureFormatError
+from diffpy.utils._deprecator import build_deprecation_message, deprecated
 
 # silence pyflakes checker
 assert StructureParser
 
+parsers_base = "diffpy.structure"
+removal_version = "4.0.0"
+getParser_deprecation_msg = build_deprecation_message(
+    parsers_base,
+    "getParser",
+    "get_parser",
+    removal_version,
+)
 
+
+@deprecated(getParser_deprecation_msg)
 def getParser(format, **kw):
     """Return Parser instance for a given structure format.
 
+    Parameters
+    ----------
+    format : str
+        String with the format name, see `parser_index_mod`.
+    **kw : dict
+        Keyword arguments passed to the Parser init function.
+
+    Returns
+    -------
+    Parser
+        Parser instance for the given format.
+
+    Raises
+    ------
+    StructureFormatError
+        When the format is not defined.
+    """
+    return get_parser(format, **kw)
+
+
+def get_parser(format, **kw):
+    """Return Parser instance for a given structure format.
+
     Parameters
     ----------
     format : str
@@ -65,7 +99,7 @@ def getParser(format, **kw):
     ns = {}
     import_cmd = "from diffpy.structure.parsers import %s as pm" % pmod
     exec(import_cmd, ns)
-    return ns["pm"].getParser(**kw)
+    return ns["pm"].get_parser(**kw)
 
 
 def inputFormats():

src/diffpy/structure/parsers/p_auto.py

@@ -206,14 +206,14 @@ def _wrap_parse_method(self, method: object, *args: object, **kwargs: object) ->
         ------
         StructureFormatError
         """
-        from diffpy.structure.parsers import getParser
+        from diffpy.structure.parsers import get_parser
 
         ofmts = self._get_ordered_formats()
         stru = None
         # try all parsers in sequence
         parsers_emsgs = []
         for fmt in ofmts:
-            p = getParser(fmt, **self.pkw)
+            p = get_parser(fmt, **self.pkw)
             try:
                 pmethod = getattr(p, method)
                 stru = pmethod(*args, **kwargs)
@@ -240,10 +240,36 @@ def _wrap_parse_method(self, method: object, *args: object, **kwargs: object) ->
 
 # Routines -------------------------------------------------------------------
 
+parsers_base = "diffpy.structure"
+removal_version = "4.0.0"
+getParser_deprecation_msg = build_deprecation_message(
+    parsers_base,
+    "getParser",
+    "get_parser",
+    removal_version,
+)
 
+
+@deprecated(getParser_deprecation_msg)
 def getParser(**kw):
     """Return a new instance of the automatic parser.
 
+    Parameters
+    ----------
+    **kw : dict
+        Keyword arguments for the structure parser
+
+    Returns
+    -------
+    P_auto
+        Instance of `P_auto`.
+    """
+    return get_parser(**kw)
+
+
+def get_parser(**kw):
+    """Return a new instance of the automatic parser.
+
     Parameters
     ----------
     **kw : dict

src/diffpy/structure/parsers/p_cif.py

@@ -817,6 +817,13 @@ def to_lines(self, stru):
 
 # Routines -------------------------------------------------------------------
 
+parsers_base = "diffpy.structure"
+getParser_deprecation_msg = build_deprecation_message(
+    parsers_base,
+    "getParser",
+    "get_parser",
+    removal_version,
+)
 # constant regular expression for leading_float()
 rx_float = re.compile(r"[-+]?(\d+(\.\d*)?|\.\d+)([eE][-+]?\d+)?")
 
@@ -901,9 +908,27 @@ def getSymOp(s):
     return rv
 
 
+@deprecated(getParser_deprecation_msg)
 def getParser(eps=None):
     """Return new `parser` object for CIF format.
 
+    Parameters
+    ----------
+    eps : float, Optional
+        fractional coordinates cutoff for duplicate positions.
+        When ``None`` use the default for `ExpandAsymmetricUnit`: ``1.0e-5``.
+
+    Returns
+    -------
+    P_cif
+        Instance of `P_cif`.
+    """
+    return get_parser(eps)
+
+
+def get_parser(eps=None):
+    """Return new `parser` object for CIF format.
+
     Parameters
     ----------
     eps : float, Optional

src/diffpy/structure/parsers/p_discus.py

@@ -412,10 +412,31 @@ def _parse_not_implemented(self, words):
 
 # Routines -------------------------------------------------------------------
 
+parsers_base = "diffpy.structure"
+removal_version = "4.0.0"
+getParser_deprecation_msg = build_deprecation_message(
+    parsers_base,
+    "getParser",
+    "get_parser",
+    removal_version,
+)
+
 
+@deprecated(getParser_deprecation_msg)
 def getParser():
     """Return new `parser` object for DISCUS format.
 
+    Returns
+    -------
+    P_discus
+        Instance of `P_discus`.
+    """
+    return get_parser()
+
+
+def get_parser():
+    """Return new `parser` object for DISCUS format.
+
     Returns
     -------
     P_discus

src/diffpy/structure/parsers/p_pdb.py

@@ -454,10 +454,30 @@ def to_lines(self, stru):
 
 # Routines -------------------------------------------------------------------
 
+parsers_base = "diffpy.structure"
+getParser_deprecation_msg = build_deprecation_message(
+    parsers_base,
+    "getParser",
+    "get_parser",
+    removal_version,
+)
+
 
+@deprecated(getParser_deprecation_msg)
 def getParser():
     """Return new `parser` object for PDB format.
 
+    Returns
+    -------
+    P_pdb
+        Instance of `P_pdb`.
+    """
+    return get_parser()
+
+
+def get_parser():
+    """Return new `parser` object for PDB format.
+
     Returns
     -------
     P_pdb

src/diffpy/structure/parsers/p_pdffit.py

@@ -388,6 +388,17 @@ def _parse_shape(self, line):
 def getParser():
     """Return new `parser` object for PDFfit format.
 
+    Returns
+    -------
+    P_pdffit
+        Instance of `P_pdffit`.
+    """
+    return get_parser()
+
+
+def get_parser():
+    """Return new `parser` object for PDFfit format.
+
     Returns
     -------
     P_pdffit

src/diffpy/structure/parsers/p_rawxyz.py

@@ -170,10 +170,30 @@ def to_lines(self, stru):
 
 # Routines -------------------------------------------------------------------
 
+parsers_base = "diffpy.structure"
+getParser_deprecation_msg = build_deprecation_message(
+    parsers_base,
+    "getParser",
+    "get_parser",
+    removal_version,
+)
+
 
+@deprecated(getParser_deprecation_msg)
 def getParser():
     """Return new `parser` object for RAWXYZ format.
 
+    Returns
+    -------
+    P_rawxyz
+        Instance of `P_rawxyz`.
+    """
+    return get_parser()
+
+
+def get_parser():
+    """Return new `parser` object for RAWXYZ format.
+
     Returns
     -------
     P_rawxyz

src/diffpy/structure/parsers/p_xcfg.py

@@ -447,10 +447,30 @@ def to_lines(self, stru):
 
 # Routines -------------------------------------------------------------------
 
+parsers_base = "diffpy.structure"
+getParser_deprecation_msg = build_deprecation_message(
+    parsers_base,
+    "getParser",
+    "get_parser",
+    removal_version,
+)
+
 
+@deprecated(getParser_deprecation_msg)
 def getParser():
     """Return new `parser` object for XCFG format.
 
+    Returns
+    -------
+    P_xcfg
+        Instance of `P_xcfg`.
+    """
+    return get_parser()
+
+
+def get_parser():
+    """Return new `parser` object for XCFG format.
+
     Returns
     -------
     P_xcfg