unittest-parametrize 1.6.0__py3-none-any.whl → 1.8.0__py3-none-any.whl

unittest_parametrize/__init__.py

@@ -5,9 +5,7 @@ import sys
 from collections.abc import Sequence
 from functools import wraps
 from types import FunctionType
-from typing import Any
-from typing import Callable
-from typing import TypeVar
+from typing import Any, Callable, TypeVar
 from unittest import TestCase
 
 if sys.version_info >= (3, 10):
@@ -122,8 +120,8 @@ TestFunc = Callable[P, T]
 
 def parametrize(
     argnames: str | Sequence[str],
-    argvalues: Sequence[tuple[Any, ...]] | Sequence[param],
-    ids: Sequence[str | None] | None = None,
+    argvalues: Sequence[tuple[Any, ...] | param | Any],
+    ids: Sequence[str | None] | Callable[[Any], str | None] | None = None,
 ) -> Callable[[Callable[P, T]], Callable[P, T]]:
     if isinstance(argnames, str):
         argnames = [a.strip() for a in argnames.split(",")]
@@ -131,24 +129,22 @@ def parametrize(
     if len(argnames) == 0:
         raise ValueError("argnames must contain at least one element")
 
-    if ids is not None and len(ids) != len(argvalues):
+    ids_callable = callable(ids)
+    if ids is not None and not ids_callable and len(ids) != len(argvalues):  # type: ignore[arg-type]
         raise ValueError("ids must have the same length as argvalues")
 
     seen_ids = set()
     params = []
     for i, argvalue in enumerate(argvalues):
-        if ids and ids[i]:
-            id_ = ids[i]
-        else:
-            id_ = str(i)
-
         if isinstance(argvalue, tuple):
             if len(argvalue) != len(argnames):
                 raise ValueError(
                     f"tuple at index {i} has wrong number of arguments "
                     + f"({len(argvalue)} != {len(argnames)})"
                 )
-            params.append(param(*argvalue, id=id_))
+            argvalue = param(*argvalue, id=make_id(i, argvalue, ids))
+            params.append(argvalue)
+            seen_ids.add(argvalue.id)
         elif isinstance(argvalue, param):
             if len(argvalue.args) != len(argnames):
                 raise ValueError(
@@ -157,15 +153,18 @@ def parametrize(
                 )
 
             if argvalue.id is None:
-                argvalue = param(*argvalue.args, id=id_)
+                argvalue = param(*argvalue.args, id=make_id(i, argvalue, ids))
             if argvalue.id in seen_ids:
                 raise ValueError(f"Duplicate param id {argvalue.id!r}")
             seen_ids.add(argvalue.id)
             params.append(argvalue)
-
+        elif len(argnames) == 1:
+            argvalue = param(argvalue, id=make_id(i, (argvalue,), ids))
+            seen_ids.add(argvalue.id)
+            params.append(argvalue)
         else:
             raise TypeError(
-                f"argvalue at index {i} is not a tuple or param instance: {argvalue!r}"
+                f"argvalue at index {i} is not a tuple, param instance, or single value: {argvalue!r}"
             )
 
     _parametrized = parametrized(argnames, params)
@@ -183,3 +182,34 @@ def parametrize(
         return func
 
     return wrapper
+
+
+def make_id(
+    i: int,
+    argvalue: tuple[Any, ...] | param,
+    ids: Sequence[str | None] | Callable[[Any], str | None] | None,
+) -> str:
+    if callable(ids):
+        if isinstance(argvalue, tuple):
+            values = argvalue
+        else:
+            values = argvalue.args
+
+        id_parts = []
+        for value in values:
+            id_part = ids(value)
+            if id_part is not None:
+                id_parts.append(id_part)
+            else:
+                id_parts.append(str(value))
+        id_ = "_".join(id_parts)
+        # Validate the generated ID
+        if not f"_{id_}".isidentifier():
+            raise ValueError(
+                f"callable ids returned invalid Python identifier suffix: {id_!r}"
+            )
+        return id_
+    elif ids and ids[i]:
+        return str(ids[i])
+    else:
+        return str(i)

{unittest_parametrize-1.6.0.dist-info → unittest_parametrize-1.8.0.dist-info}/METADATA

@@ -1,15 +1,15 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: unittest-parametrize
-Version: 1.6.0
+Version: 1.8.0
 Summary: Parametrize tests within unittest TestCases.
 Author-email: Adam Johnson <me@adamj.eu>
+License-Expression: MIT
 Project-URL: Changelog, https://github.com/adamchainz/unittest-parametrize/blob/main/CHANGELOG.rst
 Project-URL: Funding, https://adamj.eu/books/
 Project-URL: Repository, https://github.com/adamchainz/unittest-parametrize
 Keywords: unittest
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Natural Language :: English
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.9
@@ -17,11 +17,13 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: >=3.9
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Requires-Dist: typing-extensions; python_version < "3.10"
+Dynamic: license-file
 
 ====================
 unittest-parametrize
@@ -58,7 +60,7 @@ Install with:
 
     python -m pip install unittest-parametrize
 
-Python 3.9 to 3.13 supported.
+Python 3.9 to 3.14 supported.
 
 Usage
 =====
@@ -76,15 +78,14 @@ There are two steps to parametrize a test case:
 2. Apply ``@parametrize`` to any test methods for parametrization.
    This decorator takes (at least):
 
-   * the argument names to parametrize, as comma-separated string
-   * a list of parameter tuples to create individual tests for
+   * the argument names to parametrize, as comma-separated string or sequence of strings.
+   * a list of parameters to create individual tests for, which may be tuples, ``param`` objects, or single values (for one argument).
 
 Here’s a basic example:
 
 .. code-block:: python
 
-    from unittest_parametrize import parametrize
-    from unittest_parametrize import ParametrizedTestCase
+    from unittest_parametrize import ParametrizedTestCase, parametrize
 
 
     class SquareTests(ParametrizedTestCase):
@@ -106,6 +107,25 @@ It supports both synchronous and asynchronous test methods.
 .. |__init_subclass__ hook| replace:: ``__init_subclass__`` hook
 __ https://docs.python.org/3/reference/datamodel.html#object.__init_subclass__
 
+Provide a single parameter without a wrapping tuple
+---------------------------------------------------
+
+If you only need a single parameter, you can provide values without wrapping them in tuples:
+
+.. code-block:: python
+
+    from unittest_parametrize import ParametrizedTestCase, parametrize
+
+
+    class EqualTests(ParametrizedTestCase):
+        @parametrize(
+            "x",
+            [1, 2, 3],
+        )
+        def test_equal(self, x: int) -> None:
+            self.assertEqual(x, x)
+
+
 Provide argument names as separate strings
 ------------------------------------------
 
@@ -113,8 +133,7 @@ You can provide argument names as a sequence of strings instead:
 
 .. code-block:: python
 
-    from unittest_parametrize import parametrize
-    from unittest_parametrize import ParametrizedTestCase
+    from unittest_parametrize import ParametrizedTestCase, parametrize
 
 
     class SquareTests(ParametrizedTestCase):
@@ -177,13 +196,20 @@ You can see these names when running the tests:
 
     OK
 
-You can customize these names by passing ``param`` objects, which contain the arguments and an optional ID for the suffix:
+You can customize these names in several ways:
+
+1. Using ``param`` objects with IDs.
+2. Passing a sequence of strings as the ``ids`` argument.
+3. Passing a callable as the ``ids`` argument.
+
+Passing ``param`` objects with IDs
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Pass a ``param`` object for each parameter set, setting the test ID suffix with the optional ``id`` argument:
 
 .. code-block:: python
 
-    from unittest_parametrize import param
-    from unittest_parametrize import parametrize
-    from unittest_parametrize import ParametrizedTestCase
+    from unittest_parametrize import ParametrizedTestCase, param, parametrize
 
 
     class SquareTests(ParametrizedTestCase):
@@ -197,7 +223,7 @@ You can customize these names by passing ``param`` objects, which contain the ar
         def test_square(self, x: int, expected: int) -> None:
             self.assertEqual(x**2, expected)
 
-Yielding perhaps more natural names:
+Yielding more natural names:
 
 .. code-block:: console
 
@@ -216,9 +242,7 @@ Since parameter IDs are optional, you can provide them only for some tests:
 
 .. code-block:: python
 
-    from unittest_parametrize import param
-    from unittest_parametrize import parametrize
-    from unittest_parametrize import ParametrizedTestCase
+    from unittest_parametrize import ParametrizedTestCase, param, parametrize
 
 
     class SquareTests(ParametrizedTestCase):
@@ -232,7 +256,7 @@ Since parameter IDs are optional, you can provide them only for some tests:
         def test_square(self, x: int, expected: int) -> None:
             self.assertEqual(x**2, expected)
 
-ID-free ``param``\s fall back to the default index suffixes:
+The ID-free ``param``\s fall back to the default index suffixes:
 
 .. code-block:: console
 
@@ -245,12 +269,14 @@ ID-free ``param``\s fall back to the default index suffixes:
 
     OK
 
-Alternatively, you can provide the id’s separately with the ``ids`` argument:
+Passing a sequence of strings as the ``ids`` argument
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Another option is to provide the IDs in the separate ``ids`` argument:
 
 .. code-block:: python
 
-    from unittest_parametrize import parametrize
-    from unittest_parametrize import ParametrizedTestCase
+    from unittest_parametrize import ParametrizedTestCase, parametrize
 
 
     class SquareTests(ParametrizedTestCase):
@@ -265,6 +291,64 @@ Alternatively, you can provide the id’s separately with the ``ids`` argument:
         def test_square(self, x: int, expected: int) -> None:
             self.assertEqual(x**2, expected)
 
+This option sets the full suffixes to the provided strings:
+
+.. code-block:: console
+
+    $ python -m unittest t.py -v
+    test_square_one (example.SquareTests.test_square_one) ... ok
+    test_square_two (example.SquareTests.test_square_two) ... ok
+
+    ----------------------------------------------------------------------
+    Ran 2 tests in 0.000s
+
+    OK
+
+Passing a callable as the ``ids`` argument
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``ids`` argument can also be a callable, which unittest-parametrize calls once per parameter value.
+The callable can return a string for that value, or ``None`` to use the default index suffix.
+The values are then joined with underscores to form the full suffix.
+
+For example:
+
+.. code-block:: python
+
+    from unittest_parametrize import ParametrizedTestCase, parametrize
+
+
+    def make_id(value):
+        if isinstance(value, int):
+            return f"num{value}"
+        return None
+
+
+    class SquareTests(ParametrizedTestCase):
+        @parametrize(
+            "x,expected",
+            [
+                (1, 1),
+                (2, 4),
+            ],
+            ids=make_id,
+        )
+        def test_square(self, x: int, expected: int) -> None:
+            self.assertEqual(x**2, expected)
+
+…yields:
+
+.. code-block:: console
+
+    $ python -m unittest t.py -v
+    test_square_num1_num1 (example.SquareTests.test_square_num1_num1) ... ok
+    test_square_num2_num4 (example.SquareTests.test_square_num2_num4) ... ok
+
+    ----------------------------------------------------------------------
+    Ran 2 tests in 0.000s
+
+    OK
+
 Use with other test decorators
 ------------------------------
 
@@ -275,8 +359,7 @@ So decorators like ``@mock.patch`` need be beneath ``@parametrize``:
 .. code-block:: python
 
     from unittest import mock
-    from unittest_parametrize import parametrize
-    from unittest_parametrize import ParametrizedTestCase
+    from unittest_parametrize import ParametrizedTestCase, parametrize
 
 
     class CarpentryTests(ParametrizedTestCase):
@@ -285,8 +368,7 @@ So decorators like ``@mock.patch`` need be beneath ``@parametrize``:
             [(11,), (17,)],
         )
         @mock.patch("example.hammer", autospec=True)
-        def test_nail_a_board(self, mock_hammer, nails):
-            ...
+        def test_nail_a_board(self, mock_hammer, nails): ...
 
 Also note that due to how ``mock.patch`` always adds positional arguments at the start, the parametrized arguments must come last.
 ``@parametrize`` always adds parameters as keyword arguments, so you can also use `keyword-only syntax <https://peps.python.org/pep-3102/>`__ for parametrized arguments:
@@ -294,8 +376,7 @@ Also note that due to how ``mock.patch`` always adds positional arguments at the
 .. code-block:: python
 
     # ...
-    def test_nail_a_board(self, mock_hammer, *, nails):
-        ...
+    def test_nail_a_board(self, mock_hammer, *, nails): ...
 
 Multiple ``@parametrize`` decorators
 ------------------------------------
@@ -305,8 +386,7 @@ To create a cross-product of tests, you can use nested list comprehensions:
 
 .. code-block:: python
 
-    from unittest_parametrize import parametrize
-    from unittest_parametrize import ParametrizedTestCase
+    from unittest_parametrize import ParametrizedTestCase, parametrize
 
 
     class RocketTests(ParametrizedTestCase):
@@ -318,8 +398,7 @@ To create a cross-product of tests, you can use nested list comprehensions:
                 for hyperdrive_level in [0, 1, 2]
             ],
         )
