chore: deprecate parseLines method in all parsers

news/deprecate-parser-1.rst

@@ -0,0 +1,40 @@
+**Added:**
+
+* Added ``parse_lines`` method in ``p_auto.py``
+* Added ``parse_lines`` method in ``p_cif.py``
+* Added ``parse_lines`` method in ``p_discus.py``
+* Added ``parse_lines`` method in ``p_pdb.py``
+* Added ``parse_lines`` method in ``p_pdffit.py``
+* Added ``parse_lines`` method in ``p_rawxyz.py``
+* Added ``parse_lines`` method in ``p_xcfg.py``
+* Added ``parse_lines`` method in ``p_xyz.py``
+* Added ``parse_lines`` method in ``structureparser.py``
+* Added ``_suppress_cif_parser_output`` method in ``p_cif.py``
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* Deprecated ``parseLines`` method in ``p_auto.py`` for removal in version 4.0.0
+* Deprecated ``parseLines`` method in ``p_cif.py`` for removal in version 4.0.0
+* Deprecated ``parseLines`` method in ``p_discus.py`` for removal in version 4.0.0
+* Deprecated ``parseLines`` method in ``p_pdb.py`` for removal in version 4.0.0
+* Deprecated ``parseLines`` method in ``p_pdffit.py`` for removal in version 4.0.0
+* Deprecated ``parseLines`` method in ``p_rawxyz.py`` for removal in version 4.0.0
+* Deprecated ``parseLines`` method in ``p_xcfg.py`` for removal in version 4.0.0
+* Deprecated ``parseLines`` method in ``p_xyz.py`` for removal in version 4.0.0
+* Deprecated ``parseLines`` method in ``structureparser.py`` for removal in version 4.0.0
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/structure/parsers/p_auto.py

@@ -18,9 +18,20 @@
 """
 
 import os
+from typing import Any
 
 from diffpy.structure.parsers import StructureParser, parser_index
 from diffpy.structure.structureerrors import StructureFormatError
+from diffpy.utils._deprecator import build_deprecation_message, deprecated
+
+base = "diffpy.structure.P_auto"
+removal_version = "4.0.0"
+parseLines_deprecation_msg = build_deprecation_message(
+    base,
+    "parseLines",
+    "parse_lines",
+    removal_version,
+)
 
 
 class P_auto(StructureParser):
@@ -76,7 +87,16 @@ def _get_ordered_formats(self):
                 ofmts.insert(0, fmt)
         return ofmts
 
+    @deprecated(parseLines_deprecation_msg)
     def parseLines(self, lines):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.P_auto.parse_lines instead.
+        """
+        return self.parse_lines(lines)
+
+    def parse_lines(self, lines):
         """Detect format and create `Structure` instance from a list of
         lines.
 
@@ -96,7 +116,7 @@ def parseLines(self, lines):
         ------
         StructureFormatError
         """
-        return self._wrap_parse_method("parseLines", lines)
+        return self._wrap_parse_method("parse_lines", lines)
 
     def parse(self, s):
         """Detect format and create `Structure` instance from a string.
@@ -145,7 +165,7 @@ def parseFile(self, filename):
         self.filename = filename
         return self._wrap_parse_method("parseFile", filename)
 
-    def _wrap_parse_method(self, method, *args, **kwargs):
+    def _wrap_parse_method(self, method: object, *args: object, **kwargs: object) -> Any:
         """A helper evaluator method that try the specified parse method
         with each registered structure parser and return the first
         successful result.

src/diffpy/structure/parsers/p_cif.py

@@ -37,10 +37,21 @@
 from diffpy.structure import Atom, Lattice, Structure
 from diffpy.structure.parsers import StructureParser
 from diffpy.structure.structureerrors import StructureFormatError
+from diffpy.utils._deprecator import build_deprecation_message, deprecated
 
 # ----------------------------------------------------------------------------
 
 
