chore: deprecate spacegroup method

Author: stevenhua0320

devutils/sgtbx_extra_groups.py

@@ -17,7 +17,7 @@
 import numpy
 from cctbx import sgtbx
 
-from diffpy.structure.spacegroups import IsSpaceGroupIdentifier, SpaceGroup, SymOp, mmLibSpaceGroupList
+from diffpy.structure.spacegroups import SpaceGroup, SymOp, is_space_group_identifier, mmLibSpaceGroupList
 
 
 def tupleToSGArray(tpl):
@@ -196,7 +196,7 @@ def main():
         if findEquivalentMMSpaceGroup(grp):
             continue
         shn = smbls.hermann_mauguin().replace(" ", "")
-        if IsSpaceGroupIdentifier(shn):
+        if is_space_group_identifier(shn):
             continue
         sg = mmSpaceGroupFromSymbol(uhm)
         hsg = hashMMSpaceGroup(sg)

news/deprecate-spacegroup.rst

@@ -0,0 +1,33 @@
+**Added:**
+
+* Added ``get_symop`` method in ``parsers/p_cif.py``
+* Added ``get_space_group`` method in ``spacegroups.py``
+* Added ``find_space_group`` method in ``spacegroups.py``
+* Added ``is_space_group_identifier`` method in ``spacegroups.py``
+* Added ``_hash_symop_list`` method in ``spacegroups.py``
+* Added ``_build_sg_lookup_table`` method in ``spacegroups.py``
+* Added ``_get_sg_hash_lookup_table`` method in ``spacegroups.py``
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* Deprecated ``getSymOp`` method in ``parsers/p_cif.py`` for removal in version 4.0.0
+* Deprecated ``GetSpaceGroup`` method in ``spacegroups.py`` for removal in version 4.0.0
+* Deprecated ``IsSpaceGroupIdentifier`` method in ``spacegroups.py`` for removal in version 4.0.0
+* Deprecated ``FindSpaceGroup`` method in ``spacegroups.py`` for removal in version 4.0.0
+* Deprecated ``_hashSymOpList`` method in ``spacegroups.py`` for removal in version 4.0.0
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/structure/parsers/p_cif.py

@@ -593,7 +593,12 @@ def _parse_space_group_symop_operation_xyz(self, block):
         block : CifBlock
             Instance of `CifBlock`.
         """
-        from diffpy.structure.spacegroups import FindSpaceGroup, GetSpaceGroup, IsSpaceGroupIdentifier, SpaceGroup
+        from diffpy.structure.spacegroups import (
+            SpaceGroup,
+            find_space_group,
+            get_space_group,
+            is_space_group_identifier,
+        )
 
         self.asymmetric_unit = list(self.stru)
         sym_synonyms = (
@@ -608,7 +613,7 @@ def _parse_space_group_symop_operation_xyz(self, block):
             sym_loop_name = sym_loop_name[0]
             sym_loop = block.GetLoop(sym_loop_name)
             for eqxyz in sym_loop[sym_loop_name]:
-                opcif = getSymOp(eqxyz)
+                opcif = get_symop(eqxyz)
                 symop_list.append(opcif)
         # determine space group number
         sg_nameHall = block.get("_space_group_name_Hall", "") or block.get("_symmetry_space_group_name_Hall", "")
@@ -623,12 +628,12 @@ def _parse_space_group_symop_operation_xyz(self, block):
         # try to reuse existing space group from symmetry operations
         if symop_list:
             try:
-                self.spacegroup = FindSpaceGroup(symop_list)
+                self.spacegroup = find_space_group(symop_list)
             except ValueError:
                 pass
         # otherwise lookup the space group from its identifier
-        if self.spacegroup is None and sgid and IsSpaceGroupIdentifier(sgid):
-            self.spacegroup = GetSpaceGroup(sgid)
+        if self.spacegroup is None and sgid and is_space_group_identifier(sgid):
+            self.spacegroup = get_space_group(sgid)
         # define new spacegroup when symmetry operations were listed, but
         # there is no match to an existing definition
         if symop_list and self.spacegroup is None:
@@ -824,6 +829,12 @@ def to_lines(self, stru):
     "get_parser",
     removal_version,
 )
+getSymOp_deprecation_msg = build_deprecation_message(
+    parsers_base,
+    "getSymOp",
+    "get_symop",
+    removal_version,
+)
 # constant regular expression for leading_float()
 rx_float = re.compile(r"[-+]?(\d+(\.\d*)?|\.\d+)([eE][-+]?\d+)?")
 
@@ -878,7 +889,17 @@ def leading_float(s, d=0.0):
 symvec["+z"] = symvec["z"]
 
 
+@deprecated(getSymOp_deprecation_msg)
 def getSymOp(s):
+    """This function has been deprecated and will be removed in version
+    4.0.0.
+
+    Please use diffpy.structure.get_symop instead.
+    """
+    return get_symop(s)
+
+
+def get_symop(s):
     """Create `SpaceGroups.SymOp` instance from a string.
 
     Parameters