-        def test_takeoff(self, use_ions, hyperdrive_level) -> None:
-            ...
+        def test_takeoff(self, use_ions, hyperdrive_level) -> None: ...
 
 The above creates 2 * 3 = 6 versions of ``test_takeoff``.
 
@@ -331,8 +410,7 @@ __ https://docs.python.org/3/library/itertools.html#itertools.product
 .. code-block:: python
 
     from itertools import product
-    from unittest_parametrize import parametrize
-    from unittest_parametrize import ParametrizedTestCase
+    from unittest_parametrize import ParametrizedTestCase, parametrize
 
 
     class RocketTests(ParametrizedTestCase):
@@ -346,8 +424,7 @@ __ https://docs.python.org/3/library/itertools.html#itertools.product
                 )
             ),
         )
-        def test_takeoff(self, use_ions, hyperdrive_level, nose_colour) -> None:
-            ...
+        def test_takeoff(self, use_ions, hyperdrive_level, nose_colour) -> None: ...
 
 The above creates 2 * 3 * 2 = 12 versions of ``test_takeoff``.
 
@@ -371,15 +448,47 @@ To parametrize all tests within a test case, create a separate decorator and app
 
     class StatsTests(ParametrizedTestCase):
         @parametrize_race
-        def test_strength(self, race: str) -> None:
-            ...
+        def test_strength(self, race: str) -> None: ...
 
         @parametrize_race
