Merge pull request diffpy#158 from stevenhua0320/deprecate-assignUniqueLabels

build: deprecate assignUniqueLabels

Author: sbillinge

news/deprecate-assignUniqueLabels.rst

@@ -0,0 +1,23 @@
+**Added:**
+
+* Added `diffpy.structure.Structure.assign_unique_labels` in replace of `assignUniqueLabels`
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* Deprecated `diffpy.structure.Structure.assignUniqueLabels` for removal in 4.0.0
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

requirements/conda.txt

@@ -1,2 +1,3 @@
 numpy
 pycifrw
+diffpy.utils

requirements/pip.txt

@@ -1,2 +1,3 @@
 numpy
 pycifrw
+diffpy.utils

src/diffpy/structure/structure.py

@@ -21,9 +21,19 @@
 from diffpy.structure.atom import Atom
 from diffpy.structure.lattice import Lattice
 from diffpy.structure.utils import _linkAtomAttribute, atomBareSymbol, isiterable
+from diffpy.utils._deprecator import build_deprecation_message, deprecated
 
 # ----------------------------------------------------------------------------
 
+base = "diffpy.structure.Structure"
+removal_version = "4.0.0"
+assignUniqueLabels_deprecation_msg = build_deprecation_message(
+    base,
+    "assignUniqueLabels",
+    "assign_unique_labels",
+    removal_version,
+)
+
 
 class Structure(list):
     """Define group of atoms in a specified lattice. Structure --> group
@@ -163,7 +173,7 @@ def getLastAtom(self):
         last_atom = self[-1]
         return last_atom
 
-    def assignUniqueLabels(self):
+    def assign_unique_labels(self):
         """Set a unique label string for each `Atom` in this structure.
 
         The label strings are formatted as "%(baresymbol)s%(index)i",
@@ -181,6 +191,16 @@ def assignUniqueLabels(self):
             islabeled.add(a)
         return
 
+    @deprecated(assignUniqueLabels_deprecation_msg)
+    def assignUniqueLabels(self):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.Structure.assign_unique_labels
+        instead.
+        """
+        return self.assign_unique_labels()
+
     def distance(self, aid0, aid1):
         """Calculate distance between 2 `Atoms`, no periodic boundary
         conditions.

tests/test_structure.py

@@ -128,11 +128,19 @@ def test_assignUniqueLabels(self):
         self.assertEqual("C2", self.stru[1].label)
         return
 
+    def test_assign_unique_labels(self):
+        """Check Structure.assign_unique_labels()"""
+        self.assertEqual("", "".join([a.label for a in self.stru]))
+        self.stru.assign_unique_labels()
+        self.assertEqual("C1", self.stru[0].label)
+        self.assertEqual("C2", self.stru[1].label)
+        return
+
     def test_distance(self):
         """Check Structure.distance()"""
         from math import sqrt
 
-        self.stru.assignUniqueLabels()
+        self.stru.assign_unique_labels()
         self.assertRaises(IndexError, self.stru.distance, 333, "C1")
         self.assertRaises(IndexError, self.stru.distance, "C", "C1")
         self.assertAlmostEqual(sqrt(2.0), self.stru.distance(0, 1), self.places)
@@ -143,7 +151,7 @@ def test_distance(self):
     def test_angle(self):
         """Check Structure.angle()"""
         cdse = Structure(filename=self.cdsefile)
-        cdse.assignUniqueLabels()
+        cdse.assign_unique_labels()
         self.assertEqual(109, round(cdse.angle(0, 2, 1)))
         self.assertEqual(109, round(cdse.angle("Cd1", "Se1", "Cd2")))
         return
@@ -236,7 +244,7 @@ def test___getitem__(self):
         cdse013.pop(2)
         self.assertEqual(cdse013, cdse[:2, 3].tolist())
         self.assertRaises(IndexError, cdse.__getitem__, "Cd1")
-        cdse.assignUniqueLabels()
+        cdse.assign_unique_labels()
         self.assertTrue(cdse[0] is cdse["Cd1"])
         cdse[0].label = "Hohenzollern"
         self.assertRaises(IndexError, cdse.__getitem__, "Cd1")
@@ -466,7 +474,7 @@ def test_label(self):
         """Check Structure.label."""
         cdse = Structure(filename=self.cdsefile)
         self.assertEqual(4 * [""], cdse.label.tolist())
-        cdse.assignUniqueLabels()
+        cdse.assign_unique_labels()
         self.assertEqual("Cd1 Cd2 Se1 Se2".split(), cdse.label.tolist())
         cdse.label = cdse.label.lower()
         self.assertEqual("cd1 cd2 se1 se2".split(), cdse.label.tolist())