@@ -913,7 +934,7 @@ def getParser(eps=None):
     """This function has been deprecated and will be removed in version
     4.0.0.
 
-    Please use diffpy.structure.P_cif.get_parser instead.
+    Please use diffpy.structure.get_parser instead.
     """
     return get_parser(eps)
 

src/diffpy/structure/spacegroups.py

@@ -643,14 +643,50 @@
     Tr_34_34_14,
     Tr_34_34_34,
 )
+from diffpy.utils._deprecator import build_deprecation_message, deprecated
 
 # Import SpaceGroup objects --------------------------------------------------
-
+base = "diffpy.structure"
+removal_version = "4.0.0"
+GetSpaceGroup_deprecation_msg = build_deprecation_message(
+    base,
+    "GetSpaceGroup",
+    "get_space_group",
+    removal_version,
+)
+FindSpaceGroup_deprecation_msg = build_deprecation_message(
+    base,
+    "FindSpaceGroup",
+    "find_space_group",
+    removal_version,
+)
+IsSpaceGroupIdentifier_deprecation_msg = build_deprecation_message(
+    base,
+    "IsSpaceGroupIdentifier",
+    "is_space_group_identifier",
+    removal_version,
+)
+_hashSymOpList_deprecation_msg = build_deprecation_message(
+    base,
+    "_hashSymOpList",
+    "_hash_symop_list",
+    removal_version,
+)
 
 SpaceGroupList = mmLibSpaceGroupList + sgtbxSpaceGroupList
 
 
+@deprecated(GetSpaceGroup_deprecation_msg)
 def GetSpaceGroup(sgid):
+    """This function has been deprecated and will be removed in version
+    4.0.0.
+
+    Please use diffpy.structure.get_space_group instead.
+    """
+    return get_space_group(sgid)
+
+
+def get_space_group(sgid):
     """Returns the SpaceGroup instance for the given identifier.
 
     Parameters
@@ -670,7 +706,7 @@ def GetSpaceGroup(sgid):
         When the identifier is not found.
     """
     if not _sg_lookup_table:
-        _buildSGLookupTable()
+        _build_sg_lookup_table()
     if sgid in _sg_lookup_table:
         return _sg_lookup_table[sgid]
     # Try different versions of sgid, first make sure it is a string
@@ -691,10 +727,22 @@ def GetSpaceGroup(sgid):
     raise ValueError(emsg)
 
 
+@deprecated(IsSpaceGroupIdentifier_deprecation_msg)
 def IsSpaceGroupIdentifier(sgid):
     """Check if identifier can be used as an argument to
     `GetSpaceGroup`.
 
+    Returns
+    -------
+    bool
+    """
+    return is_space_group_identifier(sgid)
+
+
+def is_space_group_identifier(sgid):
+    """Check if identifier can be used as an argument to
+    `GetSpaceGroup`.
+
     Returns
     -------
     bool
@@ -707,7 +755,17 @@ def IsSpaceGroupIdentifier(sgid):
     return rv
 
 
+@deprecated(FindSpaceGroup_deprecation_msg)
 def FindSpaceGroup(symops, shuffle=False):
+    """This function has been deprecated and will be removed in version
+    4.0.0.
+
+    Please use diffpy.structure.find_space_group instead.
+    """
+    return find_space_group(symops, shuffle=shuffle)
+
+
+def find_space_group(symops, shuffle=False):
     """Lookup SpaceGroup from a given list of symmetry operations.
 
     Parameters