+base = "diffpy.structure.P_cif"
+removal_version = "4.0.0"
+parseLines_deprecation_msg = build_deprecation_message(
+    base,
+    "parseLines",
+    "parse_lines",
+    removal_version,
+)
+
+
 class P_cif(StructureParser):
     """Simple parser for CIF structure format.
 
@@ -330,7 +341,17 @@ def parse(self, s):
         rv = self._parseCifDataSource(fp)
         return rv
 
+    @deprecated(parseLines_deprecation_msg)
     def parseLines(self, lines):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.P_cif.parse_lines instead.
+        """
+        return self.parse_lines(lines)
+
+    @deprecated(parseLines_deprecation_msg)
+    def parse_lines(self, lines):
         """Parse list of lines in CIF format.
 
         Parameters
@@ -400,7 +421,7 @@ def _parseCifDataSource(self, datasource):
 
         self.stru = None
         try:
-            with _suppressCifParserOutput():
+            with _suppress_cif_parser_output():
                 # Use `grammar` option to digest values with curly-brackets.
                 # Ref: https://bitbucket.org/jamesrhester/pycifrw/issues/19
                 self.ciffile = CifFile(datasource, grammar="auto")
@@ -871,7 +892,7 @@ def getParser(eps=None):
 
 
 @contextmanager
-def _suppressCifParserOutput():
+def _suppress_cif_parser_output():
     """Context manager which suppresses diagnostic messages from CIF
     parser."""
     from CifFile import yapps3_compiled_rt

src/diffpy/structure/parsers/p_discus.py

@@ -134,6 +134,81 @@ def parseLines(self, lines):
             raise e.with_traceback(exc_traceback)
         return self.stru
 
+    def parse_lines(self, lines):
+        """Parse list of lines in DISCUS format.
+
+        Parameters
+        ----------
+        lines : list of str
+            List of lines from the input file.
+
+        Returns
+        -------
+        PDFFitStructure
+            Parsed `PDFFitStructure` instance.
+
+        Raises
+        ------
+        StructureFormatError
+            If the file is not in DISCUS format.
+        """
+        self.lines = lines
+        ilines = self._linesIterator()
+        self.stru = PDFFitStructure()
+        record_parsers = {
+            "cell": self._parse_cell,
+            "format": self._parse_format,
+            "generator": self._parse_not_implemented,
+            "molecule": self._parse_not_implemented,
+            "ncell": self._parse_ncell,
+            "spcgr": self._parse_spcgr,
+            "symmetry": self._parse_not_implemented,
+            "title": self._parse_title,
+            "shape": self._parse_shape,
+        }
+        try:
+            # parse header
+            for self.line in ilines:
+                words = self.line.split()
+                if not words or words[0][0] == "#":
+                    continue
+                if words[0] == "atoms":
+                    break
+                rp = record_parsers.get(words[0], self._parse_unknown_record)
+                rp(words)
+            # check if cell has been defined
+            if not self.cell_read:
+                emsg = "%d: unit cell not defined" % self.nl
+                raise StructureFormatError(emsg)
+            # parse atoms
+            for self.line in ilines:
+                words = self.line.replace(",", " ").split()
+                if not words or words[0][0] == "#":
+                    continue
+                self._parse_atom(words)
+            # self consistency check
+            exp_natoms = reduce(lambda x, y: x * y, self.stru.pdffit["ncell"])
+            # only check if ncell record exists
+            if self.ncell_read and exp_natoms != len(self.stru):
+                emsg = "Expected %d atoms, read %d." % (
+                    exp_natoms,
+                    len(self.stru),
+                )
+                raise StructureFormatError(emsg)
+            # take care of superlattice
+            if self.stru.pdffit["ncell"][:3] != [1, 1, 1]:
+                latpars = list(self.stru.lattice.abcABG())
+                superlatpars = [latpars[i] * self.stru.pdffit["ncell"][i] for i in range(3)] + latpars[3:]
+                superlattice = Lattice(*superlatpars)
+                self.stru.place_in_lattice(superlattice)
+                self.stru.pdffit["ncell"] = [1, 1, 1, exp_natoms]
+        except (ValueError, IndexError):
+            exc_type, exc_value, exc_traceback = sys.exc_info()
+            emsg = "%d: file is not in DISCUS format" % self.nl
+            e = StructureFormatError(emsg)
+            raise e.with_traceback(exc_traceback)
+        return self.stru
+
     def toLines(self, stru):
         """Convert `Structure` stru to a list of lines in DISCUS format.
 