-        def test_dexterity(self, race: str) -> None:
-            ...
+        def test_dexterity(self, race: str) -> None: ...
 
         ...
 
+Pass parameters in a dataclass
+------------------------------
+
+Thanks to `Florian Bruhin <https://bruhin.software/>`__ for this tip, from his `pytest tips and tricks presentation <https://bruhin.software/>`__.
+
+If your test uses many parameters or cases, the parametrization may become unwieldy, as cases don’t name the arguments.
+In this case, try using a `dataclass <https://docs.python.org/3/library/dataclasses.html>`__ to hold the arguments:
+
+.. code-block:: python
+
+    from dataclasses import dataclass
+
+    from unittest_parametrize import ParametrizedTestCase, parametrize
+
+
+    @dataclass
+    class SquareParams:
+        x: int
+        expected: int
+
+
+    class SquareTests(ParametrizedTestCase):
+        @parametrize(
+            "sp",
+            [
+                (SquareParams(x=1, expected=1),),
+                (SquareParams(x=2, expected=4),),
+            ],
+        )
+        def test_square(self, sp: SquareParams) -> None:
+            self.assertEqual(sp.x**2, sp.expected)
+
+This way, each parameter is type-checked and named, improving safety and readability.
+
 History
 =======
 

unittest_parametrize-1.8.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+unittest_parametrize/__init__.py,sha256=FP9gc8jyJOHJVe9s52mbMEEsZpyw5vuD3tZxEuLclhg,7433
+unittest_parametrize/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+unittest_parametrize-1.8.0.dist-info/licenses/LICENSE,sha256=Jn179RflkRZXhSCGt_D7asLy2Ex47C0WdBHxe0lBazk,1069
+unittest_parametrize-1.8.0.dist-info/METADATA,sha256=6I1nJVKypKpSdAlx9npkXSVIVN2Y1CM8j4rjey5r_So,18449
+unittest_parametrize-1.8.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+unittest_parametrize-1.8.0.dist-info/top_level.txt,sha256=4nLqNaGtBX8Ny36ZdFt37Gk-87hPtOvfdfZlTBi3OtU,21
+unittest_parametrize-1.8.0.dist-info/RECORD,,

{unittest_parametrize-1.6.0.dist-info → unittest_parametrize-1.8.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (75.7.0)
+Generator: setuptools (80.9.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

unittest_parametrize-1.6.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-unittest_parametrize/__init__.py,sha256=-WNbay-GoS2_ENp9cOgE3pf_BJH2Nr1eX7wiAwJyxic,6299
-unittest_parametrize/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-unittest_parametrize-1.6.0.dist-info/LICENSE,sha256=Jn179RflkRZXhSCGt_D7asLy2Ex47C0WdBHxe0lBazk,1069
-unittest_parametrize-1.6.0.dist-info/METADATA,sha256=kZJe0NHStrHyHJgkttwwmGgBOagnfB4XfffeK_SspUI,15223
-unittest_parametrize-1.6.0.dist-info/WHEEL,sha256=A3WOREP4zgxI0fKrHUG8DC8013e3dK3n7a6HDbcEIwE,91
-unittest_parametrize-1.6.0.dist-info/top_level.txt,sha256=4nLqNaGtBX8Ny36ZdFt37Gk-87hPtOvfdfZlTBi3OtU,21
-unittest_parametrize-1.6.0.dist-info/RECORD,,