Documentation and docstring updates

Author: Sylvain MARIE

docs/api_reference.md

@@ -247,10 +247,29 @@ Lists all desired cases for a given user query. This function may be convenient
 
 `pytest_fixture_plus(scope="function", autouse=False, name=None, **kwargs)`
 
-Identical to `@pytest.fixture` decorator, except that it supports multi-parametrization with `@pytest.mark.parametrize` as requested in [pytest#3960](https://github.com/pytest-dev/pytest/issues/3960).
+Identical to `@pytest.fixture` decorator, except that 
+
+ - it supports multi-parametrization with `@pytest.mark.parametrize` as requested in [pytest#3960](https://github.com/pytest-dev/pytest/issues/3960). As a consequence it does not support the `params` and `ids` arguments anymore.
+ 
+ - it supports a new argument `unpack_into` where you can provide names for fixtures where to unpack this fixture into.
 
 As a consequence it does not support the `params` and `ids` arguments anymore.
 
+### `unpack_fixture`
+
+`unpack_fixture(argnames, fixture) -> Tuple[<Fixture>]`
+
+Creates several fixtures with names `argnames` from the source `fixture`. Created fixtures will correspond to elements unpacked from `fixture` in order. For example if `fixture` is a tuple of length 2, `argnames="a,b"` will create two fixtures containing the first and second element respectively.
+
+The created fixtures are automatically registered into the callers' module, but you may wish to assign them to variables for convenience. In that case make sure that you use the same names, e.g. `a, b = unpack_fixture('a,b', 'c')`.
+
+**Parameters**
+
+ - **argnames**: same as `@pytest.mark.parametrize` `argnames`.
+ - **fixture**: a fixture name string or a fixture symbol. If a fixture symbol is provided, the created fixtures will have the same scope. If a name is provided, they will have scope='function'. Note that in practice the performance loss resulting from using `function` rather than a higher scope is negligible since the created fixtures' body is a one-liner.
+
+**Outputs:** the created fixtures.
+
 ### `fixture_union`
 
 `fixture_union(name, fixtures, scope="function", idstyle='explicit',
@@ -279,7 +298,7 @@ The style of test ids corresponding to the union alternatives can be changed wit
 
 ### `param_fixtures`
 
-`param_fixtures(argnames, argvalues, autouse=False, ids=None, scope="function", **kwargs)`
+`param_fixtures(argnames, argvalues, autouse=False, ids=None, scope="function", **kwargs) -> Tuple[<Fixture>]`
 
 Creates one or several "parameters" fixtures - depending on the number or coma-separated names in `argnames`. The created fixtures are automatically registered into the callers' module, but you may wish to assign them to variables for convenience. In that case make sure that you use the same names, e.g. `p, q = param_fixtures('p,q', [(0, 1), (2, 3)])`.
 
@@ -289,7 +308,7 @@ Note that the `(argnames, argvalues, ids)` signature is similar to `@pytest.mark
 
 ### `param_fixture`
 
-`param_fixture(argname, argvalues, autouse=False, ids=None, scope="function", **kwargs)`
+`param_fixture(argname, argvalues, autouse=False, ids=None, scope="function", **kwargs) -> <Fixture>`
 
 Identical to `param_fixtures` but for a single parameter name, so that you can assign its output to a single variable.
 

docs/index.md

@@ -217,6 +217,40 @@ This new commandline is a goodie to change the reordering:
 !!! note "`@pytest_fixture_plus` deprecation if/when `@pytest.fixture` supports `@pytest.mark.parametrize`"
     The ability for pytest fixtures to support the `@pytest.mark.parametrize` annotation is a feature that clearly belongs to `pytest` scope, and has been [requested already](https://github.com/pytest-dev/pytest/issues/3960). It is therefore expected that `@pytest_fixture_plus` will be deprecated in favor of `@pytest_fixture` if/when the `pytest` team decides to add the proposed feature. As always, deprecation will happen slowly across versions (at least two minor, or one major version update) so as for users to have the time to update their code bases.
 
+### `unpack_fixture` / `unpack_into`
+
+In some cases fixtures return a tuple or a list of items. It is not easy to refer to a single of these items in a test or another fixture. With `unpack_fixture` you can easily do it:
+
+```python
+import pytest
+from pytest_cases import unpack_fixture, pytest_fixture_plus
+
+@pytest_fixture_plus
+@pytest.mark.parametrize("o", ['hello', 'world'])
+def c(o):
+    return o, o[0]
+
+a, b = unpack_fixture("a,b", c)
+
+def test_function(a, b):
+    assert a[0] == b
+```
+
+Note that you can also use the `unpack_into=` argument of `@pytest_fixture_plus` to do the same thing:
+
+```python
+import pytest
+from pytest_cases import pytest_fixture_plus
+
+@pytest_fixture_plus(unpack_into="a,b")
+@pytest.mark.parametrize("o", ['hello', 'world'])
+def c(o):
+    return o, o[0]
+
+def test_function(a, b):
+    assert a[0] == b
+```
+
 ### `param_fixture[s]`
 
 If you wish to share some parameters across several fixtures and tests, it might be convenient to have a fixture representing this parameter. This is relatively easy for single parameters, but a bit harder for parameter tuples.

pytest_cases/main_fixtures.py

@@ -136,13 +136,28 @@ def param_fixture(argname, argvalues, autouse=False, ids=None, scope="function",
     Identical to `param_fixtures` but for a single parameter name, so that you can assign its output to a single
     variable.
 
+    ```python
+    import pytest
+    from pytest_cases import param_fixtures, param_fixture
+
+    # create a single parameter fixture
+    my_parameter = param_fixture("my_parameter", [1, 2, 3, 4])
+
+    @pytest.fixture
+    def fixture_uses_param(my_parameter):
+        ...
+
+    def test_uses_param(my_parameter, fixture_uses_param):
+        ...
+    ```
+
     :param argname: see fixture `name`
     :param argvalues: see fixture `params`
     :param autouse: see fixture `autouse`
     :param ids: see fixture `ids`
     :param scope: see fixture `scope`
     :param kwargs: any other argument for 'fixture'
-    :return:
+    :return: the create fixture
     """
     if "," in argname:
         raise ValueError("`param_fixture` is an alias for `param_fixtures` that can only be used for a single "
@@ -246,13 +261,28 @@ def param_fixtures(argnames, argvalues, autouse=False, ids=None, scope="function
     Note that the (argnames, argvalues, ids) signature is similar to `@pytest.mark.parametrize` for consistency,
     see https://docs.pytest.org/en/latest/reference.html?highlight=pytest.param#pytest-mark-parametrize
 
+    ```python
+    import pytest
+    from pytest_cases import param_fixtures, param_fixture
+
+    # create a 2-tuple parameter fixture
+    arg1, arg2 = param_fixtures("arg1, arg2", [(1, 2), (3, 4)])
+
+    @pytest.fixture
+    def fixture_uses_param2(arg2):
+        ...
+
+    def test_uses_param2(arg1, arg2, fixture_uses_param2):
+        ...
+    ```
+
     :param argnames: same as `@pytest.mark.parametrize` `argnames`.
     :param argvalues: same as `@pytest.mark.parametrize` `argvalues`.
     :param autouse: see fixture `autouse`
     :param ids: same as `@pytest.mark.parametrize` `ids`
     :param scope: see fixture `scope`
     :param kwargs: any other argument for the created 'fixtures'
-    :return:
+    :return: the created fixtures
     """
     created_fixtures = []
     argnames_lst = get_param_argnames_as_list(argnames)
@@ -281,7 +311,7 @@ def _root_fixture(**kwargs):
     # finally create the sub-fixtures
     for param_idx, argname in enumerate(argnames_lst):
         # create the fixture
-        # To fix late binding issue with `param_idx` we add an extra layer of scope
+        # To fix late binding issue with `param_idx` we add an extra layer of scope: a factory function
         # See https://stackoverflow.com/questions/3431676/creating-functions-in-a-loop
         def _create_fixture(param_idx):
             @pytest_fixture_plus(name=argname, scope=scope, autouse=autouse, **kwargs)