Merge pull request #177 from stevenhua0320/deprecate-parser-display

chore: derepcate P_pdb method

Author: sbillinge

news/deprecate-parser-display.rst

@@ -0,0 +1,31 @@
+**Added:**
+
+* Added ``input_formats`` method in ``parsers/__init__.py``
+* Added ``output_formats`` method in ``parsers/__init__.py``
+* Added ``title_lines`` method in ``p_pdb.py``
+* Added ``cryst1_lines`` method in ``p_pdb.py``
+* Added ``atom_lines`` method in ``p_pdb.py``
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* Deprecated ``inputFormats`` method in ``parsers/__init__.py`` for removal in version 4.0.0
+* Deprecated ``outputFormats`` method in ``parsers/__init__.py`` for removal in version 4.0.0
+* Deprecated ``titleLines`` method in ``p_pdb.py`` for removal in version 4.0.0
+* Deprecated ``crystl1Lines`` method in ``p_pdb.py`` for removal in version 4.0.0
+* Deprecated ``atomLines`` method in ``p_pdb.py`` for removal in version 4.0.0
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/structure/apps/anyeye.py

@@ -72,9 +72,9 @@ def usage(style=None):
     if style == "brief":
         msg = msg.split("\n")[1] + "\n" + "Try `%s --help' for more information." % myname
     else:
-        from diffpy.structure.parsers import inputFormats
+        from diffpy.structure.parsers import input_formats
 
-        fmts = [f for f in inputFormats() if f != "auto"]
+        fmts = [f for f in input_formats() if f != "auto"]
         msg = msg.replace("inputFormats", " ".join(fmts))
     print(msg)
     return

src/diffpy/structure/apps/transtru.py

@@ -52,10 +52,10 @@ def usage(style=None):
     if style == "brief":
         msg = msg.split("\n")[1] + "\n" + "Try `%s --help' for more information." % myname
     else:
-        from diffpy.structure.parsers import inputFormats, outputFormats
+        from diffpy.structure.parsers import input_formats, output_formats
 
-        msg = msg.replace("inputFormats", " ".join(inputFormats()))
-        msg = msg.replace("outputFormats", " ".join(outputFormats()))
+        msg = msg.replace("inputFormats", " ".join(input_formats()))
+        msg = msg.replace("outputFormats", " ".join(output_formats()))
     print(msg)
     return
 
@@ -88,14 +88,14 @@ def main():
         usage("brief")
         sys.exit()
     # process arguments
-    from diffpy.structure.parsers import inputFormats, outputFormats
+    from diffpy.structure.parsers import input_formats, output_formats
 
     try:
         infmt, outfmt = args[0].split("..", 1)
-        if infmt not in inputFormats():
+        if infmt not in input_formats():
             print("'%s' is not valid input format" % infmt, file=sys.stderr)
             sys.exit(2)
-        if outfmt not in outputFormats():
+        if outfmt not in output_formats():
             print("'%s' is not valid output format" % outfmt, file=sys.stderr)
             sys.exit(2)
     except ValueError:

src/diffpy/structure/parsers/__init__.py

@@ -46,28 +46,26 @@
     "get_parser",
     removal_version,
 )
