chore: deprecate utils method and private methods in parsers

news/deprecate-utils.rst

@@ -0,0 +1,39 @@
+**Added:**
+
+* Added ``atom_bare_symbol`` method in ``utils.py``
+* Added ``_get_ordered_formats`` method in ``p_auto.py``
+* Added ``_wrap_parse_method`` method in ``p_auto.py``
+* Added ``_tr_atom_site_u_iso_or_equiv`` method in ``p_cif.py``
+* Added ``_tr_atom_site_b_iso_or_equiv`` method in ``p_cif.py``
+* Added ``_tr_atom_site_aniso_u_11`` method in ``p_cif.py``
+* Added ``_tr_atom_site_aniso_u_22`` method in ``p_cif.py``
+* Added ``_tr_atom_site_aniso_u_33`` method in ``p_cif.py``
+* Added ``_tr_atom_site_aniso_u_12`` method in ``p_cif.py``
+* Added ``_tr_atom_site_aniso_u_13`` method in ``p_cif.py``
+* Added ``_tr_atom_site_aniso_u_23`` method in ``p_cif.py``
+* Added ``_tr_atom_site_aniso_b_11`` method in ``p_cif.py``
+* Added ``_tr_atom_site_aniso_b_22`` method in ``p_cif.py``
+* Added ``_tr_atom_site_aniso_b_33`` method in ``p_cif.py``
+* Added ``_tr_atom_site_aniso_b_12`` method in ``p_cif.py``
+* Added ``_tr_atom_site_aniso_b_13`` method in ``p_cif.py``
+* Added ``_tr_atom_site_aniso_b_23`` method in ``p_cif.py``
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* Deprecated ``atomBareSymbol`` method in ``utils.py`` for removal in version 4.0.0
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/structure/parsers/p_auto.py

@@ -51,7 +51,7 @@ def __init__(self, **kw):
         return
 
     # parseLines helpers
-    def _getOrderedFormats(self):
+    def _get_ordered_formats(self):
         """Build a list of relevance ordered structure formats.
 
         This only works when `self.filename` has a known extension.
@@ -96,7 +96,7 @@ def parseLines(self, lines):
         ------
         StructureFormatError
         """
-        return self._wrapParseMethod("parseLines", lines)
+        return self._wrap_parse_method("parseLines", lines)
 
     def parse(self, s):
         """Detect format and create `Structure` instance from a string.
@@ -117,7 +117,7 @@ def parse(self, s):
         ------
         StructureFormatError
         """
-        return self._wrapParseMethod("parse", s)
+        return self._wrap_parse_method("parse", s)
 
     def parseFile(self, filename):
         """Detect format and create Structure instance from an existing
@@ -143,9 +143,9 @@ def parseFile(self, filename):
             If the file cannot be read.
         """
         self.filename = filename
-        return self._wrapParseMethod("parseFile", filename)
+        return self._wrap_parse_method("parseFile", filename)
 
-    def _wrapParseMethod(self, method, *args, **kwargs):
+    def _wrap_parse_method(self, method, *args, **kwargs):
         """A helper evaluator method that try the specified parse method
         with each registered structure parser and return the first
         successful result.
@@ -173,7 +173,7 @@ def _wrapParseMethod(self, method, *args, **kwargs):
         """
         from diffpy.structure.parsers import getParser
 
-        ofmts = self._getOrderedFormats()
+        ofmts = self._get_ordered_formats()
         stru = None
         # try all parsers in sequence
         parsers_emsgs = []

src/diffpy/structure/parsers/p_cif.py

@@ -104,23 +104,23 @@ class P_cif(StructureParser):
             "_tr_atom_site_cartn_x",
             "_tr_atom_site_cartn_y",
             "_tr_atom_site_cartn_z",
-            "_tr_atom_site_U_iso_or_equiv",
-            "_tr_atom_site_B_iso_or_equiv",
+            "_tr_atom_site_u_iso_or_equiv",
+            "_tr_atom_site_b_iso_or_equiv",
             "_tr_atom_site_adp_type",
             "_tr_atom_site_thermal_displace_type",
             "_tr_atom_site_occupancy",
-            "_tr_atom_site_aniso_U_11",
-            "_tr_atom_site_aniso_U_22",
-            "_tr_atom_site_aniso_U_33",
-            "_tr_atom_site_aniso_U_12",
-            "_tr_atom_site_aniso_U_13",
-            "_tr_atom_site_aniso_U_23",
-            "_tr_atom_site_aniso_B_11",
-            "_tr_atom_site_aniso_B_22",
-            "_tr_atom_site_aniso_B_33",
-            "_tr_atom_site_aniso_B_12",
-            "_tr_atom_site_aniso_B_13",
-            "_tr_atom_site_aniso_B_23",
+            "_tr_atom_site_aniso_u_11",
+            "_tr_atom_site_aniso_u_22",
+            "_tr_atom_site_aniso_u_33",
+            "_tr_atom_site_aniso_u_12",
+            "_tr_atom_site_aniso_u_13",
+            "_tr_atom_site_aniso_u_23",
+            "_tr_atom_site_aniso_b_11",
+            "_tr_atom_site_aniso_b_22",
+            "_tr_atom_site_aniso_b_33",
+            "_tr_atom_site_aniso_b_12",
+            "_tr_atom_site_aniso_b_13",
+            "_tr_atom_site_aniso_b_23",
         )
     )
     # make _atom_setters case insensitive
