Repository: PlasmaPy/PlasmaPy

Issue:
Address functions in `distributions.py` with unexpected possible `return None`
While working on #2213, I noticed that there were a few functions in `distributions.py` which had an implicit `return None` that should not be possible.  We should update these functions so that an exception is raised instead of `None` being returned.

We'll need to check #2213 to see all of the functions.  (If I have time and the wherewithal, I'll make this update later.)

Discussion:

Patch:
diff --git a/changelog/2229.trivial.rst b/changelog/2229.trivial.rst
new file mode 100644
index 00000000..e0419e35
--- /dev/null
+++ b/changelog/2229.trivial.rst
@@ -0,0 +1,1 @@
+Distributions defined in the `~plasmapy.formulary.distribution` module will now raise a ``ValueError`` for an improper ``units`` parameter.
diff --git a/plasmapy/formulary/distribution.py b/plasmapy/formulary/distribution.py
index 7fc2813a..45249bb1 100644
--- a/plasmapy/formulary/distribution.py
+++ b/plasmapy/formulary/distribution.py
@@ -158,7 +158,8 @@ def Maxwellian_1D(
         return distFunc << SPEED_DISTRIBUTION_UNITS_1D
     elif units == "unitless":
         return distFunc
-    return None
+    else:
+        raise ValueError(f"Units must be either 'units' or 'unitless', got {units}).")
 
 
 @particle_input
@@ -305,7 +306,8 @@ def Maxwellian_velocity_2D(
         return distFunc << SPEED_DISTRIBUTION_UNITS_2D
     elif units == "unitless":
         return distFunc
-    return None
+    else:
+        raise ValueError(f"Units must be either 'units' or 'unitless', got {units}).")
 
 
 @particle_input
@@ -463,7 +465,8 @@ def Maxwellian_velocity_3D(
         return distFunc << SPEED_DISTRIBUTION_UNITS_3D
     elif units == "unitless":
         return distFunc
-    return None
+    else:
+        raise ValueError(f"Units must be either 'units' or 'unitless', got {units}).")
 
 
 @particle_input
@@ -589,7 +592,8 @@ def Maxwellian_speed_1D(
         return distFunc << SPEED_DISTRIBUTION_UNITS_1D
     elif units == "unitless":
         return distFunc
-    return None
+    else:
+        raise ValueError(f"Units must be either 'units' or 'unitless', got {units}).")
 
 
 @particle_input
@@ -723,7 +727,8 @@ def Maxwellian_speed_2D(
         return distFunc << SPEED_DISTRIBUTION_UNITS_1D
     elif units == "unitless":
         return distFunc
-    return None
+    else:
+        raise ValueError(f"Units must be either 'units' or 'unitless', got {units}).")
 
 
 @particle_input
@@ -856,7 +861,8 @@ def Maxwellian_speed_3D(
         return distFunc << SPEED_DISTRIBUTION_UNITS_1D
     elif units == "unitless":
         return distFunc
-    return None
+    else:
+        raise ValueError(f"Units must be either 'units' or 'unitless', got {units}).")
 
 
 @particle_input
@@ -1010,7 +1016,8 @@ def kappa_velocity_1D(
         return distFunc << SPEED_DISTRIBUTION_UNITS_1D
     elif units == "unitless":
         return distFunc
-    return None
+    else:
+        raise ValueError(f"Units must be either 'units' or 'unitless', got {units}).")
 
 
 @particle_input
@@ -1184,4 +1191,5 @@ def kappa_velocity_3D(
         return distFunc << SPEED_DISTRIBUTION_UNITS_3D
     elif units == "unitless":
         return distFunc
-    return None
+    else:
+        raise ValueError(f"Units must be either 'units' or 'unitless', got {units}).")


Test patch:
diff --git a/plasmapy/formulary/tests/test_distribution.py b/plasmapy/formulary/tests/test_distribution.py
index a91dbd56..c9bb4132 100644
--- a/plasmapy/formulary/tests/test_distribution.py
+++ b/plasmapy/formulary/tests/test_distribution.py
@@ -194,6 +194,19 @@ def test_value_drift_units(self):
         errStr = f"Distribution function should be {testVal} and not {distFunc}."
         assert np.isclose(distFunc.value, testVal, rtol=1e-5, atol=0.0), errStr
 
+    def test_no_units(self):
+        """
+        Test resulting error from using incorrect units parameter
+        """
+        with pytest.raises(ValueError):
+            Maxwellian_1D(
+                v=self.v.value,
+                T=self.T_e.value,
+                particle=self.particle,
+                v_drift=self.v_drift3.value,
+                units="Lorem ipsum",
+            )
+
 
 class Test_Maxwellian_speed_1D:
     @classmethod
@@ -323,6 +336,19 @@ def test_value_drift_units(self):
             distFunc.value, self.distFuncDrift.value, rtol=1e-5, atol=0.0
         ), errStr
 
+    def test_no_units(self):
+        """
+        Test resulting error from using incorrect units parameter
+        """
+        with pytest.raises(ValueError):
+            Maxwellian_speed_1D(
+                v=self.v.value,
+                T=self.T.value,
+                particle=self.particle,
+                v_drift=self.v_drift2.value,
+                units="Lorem ipsum",
+            )
+
 
 class Test_Maxwellian_velocity_2D:
     @classmethod
@@ -480,6 +506,21 @@ def test_value_drift_units(self):
         errStr = f"Distribution function should be {testVal} and not {distFunc}."
         assert np.isclose(distFunc.value, testVal, rtol=1e-5, atol=0.0), errStr
 
+    def test_no_units(self):
+        """
+        Test resulting error from using incorrect units parameter
+        """
+        with pytest.raises(ValueError):
+            Maxwellian_velocity_2D(
+                vx=self.vx.value,
+                vy=self.vy.value,
+                T=self.T.value,
+                particle=self.particle,
+                vx_drift=self.vx_drift.value,
+                vy_drift=self.vy_drift.value,
+                units="Lorem ipsum",
+            )
+
 
 @pytest.mark.slow()
 class Test_Maxwellian_speed_2D:
@@ -606,6 +647,19 @@ def test_value_drift_units(self):
                 units="units",
             )
 
+    def test_no_units(self):
+        """
+        Test resulting error from using incorrect units parameter
+        """
+        with pytest.raises(ValueError):
+            Maxwellian_speed_2D(
+                v=self.v.value,
+                T=self.T.value,
+                particle=self.particle,
+                v_drift=self.v_drift.value,
+                units="Lorem ipsum",
+            )
+
 
 @pytest.mark.slow()
 class Test_Maxwellian_velocity_3D:
@@ -781,6 +835,23 @@ def test_value_drift_units(self):
         errStr = f"Distribution function should be {testVal} and not {distFunc}."
         assert np.isclose(distFunc.value, testVal, rtol=1e-5, atol=0.0), errStr
 
+    def test_no_units(self):
+        """
+        Test resulting error from using incorrect units parameter
+        """
+        with pytest.raises(ValueError):
+            Maxwellian_velocity_3D(
+                vx=self.vx.value,
+                vy=self.vy.value,
+                vz=self.vz.value,
+                T=self.T.value,
+                particle=self.particle,
+                vx_drift=self.vx_drift2.value,
+                vy_drift=self.vy_drift2.value,
+                vz_drift=self.vz_drift2.value,
+                units="Lorem ipsum",
+            )
+
 
 class Test_Maxwellian_speed_3D:
     @classmethod
@@ -906,6 +977,19 @@ def test_value_drift_units(self):
                 units="units",
             )
 
+    def test_no_units(self):
+        """
+        Test resulting error from using incorrect units parameter
+        """
+        with pytest.raises(ValueError):
+            Maxwellian_speed_3D(
+                v=self.v.value,
+                T=self.T.value,
+                particle=self.particle,
+                v_drift=self.v_drift.value,
+                units="Lorem ipsum",
+            )
+
 
 class Test_kappa_velocity_1D:
     @classmethod
@@ -1126,6 +1210,20 @@ def test_value_drift_units(self):
         errStr = f"Distribution function should be {testVal} and not {distFunc}."
         assert np.isclose(distFunc.value, testVal, rtol=1e-5, atol=0.0), errStr
 
+    def test_no_units(self):
+        """
+        Test resulting error from using incorrect units parameter
+        """
+        with pytest.raises(ValueError):
+            kappa_velocity_1D(
+                v=self.v.value,
+                T=self.T_e.value,
+                kappa=self.kappa,
+                particle=self.particle,
+                v_drift=self.v_drift3.value,
+                units="Lorem ipsum",
+            )
+
 
 @pytest.mark.slow()
 class Test_kappa_velocity_3D:
@@ -1359,3 +1457,21 @@ def test_value_drift_units(self):
         )
         errStr = f"Distribution function should be {testVal} and not {distFunc}."
         assert np.isclose(distFunc.value, testVal, rtol=1e-5, atol=0.0), errStr
+
+    def test_no_units(self):
+        """
+        Test resulting error from using incorrect units parameter
+        """
+        with pytest.raises(ValueError):
+            kappa_velocity_3D(
+                vx=self.vx.value,
+                vy=self.vy.value,
+                vz=self.vz.value,
+                T=self.T.value,
+                kappa=self.kappa,
+                particle=self.particle,
+                vx_drift=self.vx_drift2.value,
+                vy_drift=self.vy_drift2.value,
+                vz_drift=self.vz_drift2.value,
+                units="Lorem ipsum",
+            )