+inputFormats_deprecation_msg = build_deprecation_message(
+    parsers_base,
+    "inputFormats",
+    "input_formats",
+    removal_version,
+)
+outputFormats_deprecation_msg = build_deprecation_message(
+    parsers_base,
+    "outputFormats",
+    "output_formats",
+    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.
+    """This function has been deprecated and will be removed in version
+    4.0.0.
 
-    Returns
-    -------
-    Parser
-        Parser instance for the given format.
-
-    Raises
-    ------
-    StructureFormatError
-        When the format is not defined.
+    Please use diffpy.structure.get_parser instead.
     """
     return get_parser(format, **kw)
 
@@ -102,14 +100,34 @@ def get_parser(format, **kw):
     return ns["pm"].get_parser(**kw)
 
 
+@deprecated(inputFormats_deprecation_msg)
 def inputFormats():
+    """This function has been deprecated and will be removed in version
+    4.0.0.
+
+    Please use diffpy.structure.input_formats instead.
+    """
+    return input_formats()
+
+
+def input_formats():
     """Return list of implemented input structure formats."""
     input_formats = [fmt for fmt, prop in parser_index.items() if prop["has_input"]]
     input_formats.sort()
     return input_formats
 
 
+@deprecated(outputFormats_deprecation_msg)
 def outputFormats():
+    """This function has been deprecated and will be removed in version
+    4.0.0.
+
+    Please use diffpy.structure.output_formats instead.
+    """
+    return output_formats()
+
+
+def output_formats():
     """Return list of implemented output structure formats."""
     output_formats = [fmt for fmt, prop in parser_index.items() if prop["has_output"]]
     output_formats.sort()

src/diffpy/structure/parsers/p_auto.py

@@ -73,9 +73,9 @@ def _get_ordered_formats(self):
 
         This only works when `self.filename` has a known extension.
         """
-        from diffpy.structure.parsers import inputFormats
+        from diffpy.structure.parsers import input_formats
 
-        ofmts = [fmt for fmt in inputFormats() if fmt != "auto"]
+        ofmts = [fmt for fmt in input_formats() if fmt != "auto"]
         if not self.filename:
             return ofmts
         # filename is defined here
@@ -252,17 +252,10 @@ def _wrap_parse_method(self, method: object, *args: object, **kwargs: object) ->
 
 @deprecated(getParser_deprecation_msg)
 def getParser(**kw):
-    """Return a new instance of the automatic parser.
-
-    Parameters
-    ----------
-    **kw : dict
-        Keyword arguments for the structure parser
+    """This function has been deprecated and will be removed in version
+    4.0.0.
 
-    Returns
-    -------
-    P_auto
-        Instance of `P_auto`.
+    Please use diffpy.structure.P_auto.get_parser instead.
     """
     return get_parser(**kw)
 

src/diffpy/structure/parsers/p_cif.py

@@ -910,18 +910,10 @@ def getSymOp(s):
 
 @deprecated(getParser_deprecation_msg)
 def getParser(eps=None):
-    """Return new `parser` object for CIF format.
+    """This function has been deprecated and will be removed in version
+    4.0.0.
 
-    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`.
+    Please use diffpy.structure.P_cif.get_parser instead.
     """
     return get_parser(eps)
 

src/diffpy/structure/parsers/p_discus.py

@@ -424,12 +424,10 @@ def _parse_not_implemented(self, words):
 
 @deprecated(getParser_deprecation_msg)
 def getParser():
-    """Return new `parser` object for DISCUS format.
+    """This function has been deprecated and will be removed in version
+    4.0.0.
 
-    Returns
-    -------
-    P_discus
-        Instance of `P_discus`.
+    Please use diffpy.structure.P_discus.get_parser instead.
     """
     return get_parser()
 

src/diffpy/structure/parsers/p_pdb.py

@@ -45,6 +45,24 @@
     "to_lines",
     removal_version,
 )
+titleLines_deprecation_msg = build_deprecation_message(
+    base,
+    "titleLines",
+    "title_lines",
+    removal_version,
+)
+cryst1Lines_deprecation_msg = build_deprecation_message(
+    base,
+    "cryst1Lines",
+    "cryst1_lines",
+    removal_version,
+)
+atomLines_deprecation_msg = build_deprecation_message(
+    base,
+    "atomLines",
+    "atom_lines",
+    removal_version,
+)
 
 
 class P_pdb(StructureParser):
@@ -269,7 +287,12 @@ def parse_lines(self, lines):
             raise e.with_traceback(exc_traceback)
         return stru
 
+    @deprecated(titleLines_deprecation_msg)
     def titleLines(self, stru):
+        """Build lines corresponding to `TITLE` record."""
+        return self.title_lines(stru)
+
+    def title_lines(self, stru):
         """Build lines corresponding to `TITLE` record."""
         lines = []
         title = stru.title
@@ -288,7 +311,12 @@ def titleLines(self, stru):
             title = title[stop:]
         return lines
 
+    @deprecated(cryst1Lines_deprecation_msg)
     def cryst1Lines(self, stru):
+        """Build lines corresponding to `CRYST1` record."""
+        return self.cryst1_lines(stru)
+
+    def cryst1_lines(self, stru):
         """Build lines corresponding to `CRYST1` record."""
         lines = []
         latpar = (
@@ -304,7 +332,13 @@ def cryst1Lines(self, stru):
             lines.append("%-80s" % line)
         return lines
 
+    @deprecated(atomLines_deprecation_msg)
     def atomLines(self, stru, idx):
+        """Build `ATOM` records and possibly `SIGATM`, `ANISOU` or
+        `SIGUIJ` records for `structure` stru `atom` number aidx."""
+        return self.atom_lines(stru, idx)
+
+    def atom_lines(self, stru, idx):
         """Build `ATOM` records and possibly `SIGATM`, `ANISOU` or
         `SIGUIJ` records for `structure` stru `atom` number aidx."""
         lines = []
@@ -425,10 +459,10 @@ def to_lines(self, stru):
             List of lines in PDB format.
         """
         lines = []
-        lines.extend(self.titleLines(stru))
-        lines.extend(self.cryst1Lines(stru))
+        lines.extend(self.title_lines(stru))
+        lines.extend(self.cryst1_lines(stru))
         for idx in range(len(stru)):
-            lines.extend(self.atomLines(stru, idx))
+            lines.extend(self.atom_lines(stru, idx))
         line = (
             "TER   "  # 1-6
             + "%(serial)5i      "  # 7-11, 12-17