diff --git a/news/deprecate-getParser.rst b/news/deprecate-getParser.rst new file mode 100644 index 0000000..99e3f33 --- /dev/null +++ b/news/deprecate-getParser.rst @@ -0,0 +1,39 @@ +**Added:** + +* Added ``get_parser`` method in ``p_auto.py`` +* Added ``get_parser`` method in ``p_cif.py`` +* Added ``get_parser`` method in ``p_discus.py`` +* Added ``get_parser`` method in ``p_pdb.py`` +* Added ``get_parser`` method in ``p_pdffit.py`` +* Added ``get_parser`` method in ``p_rawxyz.py`` +* Added ``get_parser`` method in ``p_xcfg.py`` +* Added ``get_parser`` method in ``p_xyz.py`` +* Added ``get_parser`` method in ``parsers/__init__.py`` + +**Changed:** + +* + +**Deprecated:** + +* Deprecated ``getParser`` method in ``p_auto.py`` for removal in version 4.0.0 +* Deprecated ``getParser`` method in ``p_cif.py`` for removal in version 4.0.0 +* Deprecated ``getParser`` method in ``p_discus.py`` for removal in version 4.0.0 +* Deprecated ``getParser`` method in ``p_pdb.py`` for removal in version 4.0.0 +* Deprecated ``getParser`` method in ``p_pdffit.py`` for removal in version 4.0.0 +* Deprecated ``getParser`` method in ``p_rawxyz.py`` for removal in version 4.0.0 +* Deprecated ``getParser`` method in ``p_xcfg.py`` for removal in version 4.0.0 +* Deprecated ``getParser`` method in ``p_xyz.py`` for removal in version 4.0.0 +* Deprecated ``getParser`` method in ``parsers/__init__.py`` for removal in version 4.0.0 + +**Removed:** + +* + +**Fixed:** + +* + +**Security:** + +* diff --git a/src/diffpy/structure/__init__.py b/src/diffpy/structure/__init__.py index 3624048..969b732 100644 --- a/src/diffpy/structure/__init__.py +++ b/src/diffpy/structure/__init__.py @@ -39,7 +39,7 @@ import diffpy.structure as _structure from diffpy.structure.atom import Atom from diffpy.structure.lattice import Lattice -from diffpy.structure.parsers import getParser +from diffpy.structure.parsers import get_parser from diffpy.structure.pdffitstructure import PDFFitStructure from diffpy.structure.structure import Structure from diffpy.structure.structureerrors import LatticeError, StructureFormatError, SymmetryError @@ -97,7 +97,7 @@ def loadStructure(filename, fmt="auto", **kw): and 'discus' formats. """ - p = getParser(fmt, **kw) + p = get_parser(fmt, **kw) rv = p.parse_file(filename) return rv diff --git a/src/diffpy/structure/parsers/__init__.py b/src/diffpy/structure/parsers/__init__.py index cb9bd4f..6bf1231 100644 --- a/src/diffpy/structure/parsers/__init__.py +++ b/src/diffpy/structure/parsers/__init__.py @@ -33,14 +33,48 @@ from diffpy.structure.parsers.parser_index_mod import parser_index from diffpy.structure.parsers.structureparser import StructureParser from diffpy.structure.structureerrors import StructureFormatError +from diffpy.utils._deprecator import build_deprecation_message, deprecated # silence pyflakes checker assert StructureParser +parsers_base = "diffpy.structure" +removal_version = "4.0.0" +getParser_deprecation_msg = build_deprecation_message( + parsers_base, + "getParser", + "get_parser", + removal_version, +) + +@deprecated(getParser_deprecation_msg) def getParser(format, **kw): """Return Parser instance for a given structure format. + Parameters + ---------- + format : str + String with the format name, see `parser_index_mod`. + **kw : dict + Keyword arguments passed to the Parser init function. + + Returns + ------- + Parser + Parser instance for the given format. + + Raises + ------ + StructureFormatError + When the format is not defined. + """ + return get_parser(format, **kw) + + +def get_parser(format, **kw): + """Return Parser instance for a given structure format. + Parameters ---------- format : str @@ -65,7 +99,7 @@ def getParser(format, **kw): ns = {} import_cmd = "from diffpy.structure.parsers import %s as pm" % pmod exec(import_cmd, ns) - return ns["pm"].getParser(**kw) + return ns["pm"].get_parser(**kw) def inputFormats(): diff --git a/src/diffpy/structure/parsers/p_auto.py b/src/diffpy/structure/parsers/p_auto.py index ed00dcb..eb5fbe3 100644 --- a/src/diffpy/structure/parsers/p_auto.py +++ b/src/diffpy/structure/parsers/p_auto.py @@ -206,14 +206,14 @@ def _wrap_parse_method(self, method: object, *args: object, **kwargs: object) -> ------ StructureFormatError """ - from diffpy.structure.parsers import getParser + from diffpy.structure.parsers import get_parser ofmts = self._get_ordered_formats() stru = None # try all parsers in sequence parsers_emsgs = [] for fmt in ofmts: - p = getParser(fmt, **self.pkw) + p = get_parser(fmt, **self.pkw) try: pmethod = getattr(p, method) stru = pmethod(*args, **kwargs) @@ -240,10 +240,36 @@ def _wrap_parse_method(self, method: object, *args: object, **kwargs: object) -> # Routines ------------------------------------------------------------------- +parsers_base = "diffpy.structure" +removal_version = "4.0.0" +getParser_deprecation_msg = build_deprecation_message( + parsers_base, + "getParser", + "get_parser", + removal_version, +) + +@deprecated(getParser_deprecation_msg) def getParser(**kw): """Return a new instance of the automatic parser. + Parameters + ---------- + **kw : dict + Keyword arguments for the structure parser + + Returns + ------- + P_auto + Instance of `P_auto`. + """ + return get_parser(**kw) + + +def get_parser(**kw): + """Return a new instance of the automatic parser. + Parameters ---------- **kw : dict diff --git a/src/diffpy/structure/parsers/p_cif.py b/src/diffpy/structure/parsers/p_cif.py index 4a88983..2f58bd5 100644 --- a/src/diffpy/structure/parsers/p_cif.py +++ b/src/diffpy/structure/parsers/p_cif.py @@ -817,6 +817,13 @@ def to_lines(self, stru): # Routines ------------------------------------------------------------------- +parsers_base = "diffpy.structure" +getParser_deprecation_msg = build_deprecation_message( + parsers_base, + "getParser", + "get_parser", + removal_version, +) # constant regular expression for leading_float() rx_float = re.compile(r"[-+]?(\d+(\.\d*)?|\.\d+)([eE][-+]?\d+)?") @@ -901,9 +908,27 @@ def getSymOp(s): return rv +@deprecated(getParser_deprecation_msg) def getParser(eps=None): """Return new `parser` object for CIF format. + Parameters + ---------- + eps : float, Optional + fractional coordinates cutoff for duplicate positions. + When ``None`` use the default for `ExpandAsymmetricUnit`: ``1.0e-5``. + + Returns + ------- + P_cif + Instance of `P_cif`. + """ + return get_parser(eps) + + +def get_parser(eps=None): + """Return new `parser` object for CIF format. + Parameters ---------- eps : float, Optional diff --git a/src/diffpy/structure/parsers/p_discus.py b/src/diffpy/structure/parsers/p_discus.py index 46b5254..0fc7122 100644 --- a/src/diffpy/structure/parsers/p_discus.py +++ b/src/diffpy/structure/parsers/p_discus.py @@ -412,10 +412,31 @@ def _parse_not_implemented(self, words): # Routines ------------------------------------------------------------------- +parsers_base = "diffpy.structure" +removal_version = "4.0.0" +getParser_deprecation_msg = build_deprecation_message( + parsers_base, + "getParser", + "get_parser", + removal_version, +) + +@deprecated(getParser_deprecation_msg) def getParser(): """Return new `parser` object for DISCUS format. + Returns + ------- + P_discus + Instance of `P_discus`. + """ + return get_parser() + + +def get_parser(): + """Return new `parser` object for DISCUS format. + Returns ------- P_discus diff --git a/src/diffpy/structure/parsers/p_pdb.py b/src/diffpy/structure/parsers/p_pdb.py index 3dd7294..7e3bbef 100644 --- a/src/diffpy/structure/parsers/p_pdb.py +++ b/src/diffpy/structure/parsers/p_pdb.py @@ -454,10 +454,30 @@ def to_lines(self, stru): # Routines ------------------------------------------------------------------- +parsers_base = "diffpy.structure" +getParser_deprecation_msg = build_deprecation_message( + parsers_base, + "getParser", + "get_parser", + removal_version, +) + +@deprecated(getParser_deprecation_msg) def getParser(): """Return new `parser` object for PDB format. + Returns + ------- + P_pdb + Instance of `P_pdb`. + """ + return get_parser() + + +def get_parser(): + """Return new `parser` object for PDB format. + Returns ------- P_pdb diff --git a/src/diffpy/structure/parsers/p_pdffit.py b/src/diffpy/structure/parsers/p_pdffit.py index 5d4ae57..bc3f187 100644 --- a/src/diffpy/structure/parsers/p_pdffit.py +++ b/src/diffpy/structure/parsers/p_pdffit.py @@ -388,6 +388,17 @@ def _parse_shape(self, line): def getParser(): """Return new `parser` object for PDFfit format. + Returns + ------- + P_pdffit + Instance of `P_pdffit`. + """ + return get_parser() + + +def get_parser(): + """Return new `parser` object for PDFfit format. + Returns ------- P_pdffit diff --git a/src/diffpy/structure/parsers/p_rawxyz.py b/src/diffpy/structure/parsers/p_rawxyz.py index d462739..fc115fa 100644 --- a/src/diffpy/structure/parsers/p_rawxyz.py +++ b/src/diffpy/structure/parsers/p_rawxyz.py @@ -170,10 +170,30 @@ def to_lines(self, stru): # Routines ------------------------------------------------------------------- +parsers_base = "diffpy.structure" +getParser_deprecation_msg = build_deprecation_message( + parsers_base, + "getParser", + "get_parser", + removal_version, +) + +@deprecated(getParser_deprecation_msg) def getParser(): """Return new `parser` object for RAWXYZ format. + Returns + ------- + P_rawxyz + Instance of `P_rawxyz`. + """ + return get_parser() + + +def get_parser(): + """Return new `parser` object for RAWXYZ format. + Returns ------- P_rawxyz diff --git a/src/diffpy/structure/parsers/p_xcfg.py b/src/diffpy/structure/parsers/p_xcfg.py index b1006be..c5709a8 100644 --- a/src/diffpy/structure/parsers/p_xcfg.py +++ b/src/diffpy/structure/parsers/p_xcfg.py @@ -447,10 +447,30 @@ def to_lines(self, stru): # Routines ------------------------------------------------------------------- +parsers_base = "diffpy.structure" +getParser_deprecation_msg = build_deprecation_message( + parsers_base, + "getParser", + "get_parser", + removal_version, +) + +@deprecated(getParser_deprecation_msg) def getParser(): """Return new `parser` object for XCFG format. + Returns + ------- + P_xcfg + Instance of `P_xcfg`. + """ + return get_parser() + + +def get_parser(): + """Return new `parser` object for XCFG format. + Returns ------- P_xcfg diff --git a/src/diffpy/structure/parsers/p_xyz.py b/src/diffpy/structure/parsers/p_xyz.py index b94def8..0238ecc 100644 --- a/src/diffpy/structure/parsers/p_xyz.py +++ b/src/diffpy/structure/parsers/p_xyz.py @@ -182,10 +182,30 @@ def to_lines(self, stru): # Routines ------------------------------------------------------------------- +parsers_base = "diffpy.structure" +getParser_deprecation_msg = build_deprecation_message( + parsers_base, + "getParser", + "get_parser", + removal_version, +) + +@deprecated(getParser_deprecation_msg) def getParser(): """Return new `parser` object for XYZ format. + Returns + ------- + P_xcfg + Instance of `P_xyz`. + """ + return get_parser() + + +def get_parser(): + """Return new `parser` object for XYZ format. + Returns ------- P_xcfg diff --git a/src/diffpy/structure/structure.py b/src/diffpy/structure/structure.py index ec1e86a..c351e93 100644 --- a/src/diffpy/structure/structure.py +++ b/src/diffpy/structure/structure.py @@ -355,8 +355,8 @@ def read(self, filename, format="auto"): import diffpy.structure import diffpy.structure.parsers - getParser = diffpy.structure.parsers.getParser - p = getParser(format) + get_parser = diffpy.structure.parsers.get_parser + p = get_parser(format) new_structure = p.parse_file(filename) # reinitialize data after successful parsing # avoid calling __init__ from a derived class @@ -398,9 +398,9 @@ def read_structure(self, s, format="auto"): Return instance of data Parser used to process input string. This can be inspected for information related to particular format. """ - from diffpy.structure.parsers import getParser + from diffpy.structure.parsers import get_parser - p = getParser(format) + p = get_parser(format) new_structure = p.parse(s) # reinitialize data after successful parsing # avoid calling __init__ from a derived class @@ -426,9 +426,9 @@ def write(self, filename, format): ``from parsers import formats`` """ - from diffpy.structure.parsers import getParser + from diffpy.structure.parsers import get_parser - p = getParser(format) + p = get_parser(format) p.filename = filename s = p.tostring(self) with open(filename, "w", encoding="utf-8", newline="") as fp: @@ -454,9 +454,9 @@ def write_structure(self, format): ``from parsers import formats`` """ - from diffpy.structure.parsers import getParser + from diffpy.structure.parsers import get_parser - p = getParser(format) + p = get_parser(format) s = p.tostring(self) return s diff --git a/tests/test_p_cif.py b/tests/test_p_cif.py index b4c88b3..fd63f03 100644 --- a/tests/test_p_cif.py +++ b/tests/test_p_cif.py @@ -20,7 +20,7 @@ import pytest from diffpy.structure import Structure -from diffpy.structure.parsers import getParser +from diffpy.structure.parsers import get_parser, getParser from diffpy.structure.parsers.p_cif import P_cif, getSymOp, leading_float from diffpy.structure.structureerrors import StructureFormatError @@ -466,6 +466,19 @@ def test_getParser(self): self.assertEqual(4, len(grph2)) return + def test_get_parser(self): + """Test passing of eps keyword argument by get_parser + function.""" + pcif = get_parser("cif", eps=1e-6) + 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 = get_parser("cif") + grph2 = pcif2.parse_file(self.graphiteciffile) + self.assertEqual(4, len(grph2)) + return + # End of class TestP_cif