unittest-parametrize 1.5.0__tar.gz → 1.7.0__tar.gz

{unittest_parametrize-1.5.0 → unittest_parametrize-1.7.0}/CHANGELOG.rst

@@ -2,6 +2,29 @@
 Changelog
 =========
 
+1.7.0 (2025-08-27)
+------------------
+
+* Add support for the ``ids`` argument being a callable.
+  The callable is called once per parameter value and can return a string for that value or ``None`` to use the default.
+
+  `PR #143 <https://github.com/adamchainz/unittest-parametrize/pull/143>`__.
+
+* Fail for collisions between autogenerated IDs and user-specified IDs when mixing tuples and ``param`` instances.
+
+  `PR #143 <https://github.com/adamchainz/unittest-parametrize/pull/143>`__.
+
+* Update the type hints to allow mixing tuples and ``param`` instances.
+
+  `PR #143 <https://github.com/adamchainz/unittest-parametrize/pull/143>`__.
+
+1.6.0 (2025-01-06)
+------------------
+
+* Add support for asynchronous tests.
+
+  Thanks to Adrien Cossa in `PR #121 <https://github.com/adamchainz/unittest-parametrize/pull/121>`__.
+
 1.5.0 (2024-10-08)
 ------------------
 

{unittest_parametrize-1.5.0/src/unittest_parametrize.egg-info → unittest_parametrize-1.7.0}/PKG-INFO

@@ -1,15 +1,15 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: unittest-parametrize
-Version: 1.5.0
+Version: 1.7.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
@@ -22,6 +22,7 @@ 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
@@ -73,7 +74,7 @@ __ https://docs.pytest.org/en/stable/how-to/parametrize.html#parametrize-basics
 There are two steps to parametrize a test case:
 
 1. Use ``ParametrizedTestCase`` in the base classes for your test case.
-2. Apply ``@parametrize`` to any tests for parametrization.
+2. Apply ``@parametrize`` to any test methods for parametrization.
    This decorator takes (at least):
 
    * the argument names to parametrize, as comma-separated string
@@ -83,8 +84,7 @@ 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):
@@ -101,6 +101,7 @@ Here’s a basic example:
 ``@parametrize`` modifies the class at definition time with Python’s |__init_subclass__ hook|__.
 It removes the original test method and creates wrapped copies with individual names.
 Thus the parametrization should work regardless of the test runner you use (be it unittest, Django’s test runner, pytest, etc.).
+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__
@@ -112,8 +113,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):
@@ -176,13 +176,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):
@@ -196,7 +203,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
 
@@ -215,9 +222,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):
@@ -231,7 +236,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
 
@@ -244,12 +249,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):
@@ -264,6 +271,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
 ------------------------------
 
@@ -274,8 +339,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):
@@ -284,8 +348,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:
@@ -293,8 +356,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
 ------------------------------------
@@ -304,8 +366,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):
@@ -317,8 +378,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``.
 
@@ -330,8 +390,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):
@@ -345,8 +404,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``.
 
@@ -370,15 +428,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.5.0 → unittest_parametrize-1.7.0}/README.rst

@@ -48,7 +48,7 @@ __ https://docs.pytest.org/en/stable/how-to/parametrize.html#parametrize-basics
 There are two steps to parametrize a test case:
 
 1. Use ``ParametrizedTestCase`` in the base classes for your test case.
-2. Apply ``@parametrize`` to any tests for parametrization.
+2. Apply ``@parametrize`` to any test methods for parametrization.
    This decorator takes (at least):
 
    * the argument names to parametrize, as comma-separated string
@@ -58,8 +58,7 @@ 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):
@@ -76,6 +75,7 @@ Here’s a basic example:
 ``@parametrize`` modifies the class at definition time with Python’s |__init_subclass__ hook|__.
 It removes the original test method and creates wrapped copies with individual names.
 Thus the parametrization should work regardless of the test runner you use (be it unittest, Django’s test runner, pytest, etc.).
+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__
@@ -87,8 +87,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):
@@ -151,13 +150,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):
@@ -171,7 +177,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
 
@@ -190,9 +196,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):
@@ -206,7 +210,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
 
@@ -219,12 +223,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):
@@ -239,6 +245,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
 ------------------------------
 
@@ -249,8 +313,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):
@@ -259,8 +322,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:
@@ -268,8 +330,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
 ------------------------------------
@@ -279,8 +340,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):
@@ -292,8 +352,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``.
 
@@ -305,8 +364,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):
@@ -320,8 +378,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``.
 
@@ -345,15 +402,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.5.0 → unittest_parametrize-1.7.0}/pyproject.toml

@@ -1,17 +1,19 @@
 [build-system]
 build-backend = "setuptools.build_meta"
 requires = [
-  "setuptools",
+  "setuptools>=77",
 ]
 
 [project]
 name = "unittest-parametrize"
-version = "1.5.0"
+version = "1.7.0"
 description = "Parametrize tests within unittest TestCases."
 readme = "README.rst"
 keywords = [
   "unittest",
 ]
+license = "MIT"
+license-files = [ "LICENSE" ]
 authors = [
   { name = "Adam Johnson", email = "me@adamj.eu" },
 ]
