chore: deprecate read/writeStr, placeInLattice method

news/deprecate-structure-function.rst

@@ -0,0 +1,27 @@
+**Added:**
+
+* Added ``place_in_lattice`` method to ``Structure``
+* Added ``read_structure`` method to ``Structure``
+* Added ``write_structure`` method to ``Structure``
+
+**Changed:**
+
+* Changed private method ``__emptySharedStructure`` to ``__empty_shared_structure``
+
+**Deprecated:**
+
+* Deprecated ``placeInLattice`` method of ``Structure`` for removal in version 4.0.0
+* Deprecated ``readStr`` method of ``Structure`` for removal in version 4.0.0
+* Deprecated ``writeStr`` method of ``Structure`` for removal in version 4.0.0
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/structure/apps/transtru.py

@@ -109,10 +109,10 @@ def main():
         strufile = args[1]
         stru = Structure()
         if args[1] == "-":
-            stru.readStr(sys.stdin.read(), infmt)
+            stru.read_structure(sys.stdin.read(), infmt)
         else:
             stru.read(strufile, infmt)
-        sys.stdout.write(stru.writeStr(outfmt))
+        sys.stdout.write(stru.write_structure(outfmt))
     except IndexError:
         print("strufile not specified", file=sys.stderr)
         sys.exit(2)

src/diffpy/structure/parsers/p_discus.py

@@ -125,7 +125,7 @@ def parseLines(self, lines):
                 latpars = list(self.stru.lattice.abcABG())
                 superlatpars = [latpars[i] * self.stru.pdffit["ncell"][i] for i in range(3)] + latpars[3:]
                 superlattice = Lattice(*superlatpars)
-                self.stru.placeInLattice(superlattice)
+                self.stru.place_in_lattice(superlattice)
                 self.stru.pdffit["ncell"] = [1, 1, 1, exp_natoms]
         except (ValueError, IndexError):
             exc_type, exc_value, exc_traceback = sys.exc_info()

src/diffpy/structure/parsers/p_pdffit.py

@@ -169,7 +169,7 @@ def parseLines(self, lines):
             if stru.pdffit["ncell"][:3] != [1, 1, 1]:
                 superlatpars = [latpars[i] * stru.pdffit["ncell"][i] for i in range(3)] + latpars[3:]
                 superlattice = Lattice(*superlatpars)
-                stru.placeInLattice(superlattice)
+                stru.place_in_lattice(superlattice)
                 stru.pdffit["ncell"] = [1, 1, 1, p_natoms]
         except (ValueError, IndexError):
             emsg = "%d: file is not in PDFfit format" % p_nl

src/diffpy/structure/pdffitstructure.py

@@ -97,7 +97,7 @@ def readStr(self, s, format="auto"):
         StructureParser
             Instance of `StructureParser` used to load the data.
         """
-        p = Structure.readStr(self, s, format)
+        p = Structure.read_structure(self, s, format)
         sg = getattr(p, "spacegroup", None)
         if sg:
             self.pdffit["spcgr"] = sg.short_name

src/diffpy/structure/structure.py

@@ -40,6 +40,24 @@
     "get_last_atom",
     removal_version,
 )
+placeInLattice_deprecation_msg = build_deprecation_message(
+    base,
+    "placeInLattice",
+    "place_in_lattice",
+    removal_version,
+)
+readStr_deprecation_msg = build_deprecation_message(
+    base,
+    "readStr",
+    "read_structure",
+    removal_version,
+)
+writeStr_deprecation_msg = build_deprecation_message(
+    base,
+    "writeStr",
+    "write_structure",
+    removal_version,
+)
 
 
 class Structure(list):
@@ -282,7 +300,16 @@ def angle(self, aid0, aid1, aid2):
         u12 = a2.xyz - a1.xyz
         return self.lattice.angle(u10, u12)
 
+    @deprecated(placeInLattice_deprecation_msg)
     def placeInLattice(self, new_lattice):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.Structure.place_in_lattice instead.
+        """
+        return self.place_in_lattice(new_lattice)
+
+    def place_in_lattice(self, new_lattice):
         """Place structure into `new_lattice` coordinate system.
 
         Sets `lattice` to `new_lattice` and recalculate fractional coordinates
@@ -345,7 +372,16 @@ def read(self, filename, format="auto"):
             self.title = tailbase
         return p
 
+    @deprecated(readStr_deprecation_msg)
     def readStr(self, s, format="auto"):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.Structure.read_structure instead.
+        """
+        return self.read_structure(s, format)
+
+    def read_structure(self, s, format="auto"):
         """Read structure from a string.
 
         Parameters
@@ -399,7 +435,16 @@ def write(self, filename, format):
             fp.write(s)
         return
 
+    @deprecated(writeStr_deprecation_msg)
     def writeStr(self, format):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.Structure.write_structure instead.
+        """
+        return self.write_structure(format)
+
+    def write_structure(self, format):
         """Return string representation of the structure in specified
         format.
 
@@ -537,7 +582,7 @@ def __getitem__(self, idx):
         >>> stru['Na3', 2, 'Cl2']
         """
         if isinstance(idx, slice):