src/diffpy/structure/parsers/p_pdb.py

@@ -29,6 +29,16 @@
 from diffpy.structure import Structure
 from diffpy.structure.parsers import StructureParser
 from diffpy.structure.structureerrors import StructureFormatError
+from diffpy.utils._deprecator import build_deprecation_message, deprecated
+
+base = "diffpy.structure.P_pdb"
+removal_version = "4.0.0"
+parseLines_deprecation_msg = build_deprecation_message(
+    base,
+    "parseLines",
+    "parse_lines",
+    removal_version,
+)
 
 
 class P_pdb(StructureParser):
@@ -111,7 +121,16 @@ def __init__(self):
         self.format = "pdb"
         return
 
+    @deprecated(parseLines_deprecation_msg)
     def parseLines(self, lines):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.P_pdb.parse_lines instead.
+        """
+        return self.parse_lines(lines)
+
+    def parse_lines(self, lines):
         """Parse list of lines in PDB format.
 
         Parameters

src/diffpy/structure/parsers/p_pdffit.py

@@ -22,6 +22,16 @@
 from diffpy.structure import Lattice, PDFFitStructure
 from diffpy.structure.parsers import StructureParser
 from diffpy.structure.structureerrors import StructureFormatError
+from diffpy.utils._deprecator import build_deprecation_message, deprecated
+
+base = "diffpy.structure.P_pdffit"
+removal_version = "4.0.0"
+parseLines_deprecation_msg = build_deprecation_message(
+    base,
+    "parseLines",
+    "parse_lines",
+    removal_version,
+)
 
 
 class P_pdffit(StructureParser):
@@ -44,7 +54,16 @@ def __init__(self):
         self.stru = None
         return
 
+    @deprecated(parseLines_deprecation_msg)
     def parseLines(self, lines):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.P_pdffit.parse_lines instead.
+        """
+        return self.parse_lines(lines)
+
+    def parse_lines(self, lines):
         """Parse list of lines in PDFfit format.
 
         Parameters

src/diffpy/structure/parsers/p_rawxyz.py

@@ -24,6 +24,16 @@
 from diffpy.structure.parsers import StructureParser
 from diffpy.structure.structureerrors import StructureFormatError
 from diffpy.structure.utils import isfloat
+from diffpy.utils._deprecator import build_deprecation_message, deprecated
+
+base = "diffpy.structure.P_rawxyz"
+removal_version = "4.0.0"
+parseLines_deprecation_msg = build_deprecation_message(
+    base,
+    "parseLines",
+    "parse_lines",
+    removal_version,
+)
 
 
 class P_rawxyz(StructureParser):
@@ -40,7 +50,16 @@ def __init__(self):
         self.format = "rawxyz"
         return
 
+    @deprecated(parseLines_deprecation_msg)
     def parseLines(self, lines):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.P_rawxyz.parse_lines instead.
+        """
+        return self.parse_lines(lines)
+
+    def parse_lines(self, lines):
         """Parse list of lines in RAWXYZ format.
 
         Parameters

src/diffpy/structure/parsers/p_xcfg.py

@@ -29,6 +29,7 @@
 from diffpy.structure.parsers import StructureParser
 from diffpy.structure.structureerrors import StructureFormatError
 from diffpy.structure.utils import isfloat
+from diffpy.utils._deprecator import build_deprecation_message, deprecated
 
 # Constants ------------------------------------------------------------------
 
@@ -151,6 +152,15 @@
 
 # ----------------------------------------------------------------------------
 
+base = "diffpy.structure.P_xcfg"
+removal_version = "4.0.0"
+parseLines_deprecation_msg = build_deprecation_message(
+    base,
+    "parseLines",
+    "parse_lines",
+    removal_version,
+)
+
 
 class P_xcfg(StructureParser):
     """Parser for AtomEye extended CFG format.
@@ -171,7 +181,16 @@ def __init__(self):
         self.format = "xcfg"
         return
 
+    @deprecated(parseLines_deprecation_msg)
     def parseLines(self, lines):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.P_xcfg.parse_lines instead.
+        """
+        return self.parse_lines(lines)
+
+    def parse_lines(self, lines):
         """Parse list of lines in XCFG format.
 
         Parameters