@@ -185,15 +185,15 @@ def _tr_atom_site_cartn_z(a, value):
 
     _tr_atom_site_cartn_z = staticmethod(_tr_atom_site_cartn_z)
 
-    def _tr_atom_site_U_iso_or_equiv(a, value):
+    def _tr_atom_site_u_iso_or_equiv(a, value):
         a.Uisoequiv = leading_float(value)
 
-    _tr_atom_site_U_iso_or_equiv = staticmethod(_tr_atom_site_U_iso_or_equiv)
+    _tr_atom_site_u_iso_or_equiv = staticmethod(_tr_atom_site_u_iso_or_equiv)
 
-    def _tr_atom_site_B_iso_or_equiv(a, value):
+    def _tr_atom_site_b_iso_or_equiv(a, value):
         a.Uisoequiv = P_cif.BtoU * leading_float(value)
 
-    _tr_atom_site_B_iso_or_equiv = staticmethod(_tr_atom_site_B_iso_or_equiv)
+    _tr_atom_site_b_iso_or_equiv = staticmethod(_tr_atom_site_b_iso_or_equiv)
 
     def _tr_atom_site_adp_type(a, value):
         a.anisotropy = value not in ("Uiso", "Biso")
@@ -206,65 +206,65 @@ def _tr_atom_site_occupancy(a, value):
 
     _tr_atom_site_occupancy = staticmethod(_tr_atom_site_occupancy)
 
-    def _tr_atom_site_aniso_U_11(a, value):
+    def _tr_atom_site_aniso_u_11(a, value):
         a.U11 = leading_float(value)
 
-    _tr_atom_site_aniso_U_11 = staticmethod(_tr_atom_site_aniso_U_11)
+    _tr_atom_site_aniso_u_11 = staticmethod(_tr_atom_site_aniso_u_11)
 
-    def _tr_atom_site_aniso_U_22(a, value):
+    def _tr_atom_site_aniso_u_22(a, value):
         a.U22 = leading_float(value)
 
-    _tr_atom_site_aniso_U_22 = staticmethod(_tr_atom_site_aniso_U_22)
+    _tr_atom_site_aniso_u_22 = staticmethod(_tr_atom_site_aniso_u_22)
 
-    def _tr_atom_site_aniso_U_33(a, value):
+    def _tr_atom_site_aniso_u_33(a, value):
         a.U33 = leading_float(value)
 
-    _tr_atom_site_aniso_U_33 = staticmethod(_tr_atom_site_aniso_U_33)
+    _tr_atom_site_aniso_u_33 = staticmethod(_tr_atom_site_aniso_u_33)
 
-    def _tr_atom_site_aniso_U_12(a, value):
+    def _tr_atom_site_aniso_u_12(a, value):
         a.U12 = leading_float(value)
 
-    _tr_atom_site_aniso_U_12 = staticmethod(_tr_atom_site_aniso_U_12)
+    _tr_atom_site_aniso_u_12 = staticmethod(_tr_atom_site_aniso_u_12)
 
-    def _tr_atom_site_aniso_U_13(a, value):
+    def _tr_atom_site_aniso_u_13(a, value):
         a.U13 = leading_float(value)
 
-    _tr_atom_site_aniso_U_13 = staticmethod(_tr_atom_site_aniso_U_13)
+    _tr_atom_site_aniso_u_13 = staticmethod(_tr_atom_site_aniso_u_13)
 
-    def _tr_atom_site_aniso_U_23(a, value):
+    def _tr_atom_site_aniso_u_23(a, value):
         a.U23 = leading_float(value)
 
-    _tr_atom_site_aniso_U_23 = staticmethod(_tr_atom_site_aniso_U_23)
+    _tr_atom_site_aniso_u_23 = staticmethod(_tr_atom_site_aniso_u_23)
 
-    def _tr_atom_site_aniso_B_11(a, value):
+    def _tr_atom_site_aniso_b_11(a, value):
         a.U11 = P_cif.BtoU * leading_float(value)
 
-    _tr_atom_site_aniso_B_11 = staticmethod(_tr_atom_site_aniso_B_11)
+    _tr_atom_site_aniso_b_11 = staticmethod(_tr_atom_site_aniso_b_11)
 
-    def _tr_atom_site_aniso_B_22(a, value):
+    def _tr_atom_site_aniso_b_22(a, value):
         a.U22 = P_cif.BtoU * leading_float(value)
 
-    _tr_atom_site_aniso_B_22 = staticmethod(_tr_atom_site_aniso_B_22)
+    _tr_atom_site_aniso_b_22 = staticmethod(_tr_atom_site_aniso_b_22)
 
