chore: deprecate parseFile method

news/deprecate-parsefile.rst

@@ -0,0 +1,27 @@
+**Added:**
+
+* Added ``parse_file`` method in ``structureparser.py``
+* Added ``parse_lines`` method in ``p_cif.py``
+* Added ``parse_lines`` method in ``p_auto.py``
+
+**Changed:**
+
+* <news item>
+
+**Deprecated:**
+
+* Deprecated ``parse_file`` method in ``structureparser.py`` for removal in version 4.0.0
+* Deprecated ``parse_file`` method in ``p_cif.py`` for removal in version 4.0.0
+* Deprecated ``parse_file`` method in ``p_auto.py`` for removal in version 4.0.0
+
+**Removed:**
+
+* <news item>
+
+**Fixed:**
+
+* <news item>
+
+**Security:**
+
+* <news item>

src/diffpy/structure/__init__.py

@@ -98,7 +98,7 @@ def loadStructure(filename, fmt="auto", **kw):
     """
 
     p = getParser(fmt, **kw)
-    rv = p.parseFile(filename)
+    rv = p.parse_file(filename)
     return rv
 
 

src/diffpy/structure/parsers/p_auto.py

@@ -32,6 +32,12 @@
     "parse_lines",
     removal_version,
 )
+parseFile_deprecation_msg = build_deprecation_message(
+    base,
+    "parseFile",
+    "parse_file",
+    removal_version,
+)
 
 
 class P_auto(StructureParser):
@@ -139,7 +145,16 @@ def parse(self, s):
         """
         return self._wrap_parse_method("parse", s)
 
+    @deprecated(parseFile_deprecation_msg)
     def parseFile(self, filename):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.P_auto.parse_file instead.
+        """
+        return self.parse_file(filename)
+
+    def parse_file(self, filename):
         """Detect format and create Structure instance from an existing
         file.
 
@@ -163,7 +178,7 @@ def parseFile(self, filename):
             If the file cannot be read.
         """
         self.filename = filename
-        return self._wrap_parse_method("parseFile", filename)
+        return self._wrap_parse_method("parse_file", filename)
 
     def _wrap_parse_method(self, method: object, *args: object, **kwargs: object) -> Any:
         """A helper evaluator method that try the specified parse method

src/diffpy/structure/parsers/p_cif.py

@@ -50,6 +50,12 @@
     "parse_lines",
     removal_version,
 )
+parseFile_deprecation_msg = build_deprecation_message(
+    base,
+    "parseFile",
+    "parse_file",
+    removal_version,
+)
 
 
 class P_cif(StructureParser):
@@ -372,7 +378,16 @@ def parse_lines(self, lines):
         s = "\n".join(lines) + "\n"
         return self.parse(s)
 
+    @deprecated(parseFile_deprecation_msg)
     def parseFile(self, filename):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.P_cif.parse_file instead.
+        """
+        return self.parse_file(filename)
+
+    def parse_file(self, filename):
         """Create Structure from an existing CIF file.
 
         Parameters

src/diffpy/structure/parsers/structureparser.py

@@ -24,6 +24,12 @@
     "parse_lines",
     removal_version,
 )
+parseFile_deprecation_msg = build_deprecation_message(
+    base,
+    "parseFile",
+    "parse_file",
+    removal_version,
+)
 
 
 class StructureParser(object):
@@ -86,7 +92,16 @@ def tostring(self, stru):
         s = "\n".join(lines) + "\n"
         return s
 
+    @deprecated(parseFile_deprecation_msg)
     def parseFile(self, filename):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use diffpy.structure.StructureParser.parse_file instead.
+        """
+        return self.parse_file(filename)
+
+    def parse_file(self, filename):
         """Create Structure instance from an existing file."""
         self.filename = filename
         with open(filename) as fp:

src/diffpy/structure/structure.py

@@ -357,7 +357,7 @@ def read(self, filename, format="auto"):
 
         getParser = diffpy.structure.parsers.getParser
         p = getParser(format)
-        new_structure = p.parseFile(filename)
+        new_structure = p.parse_file(filename)
         # reinitialize data after successful parsing
         # avoid calling __init__ from a derived class
         Structure.__init__(self)

tests/test_p_cif.py

@@ -173,6 +173,49 @@ def test_parseFile(self):
         self.assertEqual(16, len(ptei))
         return
 
+    def test_parse_file(self):
+        """Check P_cif.parse_file()"""
+        # pbteciffile
+        stru = self.pfile.parse_file(self.pbteciffile)
+        self.assertEqual(8, len(stru))
+        self.assertEqual(6.461, stru.lattice.a)
+        self.assertEqual(6.461, stru.lattice.b)
+        self.assertEqual(6.461, stru.lattice.c)
+        self.assertEqual(90.0, stru.lattice.alpha)
+        self.assertEqual(90.0, stru.lattice.beta)
+        self.assertEqual(90.0, stru.lattice.gamma)
+        self.assertEqual("Fm-3m", self.pfile.spacegroup.short_name)
+        a0 = stru[0]
+        self.assertEqual(0.5, a0.x)
+        self.assertEqual(0.5, a0.y)
+        self.assertEqual(0.5, a0.z)
+        self.assertEqual(False, a0.anisotropy)
+        self.assertEqual(1.0, a0.occupancy)
+        self.assertEqual(0.0225566, a0.Uisoequiv)
+        # badciffile
+        pfile2 = P_cif()
+        self.assertRaises(StructureFormatError, pfile2.parse_file, self.badciffile)
+        # graphite
+        pgraphite = P_cif()
+        graphite = pgraphite.parse_file(self.graphiteciffile)
+        self.assertEqual(4, len(graphite))
+        c1 = graphite[0]
+        self.assertEqual(str, type(c1.element))
+        self.assertEqual("C", c1.element)
+        self.assertEqual(str, type(c1.label))
+        self.assertEqual("C1", c1.label)
+        # filename with unicode encoding
+        hasbs = "\\" in self.graphiteciffile
+        uciffile = self.graphiteciffile.replace("\\", "/")
+        if hasbs:  # pragma: no cover
+            uciffile = uciffile.replace("/", "\\")
+        ugraphite = P_cif().parse_file(uciffile)
+        self.assertEqual(4, len(ugraphite))
+        # File with full space group name
+        ptei = P_cif().parse_file(self.teiciffile)
+        self.assertEqual(16, len(ptei))
+        return
+
     #   def test__parseCifBlock(self):
     #       """check P_cif._parseCifBlock()
     #       """
