chore: deprecate toLines method across of parsers

news/deprecate-toLine.rst

@@ -0,0 +1,38 @@
+**Added:**
+
+* Added ``_parse_cif_data_source`` method in ``p_cif.py``
+* Added ``_parse_cif_block`` method in ``p_cif.py``
+* Added ``to_lines`` method in ``p_cif.py``
+* Added ``to_lines`` method in ``p_pdb.py``
+* Added ``to_lines`` method in ``p_rawxyz.py``
+* Added ``to_lines`` method in ``p_xcfg.py``
+* Added ``to_lines`` method in ``p_xyz.py``
+* Added ``to_lines`` method in ``structureparser.py``
+* Added ``_lines_iterator`` method in ``p_discus.py``
+* Added ``to_lines`` method in ``p_discus.py``
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* Deprecated ``toLines`` method in ``p_cif.py`` for removal in version 4.0.0
+* Deprecated ``toLines`` method in ``p_pdb.py`` for removal in version 4.0.0
+* Deprecated ``toLines`` method in ``p_rawxyz.py`` for removal in version 4.0.0
+* Deprecated ``toLines`` method in ``p_xcfg.py`` for removal in version 4.0.0
+* Deprecated ``toLines`` method in ``p_xyz.py`` for removal in version 4.0.0
+* Deprecated ``toLines`` method in ``structureparser.py`` for removal in version 4.0.0
+* Deprecated ``toLines`` method in ``p_discus.py`` for removal in version 4.0.0
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/structure/parsers/p_cif.py

@@ -56,6 +56,12 @@
     "parse_file",
     removal_version,
 )
+toLines_deprecation_msg = build_deprecation_message(
+    base,
+    "toLines",
+    "to_lines",
+    removal_version,
+)
 
 
 class P_cif(StructureParser):
@@ -344,7 +350,7 @@ def parse(self, s):
         self.ciffile = None
         self.filename = ""
         fp = io.StringIO(s)
-        rv = self._parseCifDataSource(fp)
+        rv = self._parse_cif_data_source(fp)
         return rv
 
     @deprecated(parseLines_deprecation_msg)
@@ -409,11 +415,11 @@ def parse_file(self, filename):
         """
         self.ciffile = None
         self.filename = filename
-        rv = self._parseCifDataSource(filename)
+        rv = self._parse_cif_data_source(filename)
         # all good here
         return rv
 
-    def _parseCifDataSource(self, datasource):
+    def _parse_cif_data_source(self, datasource):
         """Open and process CIF data from the specified `datasource`.
 
         Parameters
@@ -441,7 +447,7 @@ def _parseCifDataSource(self, datasource):
                 # Ref: https://bitbucket.org/jamesrhester/pycifrw/issues/19
                 self.ciffile = CifFile(datasource, grammar="auto")
                 for blockname in self.ciffile.keys():
-                    self._parseCifBlock(blockname)
+                    self._parse_cif_block(blockname)
                     # stop after reading the first structure
                     if self.stru is not None:
                         break
@@ -452,7 +458,7 @@ def _parseCifDataSource(self, datasource):
             raise e.with_traceback(exc_traceback)
         return self.stru
 
-    def _parseCifBlock(self, blockname):
+    def _parse_cif_block(self, blockname):
         """Translate CIF file block, skip blocks without
         `_atom_site_label`. Updates data members `stru`, `eau`.
 
@@ -682,7 +688,16 @@ def _expand_asymmetric_unit(self, block):
 
     # conversion to CIF ------------------------------------------------------
 
+    @deprecated(toLines_deprecation_msg)
     def toLines(self, stru):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.P_cif.to_lines instead.
+        """
+        return self.to_lines(stru)
+
+    def to_lines(self, stru):
         """Convert `Structure` to a list of lines in basic CIF format.
 
         Parameters

src/diffpy/structure/parsers/p_discus.py

@@ -20,6 +20,22 @@
 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_discus"
+removal_version = "4.0.0"
+parseLines_deprecation_msg = build_deprecation_message(
+    base,
+    "parseLines",
+    "parse_lines",
+    removal_version,
+)
+toLines_deprecation_msg = build_deprecation_message(
+    base,
+    "toLines",
+    "to_lines",
+    removal_version,
+)
 
 
 class P_discus(StructureParser):
@@ -59,6 +75,7 @@ def __init__(self):
         self.ncell_read = False
         return
 
+    @deprecated(parseLines_deprecation_msg)
     def parseLines(self, lines):
         """Parse list of lines in DISCUS format.
 