@@ -19,7 +21,6 @@ requires-python = ">=3.9"
 classifiers = [
   "Development Status :: 5 - Production/Stable",
   "Intended Audience :: Developers",
-  "License :: OSI Approved :: MIT License",
   "Natural Language :: English",
   "Programming Language :: Python :: 3 :: Only",
   "Programming Language :: Python :: 3.9",
@@ -36,12 +37,50 @@ urls.Changelog = "https://github.com/adamchainz/unittest-parametrize/blob/main/C
 urls.Funding = "https://adamj.eu/books/"
 urls.Repository = "https://github.com/adamchainz/unittest-parametrize"
 
-[tool.isort]
-add_imports = [
-  "from __future__ import annotations",
+[dependency-groups]
+test = [
+  "coverage[toml]",
+  "pytest",
+  "pytest-randomly",
+  "typing-extensions; python_version<'3.10'",
+]
+
+[tool.ruff]
+lint.select = [
+  # flake8-bugbear
+  "B",
+  # flake8-comprehensions
+  "C4",
+  # pycodestyle
+  "E",
+  # Pyflakes errors
+  "F",
+  # isort
+  "I",
+  # flake8-simplify
+  "SIM",
+  # flake8-tidy-imports
+  "TID",
+  # pyupgrade
+  "UP",
+  # Pyflakes warnings
+  "W",
+]
+lint.ignore = [
+  # flake8-bugbear opinionated rules
+  "B9",
+  # line-too-long
+  "E501",
+  # suppressible-exception
+  "SIM105",
+  # if-else-block-instead-of-if-exp
+  "SIM108",
+]
+lint.extend-safe-fixes = [
+  # non-pep585-annotation
+  "UP006",
 ]
-force_single_line = true
-profile = "black"
+lint.isort.required-imports = [ "from __future__ import annotations" ]
 
 [tool.pyproject-fmt]
 max_supported_python = "3.13"

{unittest_parametrize-1.5.0 → unittest_parametrize-1.7.0}/src/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):
@@ -40,23 +38,49 @@ class ParametrizedTestCase(TestCase):
             for param in _parametrized.params:
                 params = dict(zip(_parametrized.argnames, param.args))
 
-                @wraps(func)
-                def test(
-                    self: TestCase,
-                    *args: Any,
-                    _func: FunctionType = func,
-                    _params: dict[str, Any] = params,
-                    **kwargs: Any,
-                ) -> Any:
-                    try:
-                        return _func(self, *args, **_params, **kwargs)
-                    except Exception as exc:
-                        if sys.version_info >= (3, 11):
-                            exc.add_note(
-                                "Test parameters: "
-                                + ", ".join(f"{k}={v!r}" for k, v in _params.items())
-                            )
-                        raise
+                if inspect.iscoroutinefunction(func):
+
+                    @wraps(func)
+                    async def test(
+                        self: TestCase,
+                        *args: Any,
+                        _func: FunctionType = func,
+                        _params: dict[str, Any] = params,
+                        **kwargs: Any,
+                    ) -> Any:
+                        try:
+                            return await _func(self, *args, **_params, **kwargs)
+                        except Exception as exc:
+                            if sys.version_info >= (3, 11):
+                                exc.add_note(
+                                    "Test parameters: "
+                                    + ", ".join(
+                                        f"{k}={v!r}" for k, v in _params.items()
+                                    )
+                                )
+                            raise
+
+                else:
+
+                    @wraps(func)
+                    def test(
+                        self: TestCase,
+                        *args: Any,
+                        _func: FunctionType = func,
+                        _params: dict[str, Any] = params,
+                        **kwargs: Any,
+                    ) -> Any:
+                        try:
+                            return _func(self, *args, **_params, **kwargs)
+                        except Exception as exc:
+                            if sys.version_info >= (3, 11):
+                                exc.add_note(
+                                    "Test parameters: "
+                                    + ", ".join(
+                                        f"{k}={v!r}" for k, v in _params.items()
+                                    )
+                                )
+                            raise
 
                 test.__name__ = f"{name}_{param.id}"
                 test.__qualname__ = f"{test.__qualname__}_{param.id}"
@@ -96,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],
+    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(",")]
@@ -105,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(
@@ -131,7 +153,7 @@ 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)
@@ -157,3 +179,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.5.0 → unittest_parametrize-1.7.0/src/unittest_parametrize.egg-info}/PKG-INFO

@@ -1,15 +1,15 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: unittest-parametrize
-Version: 1.5.0
+Version: 1.7.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
@@ -22,6 +22,7 @@ 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
@@ -73,7 +74,7 @@ __ https://docs.pytest.org/en/stable/how-to/parametrize.html#parametrize-basics
 There are two steps to parametrize a test case:
 
 1. Use ``ParametrizedTestCase`` in the base classes for your test case.
-2. Apply ``@parametrize`` to any tests for parametrization.
+2. Apply ``@parametrize`` to any test methods for parametrization.
    This decorator takes (at least):
 
    * the argument names to parametrize, as comma-separated string
@@ -83,8 +84,7 @@ 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):
@@ -101,6 +101,7 @@ Here’s a basic example:
 ``@parametrize`` modifies the class at definition time with Python’s |__init_subclass__ hook|__.
 It removes the original test method and creates wrapped copies with individual names.
 Thus the parametrization should work regardless of the test runner you use (be it unittest, Django’s test runner, pytest, etc.).
+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__
@@ -112,8 +113,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):
@@ -176,13 +176,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):
@@ -196,7 +203,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
 
@@ -215,9 +222,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):
@@ -231,7 +236,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
 
@@ -244,12 +249,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):
@@ -264,6 +271,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
 ------------------------------
 
@@ -274,8 +339,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):
@@ -284,8 +348,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:
@@ -293,8 +356,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
 ------------------------------------
@@ -304,8 +366,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):
@@ -317,8 +378,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``.
 
@@ -330,8 +390,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):
@@ -345,8 +404,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``.
 
@@ -370,15 +428,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
 =======