@@ -271,19 +314,19 @@ def test_eps(self):
         """Test the P_cif.eps coordinates resolution."""
         pcif = P_cif()
         pcif.eps = 1e-8
-        grph = pcif.parseFile(self.graphiteciffile)
+        grph = pcif.parse_file(self.graphiteciffile)
         self.assertEqual(8, len(grph))
         self.assertTrue(all(a.label.startswith("C1") for a in grph[:2]))
         self.assertTrue(all(a.label.startswith("C2") for a in grph[2:]))
         pcif2 = P_cif()
         pcif2.eps = 1e-3
-        grph2 = pcif2.parseFile(self.graphiteciffile)
+        grph2 = pcif2.parse_file(self.graphiteciffile)
         self.assertEqual(4, len(grph2))
         return
 
     def test_unknown_occupancy(self):
         "test CIF file with unknown occupancy data"
-        stru = self.ptest.parseFile(self.datafile("TeI-unkocc.cif"))
+        stru = self.ptest.parse_file(self.datafile("TeI-unkocc.cif"))
         self.assertTrue(numpy.array_equal(16 * [1], stru.occupancy))
         return
 
@@ -311,7 +354,7 @@ def test_unknown_spacegroup_number(self):
     def test_nosites_cif(self):
         """Test reading of CIF file with no valid sites."""
         ptest = self.ptest
-        stru = ptest.parseFile(self.datafile("nosites.cif"))
+        stru = ptest.parse_file(self.datafile("nosites.cif"))
         self.assertEqual(0, len(stru))
         self.assertEqual(10.413, stru.lattice.a)
         self.assertEqual(10.413, stru.lattice.b)
@@ -322,14 +365,14 @@ def test_badspacegroup_cif(self):
         """Test reading of CIF file with unrecognized space group."""
         ptest = self.ptest
         filename = self.datafile("badspacegroup.cif")
-        self.assertRaises(StructureFormatError, ptest.parseFile, filename)
+        self.assertRaises(StructureFormatError, ptest.parse_file, filename)
         return
 
     def test_custom_spacegroup_cif(self):
         """Test parsing of nonstandard symops-defined space group."""
         pfile = self.pfile
         filename = self.datafile("customsg.cif")
-        pfile.parseFile(filename)
+        pfile.parse_file(filename)
         sg = pfile.spacegroup
         self.assertEqual("CIF data", sg.short_name)
         self.assertEqual(6, len(sg.symop_list))
@@ -349,14 +392,14 @@ def test_spacegroup_isotropy(self):
 
     def test_spacegroup_anisotropy(self):
         "verify site anisotropy due to site symmetry."
-        stru = self.ptest.parseFile(self.graphiteciffile)
+        stru = self.ptest.parse_file(self.graphiteciffile)
         self.assertTrue(all(stru.anisotropy))
         return
 
     def test_spacegroup_ref(self):
         "verify space group reference"
         pfile = self.pfile
-        pfile.parseFile(self.refciffile)
+        pfile.parse_file(self.refciffile)
         sg = pfile.spacegroup
         self.assertEqual("Fm-3m", sg.short_name)
 
@@ -406,20 +449,20 @@ def test_unknown_aniso(self):
     def test_curly_brace(self):
         "verify loading of a CIF file with unquoted curly brace"
         ptest = self.ptest
-        stru = ptest.parseFile(self.datafile("curlybrackets.cif"))
+        stru = ptest.parse_file(self.datafile("curlybrackets.cif"))
         self.assertEqual(20, len(stru))
         return
 
     def test_getParser(self):
         """Test passing of eps keyword argument by getParser
         function."""
         pcif = getParser("cif", eps=1e-6)
-        grph = pcif.parseFile(self.graphiteciffile)
+        grph = pcif.parse_file(self.graphiteciffile)
         self.assertEqual(8, len(grph))
         self.assertTrue(all(a.label.startswith("C1") for a in grph[:2]))
         self.assertTrue(all(a.label.startswith("C2") for a in grph[2:]))
         pcif2 = getParser("cif")
-        grph2 = pcif2.parseFile(self.graphiteciffile)
+        grph2 = pcif2.parse_file(self.graphiteciffile)
         self.assertEqual(4, len(grph2))
         return