@@ -78,7 +95,7 @@ def parseLines(self, lines):
             If the file is not in DISCUS format.
         """
         self.lines = lines
-        ilines = self._linesIterator()
+        ilines = self._lines_iterator()
         self.stru = PDFFitStructure()
         record_parsers = {
             "cell": self._parse_cell,
@@ -153,7 +170,7 @@ def parse_lines(self, lines):
             If the file is not in DISCUS format.
         """
         self.lines = lines
-        ilines = self._linesIterator()
+        ilines = self._lines_iterator()
         self.stru = PDFFitStructure()
         record_parsers = {
             "cell": self._parse_cell,
@@ -209,7 +226,16 @@ def parse_lines(self, lines):
             raise e.with_traceback(exc_traceback)
         return self.stru
 
+    @deprecated(toLines_deprecation_msg)
     def toLines(self, stru):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.P_discus.to_lines instead.
+        """
+        return self.to_lines(stru)
+
+    def to_lines(self, stru):
         """Convert `Structure` stru to a list of lines in DISCUS format.
 
         Parameters
@@ -257,7 +283,7 @@ def toLines(self, stru):
             )
         return lines
 
-    def _linesIterator(self):
+    def _lines_iterator(self):
         """Iterator over `self.lines`, which increments `self.nl`"""
         # ignore trailing empty lines
         stop = len(self.lines)

src/diffpy/structure/parsers/p_pdb.py

@@ -39,6 +39,12 @@
     "parse_lines",
     removal_version,
 )
+toLines_deprecation_msg = build_deprecation_message(
+    base,
+    "toLines",
+    "to_lines",
+    removal_version,
+)
 
 
 class P_pdb(StructureParser):
@@ -396,7 +402,16 @@ def atomLines(self, stru, idx):
                 lines.append(line)
         return lines
 
+    @deprecated(toLines_deprecation_msg)
     def toLines(self, stru):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.P_pdb.to_lines instead.
+        """
+        return self.to_lines(stru)
+
+    def to_lines(self, stru):
         """Convert `Structure` stru to a list of lines in PDB format.
 
         Parameters

src/diffpy/structure/parsers/p_pdffit.py

@@ -274,6 +274,83 @@ def toLines(self, stru):
             lines.append("    %18.8f %17.8f %17.8f" % sigUij)
         return lines
 