-    def _tr_atom_site_aniso_B_33(a, value):
+    def _tr_atom_site_aniso_b_33(a, value):
         a.U33 = P_cif.BtoU * leading_float(value)
 
-    _tr_atom_site_aniso_B_33 = staticmethod(_tr_atom_site_aniso_B_33)
+    _tr_atom_site_aniso_b_33 = staticmethod(_tr_atom_site_aniso_b_33)
 
-    def _tr_atom_site_aniso_B_12(a, value):
+    def _tr_atom_site_aniso_b_12(a, value):
         a.U12 = P_cif.BtoU * leading_float(value)
 
-    _tr_atom_site_aniso_B_12 = staticmethod(_tr_atom_site_aniso_B_12)
+    _tr_atom_site_aniso_b_12 = staticmethod(_tr_atom_site_aniso_b_12)
 
-    def _tr_atom_site_aniso_B_13(a, value):
+    def _tr_atom_site_aniso_b_13(a, value):
         a.U13 = P_cif.BtoU * leading_float(value)
 
-    _tr_atom_site_aniso_B_13 = staticmethod(_tr_atom_site_aniso_B_13)
+    _tr_atom_site_aniso_b_13 = staticmethod(_tr_atom_site_aniso_b_13)
 
-    def _tr_atom_site_aniso_B_23(a, value):
+    def _tr_atom_site_aniso_b_23(a, value):
         a.U23 = P_cif.BtoU * leading_float(value)
 
-    _tr_atom_site_aniso_B_23 = staticmethod(_tr_atom_site_aniso_B_23)
+    _tr_atom_site_aniso_b_23 = staticmethod(_tr_atom_site_aniso_b_23)
 
     def _get_atom_setters(cifloop):
         """Static method for finding translators of CifLoop items to
@@ -602,10 +602,10 @@ def _parse_space_group_symop_operation_xyz(self, block):
         if self.spacegroup is None:
             emsg = "CIF file has unknown space group identifier {!r}."
             raise StructureFormatError(emsg.format(sgid))
-        self._expandAsymmetricUnit(block)
+        self._expand_asymmetric_unit(block)
         return
 
-    def _expandAsymmetricUnit(self, block):
+    def _expand_asymmetric_unit(self, block):
         """Perform symmetry expansion of `self.stru` using
         `self.spacegroup`.
 

src/diffpy/structure/utils.py

@@ -18,6 +18,17 @@
 
 import numpy
 
+from diffpy.utils._deprecator import build_deprecation_message, deprecated
+
+base = "diffpy.structure"
+removal_version = "4.0.0"
+atomBareSymbol_deprecation_msg = build_deprecation_message(
+    base,
+    "atomBareSymbol",
+    "atom_bare_symbol",
+    removal_version,
+)
+
 
 def isiterable(obj):
     """``True`` if argument is iterable."""
@@ -35,7 +46,18 @@ def isfloat(s):
     return False
 
 
+@deprecated(atomBareSymbol_deprecation_msg)
 def atomBareSymbol(smbl):
+    """This function has been deprecated and will be removed in version
+    4.0.0.
+
+    Please use diffpy.structure.atom_bare_symbol instead.
+    """
+
+    return atom_bare_symbol(smbl)
+
+
+def atom_bare_symbol(smbl):
     """Remove atom type string stripped of isotope and ion charge
     symbols.
 
@@ -54,14 +76,13 @@ def atomBareSymbol(smbl):
 
     Examples
     --------
-    >>> atomBareSymbol("Cl-")
+    >>> atom_bare_symbol("Cl-")
     'Cl'
-    >>> atomBareSymbol("Ca2+")
+    >>> atom_bare_symbol("Ca2+")
     'Ca'
-    >>> atomBareSymbol("12-C")
+    >>> atom_bare_symbol("12-C")
     'C'
     """
-
     rv = smbl.strip().lstrip("0123456789-").rstrip("123456789+-")
     return rv
 

tests/test_utils.py

@@ -0,0 +1,37 @@
+#!/usr/bin/env python
+##############################################################################
+#
+# diffpy.structure  Complex Modeling Initiative
+#                   (c) 2016 Brookhaven Science Associates,
+#                   Brookhaven National Laboratory.
+#                   All rights reserved.
+#
+# File coded by:    Pavol Juhas
+#
+# See AUTHORS.txt for a list of people who contributed.
+# See LICENSE.txt for license information.
+#
+##############################################################################
+"""Test for Structure utilities."""
+import pytest
+
+from diffpy.structure.utils import atom_bare_symbol, atomBareSymbol
+
+
+def test_atomBareSymbol():
+    assert atomBareSymbol("Cl-") == "Cl"
+    assert atomBareSymbol("Ca2+") == "Ca"
+    assert atomBareSymbol("12-C") == "C"
+
+
+@pytest.mark.parametrize(
+    "symbol, expected",
+    [
+        ("Cl-", "Cl"),
+        ("Ca2+", "Ca"),
+        ("12-C", "C"),
+    ],
+)
+def test_atom_bare_symbol(symbol, expected):
+    actual = atom_bare_symbol(symbol)
+    assert actual == expected