Deprecate Particle methods from_string and from_string_list (#354)

* Deprecate from_string and from_string_list

* __main__.py: replace from_string_list with findall

* Adapt tests to deprecation warnings

* Deprecated _from_group_dict_list as well since only used by what gets deprecated in this MR

* No longer accept ad-hoc AmpGen style of particle names

* Remove a decorated duplicately added by mistake

* Do not add a deprecated warning to a private method

* style: pre-commit fixes

* Conflicts resolved wet master

* __main__.py: replace from_string_list with findall

* Adapt tests to deprecation warnings

* Minor fix

* Add dependencies and imports for deprecated

* style: pre-commit fixes

* Add a missing 'with pytest.deprecated_call():'

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

.pre-commit-config.yaml

@@ -34,7 +34,7 @@ repos:
   hooks:
   - id: mypy
     files: src
-    additional_dependencies: [attrs==21.4.0, hepunits>=2.2.0, importlib_resources]
+    additional_dependencies: [attrs==21.4.0, hepunits>=2.2.0, importlib_resources, types-deprecated]
     args: [--show-error-codes]
 
 - repo: https://github.com/codespell-project/codespell

pyproject.toml

@@ -44,6 +44,7 @@ dependencies = [
     "hepunits>=2.0.0",
     "importlib-resources>=2.0;python_version<\"3.9\"",
     "typing-extensions;python_version<\"3.8\"",
+    "deprecated"
 ]
 dynamic = ["version"]
 

src/particle/__main__.py

@@ -55,7 +55,7 @@ def main() -> None:
             if value:
                 particles = [Particle.from_pdgid(value)]
             else:
-                particles = Particle.from_string_list(cand)
+                particles = Particle.findall(cand)
 
             if not particles:
                 print("Particle", cand, "not found.")

src/particle/particle/particle.py

@@ -15,6 +15,7 @@
 
 # External dependencies
 import attr
+from deprecated import deprecated
 from hepunits.constants import c_light
 
 from .. import data
@@ -1238,6 +1239,10 @@ def findall(
         )
 
     @classmethod
+    @deprecated(
+        version="0.21",
+        reason="This method is deprecated and will be removed from version 0.22.0. Use finditer or findall instead.",
+    )
     def from_string(cls: type[Self], name: str) -> Self:
         "Get a particle from a PDG style name - returns the best match."
         matches = cls.from_string_list(name)
@@ -1246,6 +1251,10 @@ def from_string(cls: type[Self], name: str) -> Self:
         raise ParticleNotFound(f"{name} not found in particle table")
 
     @classmethod
+    @deprecated(
+        version="0.21",
+        reason="This method is deprecated and will be removed from version 0.22.0. Use finditer or findall instead.",
+    )
     def from_string_list(cls: type[Self], name: str) -> list[Self]:
         "Get a list of particles from a PDG style name."
 

tests/particle/test_particle.py

@@ -221,10 +221,11 @@ def test_int_compare():
 
 
 def test_string():
-    pi = Particle.from_string("pi+")
+    with pytest.deprecated_call():
+        pi = Particle.from_string("pi+")
     assert pi.pdgid == 211
 
-    with pytest.raises(ParticleNotFound):
+    with pytest.raises(ParticleNotFound), pytest.deprecated_call():
         Particle.from_string("unknown")
 
 
@@ -233,7 +234,8 @@ def test_fuzzy_string():
     The input name is not specific enough, in which case the search is done
     by pdg_name after failing a match by name.
     """
-    p = Particle.from_string("a(0)(980)")  # all 3 charge stages match
+    with pytest.deprecated_call():
+        p = Particle.from_string("a(0)(980)")  # all 3 charge stages match
     assert p.pdgid == 9000111
 
 
@@ -680,7 +682,8 @@ def test_to_dict():
 
 @pytest.mark.parametrize(("name", "pid"), ampgen_style_names)
 def test_ampgen_style_names(name, pid):
-    particle = Particle.from_string(name)
+    with pytest.deprecated_call():
+        particle = Particle.from_string(name)
 
     assert particle.pdgid == pid
     assert particle == pid