+    def to_lines(self, stru):
+        """Convert `Structure` stru to a list of lines in PDFfit format.
+
+        Parameters
+        ----------
+        stru : Structure
+            Structure to be converted.
+
+        Returns
+        -------
+        list of str
+            List of lines in PDFfit format.
+        """
+        # build the stru_pdffit dictionary initialized from the defaults
+        # in PDFFitStructure
+        stru_pdffit = PDFFitStructure().pdffit
+        if stru.pdffit:
+            stru_pdffit.update(stru.pdffit)
+        lines = []
+        # default values of standard deviations
+        d_sigxyz = numpy.zeros(3, dtype=float)
+        d_sigo = 0.0
+        d_sigU = numpy.zeros((3, 3), dtype=float)
+        # here we can start
+        line = "title  " + stru.title
+        lines.append(line.strip())
+        lines.append("format pdffit")
+        lines.append("scale  %9.6f" % stru_pdffit["scale"])
+        lines.append(
+            "sharp  %9.6f, %9.6f, %9.6f, %9.6f"
+            % (
+                stru_pdffit["delta2"],
+                stru_pdffit["delta1"],
+                stru_pdffit["sratio"],
+                stru_pdffit["rcut"],
+            )
+        )
+        lines.append("spcgr   " + stru_pdffit["spcgr"])
+        if stru_pdffit.get("spdiameter", 0.0) > 0.0:
+            line = "shape   sphere, %g" % stru_pdffit["spdiameter"]
+            lines.append(line)
+        if stru_pdffit.get("stepcut", 0.0) > 0.0:
+            line = "shape   stepcut, %g" % stru_pdffit["stepcut"]
+            lines.append(line)
+        lat = stru.lattice
+        lines.append(
+            "cell   %9.6f, %9.6f, %9.6f, %9.6f, %9.6f, %9.6f"
+            % (lat.a, lat.b, lat.c, lat.alpha, lat.beta, lat.gamma)
+        )
+        lines.append("dcell  %9.6f, %9.6f, %9.6f, %9.6f, %9.6f, %9.6f" % tuple(stru_pdffit["dcell"]))
+        lines.append("ncell  %9i, %9i, %9i, %9i" % (1, 1, 1, len(stru)))
+        lines.append("atoms")
+        for a in stru:
+            ad = a.__dict__
+            lines.append(
+                "%-4s %17.8f %17.8f %17.8f %12.4f"
+                % (
+                    a.element.upper(),
+                    a.xyz[0],
+                    a.xyz[1],
+                    a.xyz[2],
+                    a.occupancy,
+                )
+            )
+            sigmas = numpy.concatenate((ad.get("sigxyz", d_sigxyz), [ad.get("sigo", d_sigo)]))
+            lines.append("    %18.8f %17.8f %17.8f %12.4f" % tuple(sigmas))
+            sigU = ad.get("sigU", d_sigU)
+            Uii = (a.U[0][0], a.U[1][1], a.U[2][2])
+            Uij = (a.U[0][1], a.U[0][2], a.U[1][2])
+            sigUii = (sigU[0][0], sigU[1][1], sigU[2][2])
+            sigUij = (sigU[0][1], sigU[0][2], sigU[1][2])
+            lines.append("    %18.8f %17.8f %17.8f" % Uii)
+            lines.append("    %18.8f %17.8f %17.8f" % sigUii)
+            lines.append("    %18.8f %17.8f %17.8f" % Uij)
+            lines.append("    %18.8f %17.8f %17.8f" % sigUij)
+        return lines
+
     # Protected methods ------------------------------------------------------
 
     def _parse_shape(self, line):

src/diffpy/structure/parsers/p_rawxyz.py

@@ -34,6 +34,12 @@
     "parse_lines",
     removal_version,
 )
+toLines_deprecation_msg = build_deprecation_message(
+    base,
+    "toLines",
+    "to_lines",
+    removal_version,
+)
 
 
 class P_rawxyz(StructureParser):
@@ -130,7 +136,16 @@ def parse_lines(self, lines):
             raise e.with_traceback(exc_traceback)
         return stru
 
+    @deprecated(toLines_deprecation_msg)
     def toLines(self, stru):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.P_rawxyz.to_lines instead.
+        """
+        return self.to_lines(stru)
+
+    def to_lines(self, stru):
         """Convert Structure stru to a list of lines in RAWXYZ format.
 
         Parameters

src/diffpy/structure/parsers/p_xcfg.py

@@ -160,6 +160,12 @@
     "parse_lines",
     removal_version,
 )
+toLines_deprecation_msg = build_deprecation_message(
+    base,
+    "toLines",
+    "to_lines",
+    removal_version,
+)
 
 
 class P_xcfg(StructureParser):
@@ -309,7 +315,16 @@ def parse_lines(self, lines):
             raise e.with_traceback(exc_traceback)
         return stru
 
+    @deprecated(toLines_deprecation_msg)
     def toLines(self, stru):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.P_xcfg.to_lines instead.
+        """
+        return self.to_lines(stru)
+
+    def to_lines(self, stru):
         """Convert Structure stru to a list of lines in XCFG atomeye
         format.
 

src/diffpy/structure/parsers/p_xyz.py

@@ -34,6 +34,12 @@
     "parse_lines",
     removal_version,
 )
+toLines_deprecation_msg = build_deprecation_message(
+    base,
+    "toLines",
+    "to_lines",
+    removal_version,
+)
 
 
 class P_xyz(StructureParser):
@@ -140,7 +146,16 @@ def parse_lines(self, lines):
             raise StructureFormatError(emsg)
         return stru
 
+    @deprecated(toLines_deprecation_msg)
     def toLines(self, stru):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.P_xyz.to_lines instead.
+        """
+        return self.to_lines(stru)
+
+    def to_lines(self, stru):
         """Convert Structure stru to a list of lines in XYZ format.
 
         Parameters