@@ -732,8 +790,8 @@ def FindSpaceGroup(symops, shuffle=False):
         When `symops` do not match any known SpaceGroup.
     """
 
-    tb = _getSGHashLookupTable()
-    hh = _hashSymOpList(symops)
+    tb = _get_sg_hash_lookup_table()
+    hh = _hash_symop_list(symops)
     if hh not in tb:
         raise ValueError("Cannot find SpaceGroup for the specified symops.")
     rv = tb[hh]
@@ -746,7 +804,17 @@ def FindSpaceGroup(symops, shuffle=False):
     return rv
 
 
+@deprecated(_hashSymOpList_deprecation_msg)
 def _hashSymOpList(symops):
+    """This function has been deprecated and will be removed in version
+    4.0.0.
+
+    Please use diffpy.structure._hash_symop_list instead.
+    """
+    return _hash_symop_list(symops)
+
+
+def _hash_symop_list(symops):
     """Return hash value for a sequence of `SymOp` objects.
 
     The symops are sorted so the results is independent of symops order.
@@ -766,7 +834,7 @@ def _hashSymOpList(symops):
     return rv
 
 
-def _buildSGLookupTable():
+def _build_sg_lookup_table():
     """Rebuild space group lookup table from the `SpaceGroupList` data.
 
     This routine updates the global `_sg_lookup_table` dictionary.
@@ -809,16 +877,16 @@ def _buildSGLookupTable():
 _sg_lookup_table = {}
 
 
-def _getSGHashLookupTable():
+def _get_sg_hash_lookup_table():
     """Return lookup table of symop hashes to standard `SpaceGroup`
     objects."""
     if _sg_hash_lookup_table:
         return _sg_hash_lookup_table
     for sg in SpaceGroupList:
-        h = _hashSymOpList(sg.symop_list)
+        h = _hash_symop_list(sg.symop_list)
         _sg_hash_lookup_table[h] = sg
     assert len(_sg_hash_lookup_table) == len(SpaceGroupList)
-    return _getSGHashLookupTable()
+    return _get_sg_hash_lookup_table()
 
 
 _sg_hash_lookup_table = {}

tests/test_p_cif.py

@@ -21,7 +21,7 @@
 
 from diffpy.structure import Structure
 from diffpy.structure.parsers import get_parser, getParser
-from diffpy.structure.parsers.p_cif import P_cif, getSymOp, leading_float
+from diffpy.structure.parsers.p_cif import P_cif, get_symop, getSymOp, leading_float
 from diffpy.structure.structureerrors import StructureFormatError
 
 # ----------------------------------------------------------------------------
@@ -56,6 +56,20 @@ def test_getSymOp(self):
         self.assertEqual(str(op1_std), str(op1))
         return
 
+    def test_get_symop(self):
+        """Check get_symop()"""
+        from diffpy.structure.spacegroups import Rot_X_mY_Z, SymOp, Tr_0_12_12
+
+        op = get_symop("x,1/2-y,1/2+z")
+        op_std = SymOp(Rot_X_mY_Z, Tr_0_12_12)
+        self.assertEqual(str(op_std), str(op))
+        from diffpy.structure.spacegroups import Rot_mX_mXY_Z, Tr_0_0_12
+
+        op1 = get_symop("-x,-x+y,1/2+z")
+        op1_std = SymOp(Rot_mX_mXY_Z, Tr_0_0_12)
+        self.assertEqual(str(op1_std), str(op1))
+        return
+
 
 # End of class TestRoutines
 
@@ -332,7 +346,7 @@ def test_unknown_occupancy(self):
 
     def test_unknown_spacegroup_number(self):
         "test CIF file with unknown space group symbol"
-        from diffpy.structure.spacegroups import GetSpaceGroup, _hashSymOpList
+        from diffpy.structure.spacegroups import _hash_symop_list, get_space_group
 
         with open(self.pbteciffile) as fp:
             lines = fp.readlines()
@@ -346,9 +360,9 @@ def test_unknown_spacegroup_number(self):
         ciftxt = "".join(lines)
         stru = self.ptest.parse(ciftxt)
         self.assertEqual(8, len(stru))
-        h225 = _hashSymOpList(GetSpaceGroup(225).iter_symops())
+        h225 = _hash_symop_list(get_space_group(225).iter_symops())
         sgcif = self.ptest.spacegroup
-        self.assertEqual(h225, _hashSymOpList(sgcif.iter_symops()))
+        self.assertEqual(h225, _hash_symop_list(sgcif.iter_symops()))
         return
 
     def test_nosites_cif(self):