Make Z and mass_numb parameters for Particle keyword-only (#1456)

namurphy · web-flow · commit 319bffe9bd91 · 2022-03-02T10:54:27.000-05:00
* Make Z and mass_numb keyword-only in Particle

* Add changelog entry

* Raise explicit error

* Update explicit error message

* Allow multiple positional args in Particle error tests

* Test when Particle is provided with &gt;1 positional arg

...since Z and mass_numb should be keyword-only.

* Remove coverage: ignore comment
diff --git a/changelog/1456.breaking.rst b/changelog/1456.breaking.rst
@@ -0,0 +1,2 @@
+The parameters ``Z`` and ``mass_numb`` to |Particle| are now
+:term:`keyword-only`.
diff --git a/plasmapy/particles/particle_class.py b/plasmapy/particles/particle_class.py
@@ -234,10 +234,10 @@ class Particle(AbstractPhysicalParticle):
         integer representing the atomic number of an element; or a
         |Particle| instance.
 
-    mass_numb : `int`, optional
+    mass_numb : `int`, optional, keyword-only
         The mass number of an isotope or nuclide.
 
-    Z : `int`, optional
+    Z : `int`, optional, keyword-only
         The charge number of the particle.
 
     Raises
@@ -413,10 +413,19 @@ class Particle(AbstractPhysicalParticle):
     def __init__(
         self,
         argument: ParticleLike,
+        *_,
         mass_numb: Integral = None,
         Z: Integral = None,
     ):
 
+        # TODO: Remove the following block during or after the 0.9.0 release
+
+        if _:
+            raise TypeError(
+                "The parameters mass_numb and Z to Particle are now "
+                "keyword-only [e.g., Particle('H', mass_numb=2, Z=1)]."
+            )
+
         # If argument is a Particle instance, then construct a new
         # Particle instance for the same particle.
 
diff --git a/plasmapy/particles/tests/test_particle_class.py b/plasmapy/particles/tests/test_particle_class.py
@@ -584,56 +584,60 @@ def test_Particle_equivalent_cases(equivalent_particles):
     run_test_equivalent_calls(Particle, *equivalent_particles)
 
 
-# arg, kwargs, attribute, exception
+# args, kwargs, attribute, exception
 test_Particle_error_table = [
-    ("a", {}, "", InvalidParticleError),
-    ("d+", {"mass_numb": 9}, "", InvalidParticleError),
-    ("H", {"mass_numb": 99}, "", InvalidParticleError),
-    ("Au-818", {}, "", InvalidParticleError),
-    ("Au-12", {}, "", InvalidParticleError),
-    ("Au", {"mass_numb": 13}, "", InvalidParticleError),
-    ("Au", {"mass_numb": 921}, "", InvalidParticleError),
-    ("e-", {"Z": -1}, "", InvalidParticleError),
-    ("e-", {}, ".atomic_number", InvalidElementError),
-    ("alpha", {}, ".standard_atomic_weight", InvalidElementError),
-    ("Fe-56", {}, ".standard_atomic_weight", InvalidElementError),
-    ("e-", {}, ".standard_atomic_weight", InvalidElementError),
-    ("tau-", {}, ".element_name", InvalidElementError),
-    ("tau+", {}, ".atomic_number", InvalidElementError),
-    ("neutron", {}, ".atomic_number", InvalidElementError),
-    ("H", {"Z": 0}, ".mass_number", InvalidIsotopeError),
-    ("neutron", {}, ".mass_number", InvalidIsotopeError),
-    ("He", {"mass_numb": 4}, ".charge", ChargeError),
-    ("He", {"mass_numb": 4}, ".charge_number", ChargeError),
-    ("Fe", {}, ".spin", MissingParticleDataError),
-    ("nu_e", {}, ".mass", MissingParticleDataError),
-    ("Og", {}, ".standard_atomic_weight", MissingParticleDataError),
-    (Particle("C-14"), {"mass_numb": 13}, "", InvalidParticleError),
-    (Particle("Au 1+"), {"Z": 2}, "", InvalidParticleError),
-    ([], {}, "", TypeError),
-    ("Fe", {}, ".ionize()", ChargeError),
-    ("D", {}, ".recombine()", ChargeError),
-    ("Fe 26+", {}, ".ionize()", InvalidIonError),
-    ("Fe 6+", {}, ".ionize(-1)", ValueError),
-    ("Fe 25+", {}, ".recombine(0)", ValueError),
-    ("Fe 6+", {}, ".ionize(4.6)", TypeError),
-    ("Fe 25+", {}, ".recombine(8.2)", TypeError),
-    ("e-", {}, ".ionize()", InvalidElementError),
-    ("e+", {}, ".recombine()", InvalidElementError),
+    (["a"], {}, "", InvalidParticleError),
+    (["d+"], {"mass_numb": 9}, "", InvalidParticleError),
+    (["H"], {"mass_numb": 99}, "", InvalidParticleError),
+    (["Au-818"], {}, "", InvalidParticleError),
+    (["Au-12"], {}, "", InvalidParticleError),
+    (["Au"], {"mass_numb": 13}, "", InvalidParticleError),
+    (["Au"], {"mass_numb": 921}, "", InvalidParticleError),
+    (["e-"], {"Z": -1}, "", InvalidParticleError),
+    (["e-"], {}, ".atomic_number", InvalidElementError),
+    (["alpha"], {}, ".standard_atomic_weight", InvalidElementError),
+    (["Fe-56"], {}, ".standard_atomic_weight", InvalidElementError),
+    (["e-"], {}, ".standard_atomic_weight", InvalidElementError),
+    (["tau-"], {}, ".element_name", InvalidElementError),
+    (["tau+"], {}, ".atomic_number", InvalidElementError),
+    (["neutron"], {}, ".atomic_number", InvalidElementError),
+    (["H"], {"Z": 0}, ".mass_number", InvalidIsotopeError),
+    (["neutron"], {}, ".mass_number", InvalidIsotopeError),
+    (["He"], {"mass_numb": 4}, ".charge", ChargeError),
+    (["He"], {"mass_numb": 4}, ".charge_number", ChargeError),
+    (["Fe"], {}, ".spin", MissingParticleDataError),
+    (["nu_e"], {}, ".mass", MissingParticleDataError),
+    (["Og"], {}, ".standard_atomic_weight", MissingParticleDataError),
+    ([Particle("C-14")], {"mass_numb": 13}, "", InvalidParticleError),
+    ([Particle("Au 1+")], {"Z": 2}, "", InvalidParticleError),
+    ([[]], {}, "", TypeError),
+    (["Fe"], {}, ".ionize()", ChargeError),
+    (["D"], {}, ".recombine()", ChargeError),
+    (["Fe 26+"], {}, ".ionize()", InvalidIonError),
+    (["Fe 6+"], {}, ".ionize(-1)", ValueError),
+    (["Fe 25+"], {}, ".recombine(0)", ValueError),
+    (["Fe 6+"], {}, ".ionize(4.6)", TypeError),
+    (["Fe 25+"], {}, ".recombine(8.2)", TypeError),
+    (["e-"], {}, ".ionize()", InvalidElementError),
+    (["e+"], {}, ".recombine()", InvalidElementError),
+    (["H", 1], {}, "", TypeError),
+    (["H", 1, 1], {}, "", TypeError),
 ]
 
 
-@pytest.mark.parametrize("arg, kwargs, attribute, exception", test_Particle_error_table)
-def test_Particle_errors(arg, kwargs, attribute, exception):
+@pytest.mark.parametrize(
+    "args, kwargs, attribute, exception", test_Particle_error_table
+)
+def test_Particle_errors(args, kwargs, attribute, exception):
     """
     Test that the appropriate exceptions are raised during the creation
     and use of a `~plasmapy.particles.Particle` object.
     """
     with pytest.raises(exception):
-        exec(f"Particle(arg, **kwargs){attribute}")
+        exec(f"Particle(*args, **kwargs){attribute}")
         pytest.fail(
             f"The following command: "
-            f"\n\n  {call_string(Particle, arg, kwargs)}{attribute}\n\n"
+            f"\n\n  {call_string(Particle, args, kwargs)}{attribute}\n\n"
             f"did not raise a {exception.__name__} as expected"
         )
 

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	+The parameters ``Z`` and ``mass_numb`` to \|Particle\| are now
	`2`	+:term:`keyword-only`.