-            rv = self.__emptySharedStructure()
+            rv = self.__empty_shared_structure()
             lst = super(Structure, self).__getitem__(idx)
             rv.extend(lst, copy=False)
             return rv
@@ -556,7 +601,7 @@ def __getitem__(self, idx):
                 idx1 = numpy.r_[idx]
             indices = numpy.arange(len(self))[idx1]
             rhs = [list.__getitem__(self, i) for i in indices]
-            rv = self.__emptySharedStructure()
+            rv = self.__empty_shared_structure()
             rv.extend(rhs, copy=False)
             return rv
         # here we need to resolve at least one string label
@@ -917,7 +962,7 @@ def _get_composition(self):
 
     # Private Methods --------------------------------------------------------
 
-    def __emptySharedStructure(self):
+    def __empty_shared_structure(self):
         """Return empty `Structure` with standard attributes same as in
         self."""
         rv = Structure()

tests/test_p_cif.py

@@ -224,6 +224,33 @@ def test_write_and_read(self):
         self.assertAlmostEqual(0.046164, a3.U[2, 2])
         return
 
+    def test_write_structure_and_read_structure(self):
+        """High-level check of P_cif.tostring()"""
+        # high-level check
+        stru_check = Structure()
+        stru_check.read(self.cdsebulkpdffitfile)
+        s_s = stru_check.write_structure("cif")
+        stru = Structure()
+        stru.read_structure(s_s, "cif")
+        self.assertAlmostEqual(4.2352, stru.lattice.a, self.places)
+        self.assertAlmostEqual(4.2352, stru.lattice.b, self.places)
+        self.assertAlmostEqual(6.90603, stru.lattice.c, self.places)
+        self.assertEqual(4, len(stru))
+        a0 = stru[0]
+        self.assertEqual("Cd", a0.element)
+        self.assertTrue(numpy.allclose([0.3334, 0.6667, 0.0], a0.xyz))
+        self.assertTrue(a0.anisotropy)
+        self.assertAlmostEqual(0.01303, a0.U[0, 0])
+        self.assertAlmostEqual(0.01303, a0.U[1, 1])
+        self.assertAlmostEqual(0.01402, a0.U[2, 2])
+        a3 = stru[3]
+        self.assertEqual("Se", a3.element)
+        self.assertTrue(numpy.allclose([0.6666, 0.333300, 0.87667], a3.xyz))
+        self.assertAlmostEqual(0.015673, a3.U[0, 0])
+        self.assertAlmostEqual(0.015673, a3.U[1, 1])
+        self.assertAlmostEqual(0.046164, a3.U[2, 2])
+        return
+
     def test_eps(self):
         """Test the P_cif.eps coordinates resolution."""
         pcif = P_cif()

tests/test_p_discus.py

@@ -91,53 +91,53 @@ def test_ignored_lines(self):
         ni_lines.insert(2, r1)
         ni_lines.insert(4, r2)
         s_s1 = "".join(ni_lines)
-        p = self.stru.readStr(s_s1, self.format)
+        p = self.stru.read_structure(s_s1, self.format)
         self.assertEqual([r1.rstrip(), r2.rstrip()], p.ignored_lines)
         ni_lines.append(r1)
         s_s2 = "".join(ni_lines)
-        self.assertRaises(StructureFormatError, self.stru.readStr, s_s2, self.format)
+        self.assertRaises(StructureFormatError, self.stru.read_structure, s_s2, self.format)
         return
 
     def test_spdiameter_parsing(self):
         """Check parsing of spdiameter record from a file."""
         stru = self.stru
         stru.read(self.datafile("Ni-discus.stru"), self.format)
         self.assertEqual(0, stru.pdffit["spdiameter"])
-        snoshape = stru.writeStr(format=self.format)
+        snoshape = stru.write_structure(format=self.format)
         self.assertTrue(not re.search("(?m)^shape", snoshape))
         # produce a string with non-zero spdiameter
         stru.pdffit["spdiameter"] = 13
-        s13 = stru.writeStr(format=self.format)
+        s13 = stru.write_structure(format=self.format)
         self.assertTrue(re.search("(?m)^shape +sphere, ", s13))
         stru13 = Structure()
-        stru13.readStr(s13)
+        stru13.read_structure(s13)
         self.assertEqual(13, stru13.pdffit["spdiameter"])
         with open(self.datafile("Ni.stru")) as fp:
             ni_lines = fp.readlines()
         ni_lines.insert(3, "shape invalid, 7\n")
         sbad = "".join(ni_lines)
-        self.assertRaises(StructureFormatError, self.stru.readStr, sbad, format=self.format)
+        self.assertRaises(StructureFormatError, self.stru.read_structure, sbad, format=self.format)
         return
 
     def test_stepcut_parsing(self):
         """Check parsing of stepcut record from a file."""
         stru = self.stru
         stru.read(self.datafile("Ni-discus.stru"), self.format)
         self.assertEqual(0, stru.pdffit["stepcut"])
-        snoshape = stru.writeStr(format=self.format)
+        snoshape = stru.write_structure(format=self.format)
         self.assertTrue(not re.search("(?m)^shape", snoshape))
         # produce a string with non-zero stepcut
         stru.pdffit["stepcut"] = 13
-        s13 = stru.writeStr(format=self.format)
+        s13 = stru.write_structure(format=self.format)
         self.assertTrue(re.search("(?m)^shape +stepcut, ", s13))
         stru13 = Structure()
-        stru13.readStr(s13)
+        stru13.read_structure(s13)
         self.assertEqual(13, stru13.pdffit["stepcut"])
         with open(self.datafile("Ni.stru")) as fp:
             ni_lines = fp.readlines()
         ni_lines.insert(3, "shape invalid, 7\n")
         sbad = "".join(ni_lines)
-        self.assertRaises(StructureFormatError, self.stru.readStr, sbad, format=self.format)
+        self.assertRaises(StructureFormatError, self.stru.read_structure, sbad, format=self.format)
         return
 
 

tests/test_p_pdffit.py

@@ -172,7 +172,7 @@ def test_writeStr_pdffit(self):
             f_s = fp.read()
         f_s = re.sub("[ \t]+", " ", f_s)
         f_s = re.sub("[ \t]+\n", "\n", f_s)
-        s_s = stru.writeStr(self.format)
+        s_s = stru.write_structure(self.format)
         s_s = re.sub("[ \t]+", " ", s_s)
         self.assertEqual(f_s, s_s)
         return
@@ -181,9 +181,9 @@ def test_huge_occupancy(self):
         """Check structure with huge occupancy can be read."""
         self.stru.read(self.datafile("Ni.stru"), self.format)
         self.stru[0].occupancy = 16e16
-        s_s = self.stru.writeStr(self.format)
+        s_s = self.stru.write_structure(self.format)
         stru1 = Structure()
-        stru1.readStr(s_s, self.format)
+        stru1.read_structure(s_s, self.format)
         self.assertEqual(16e16, stru1[0].occupancy)
         return
 
@@ -196,53 +196,53 @@ def test_ignored_lines(self):
         ni_lines.insert(2, r1 + "\n")
         ni_lines.insert(4, r2 + "\n")
         s_s1 = "".join(ni_lines)
-        p = self.stru.readStr(s_s1, self.format)
+        p = self.stru.read_structure(s_s1, self.format)
         self.assertEqual([r1, r2], p.ignored_lines)
         ni_lines.insert(-3, r1 + "\n")
         s_s2 = "".join(ni_lines)
-        self.assertRaises(StructureFormatError, self.stru.readStr, s_s2, self.format)
+        self.assertRaises(StructureFormatError, self.stru.read_structure, s_s2, self.format)
         return
 
     def test_spdiameter_parsing(self):
         """Check parsing of spdiameter record from a file."""
         stru = self.stru
         stru.read(self.datafile("Ni.stru"), self.format)
         self.assertEqual(0, stru.pdffit["spdiameter"])
-        snoshape = stru.writeStr(format=self.format)
+        snoshape = stru.write_structure(format=self.format)
         self.assertTrue(not re.search("(?m)^shape", snoshape))
         # produce a string with non-zero spdiameter
         stru.pdffit["spdiameter"] = 13
-        s13 = stru.writeStr(format=self.format)
+        s13 = stru.write_structure(format=self.format)
         self.assertTrue(re.search("(?m)^shape +sphere, ", s13))
         stru13 = Structure()
-        stru13.readStr(s13)
+        stru13.read_structure(s13)
         self.assertEqual(13, stru13.pdffit["spdiameter"])
         with open(self.datafile("Ni.stru")) as fp:
             ni_lines = fp.readlines()
         ni_lines.insert(3, "shape invalid, 7\n")
         sbad = "".join(ni_lines)
-        self.assertRaises(StructureFormatError, self.stru.readStr, sbad, format=self.format)
+        self.assertRaises(StructureFormatError, self.stru.read_structure, sbad, format=self.format)
         return
 
     def test_stepcut_parsing(self):
         """Check parsing of stepcut record from a file."""
         stru = self.stru
         stru.read(self.datafile("Ni.stru"), self.format)
         self.assertEqual(0, stru.pdffit["stepcut"])
-        snoshape = stru.writeStr(format=self.format)
+        snoshape = stru.write_structure(format=self.format)
         self.assertTrue(not re.search("(?m)^shape", snoshape))
         # produce a string with non-zero stepcut
         stru.pdffit["stepcut"] = 13
-        s13 = stru.writeStr(format=self.format)
+        s13 = stru.write_structure(format=self.format)
         self.assertTrue(re.search("(?m)^shape +stepcut, ", s13))
         stru13 = Structure()
-        stru13.readStr(s13)
+        stru13.read_structure(s13)
         self.assertEqual(13, stru13.pdffit["stepcut"])
         with open(self.datafile("Ni.stru")) as fp:
             ni_lines = fp.readlines()
         ni_lines.insert(3, "shape invalid, 7\n")
         sbad = "".join(ni_lines)
-        self.assertRaises(StructureFormatError, self.stru.readStr, sbad, format=self.format)
+        self.assertRaises(StructureFormatError, self.stru.read_structure, sbad, format=self.format)
         return