Fixed documentation for the new fixture

Author: Sylvain MARIE

docs/api_reference.md

@@ -2,7 +2,20 @@
 
 In general, using `help(symbol)` is the recommended way to get the latest documentation. In addition, this page provides an overview of the various elements in this package.
 
-## 1 - Case functions
+## 1 - Fixtures
+
+### `current_cases`
+
+A fixture containing [`get_current_cases(request)`](#get_current_cases).
+
+This is a dictionary containing all case parameters for the currently active `pytest` item. For each test function argument parametrized using a [`@parametrize_with_case(<argname>, ...)`](#parametrize_with_cases) this dictionary contains an entry `{<argname>: (actual_id, case_function)}`. If several argnames are parametrized this way, a dedicated entry will be present for each argname.
+
+If a fixture parametrized with cases is active, the dictionary will contain an entry `{<fixturename>: <dct>}` where `<dct>` is a dictionary `{<argname>: (actual_id, case_function)}`.
+
+To get more information on a case function, you can use [`get_case_id(f)`](#get_case_id), [`get_case_marks(f)`](#get_case_marks), [`get_case_tags(f)`](#get_case_tags). You can also use [`matches_tag_query`](#matches_tag_query) to check if a case function matches some expectations either concerning its id
+or its tags. See [filters and tags documentation](https://smarie.github.io/python-pytest-cases/#filters-and-tags).
+
+## 2 - Case functions
 
 As explained in the [documentation](index.md), case functions have no requirement anymore, and starting from version 2.0.0 of `pytest_cases` they can be parametrized with the usual `@pytest.mark.parametrize` or its improvement [`@parametrize`](#parametrize). Therefore the only remaining decorator is the optional `@case` decorator:
 
@@ -233,7 +246,7 @@ CaseFilter(filter_function: Callable)
 
 `CaseFilter` is the class used by all filters above, and implementing logical operations "and" (`&`) "or" (`|`) and "not" (`~`). You can use it to define a composable filter from any callable receiving a single `case` argument and returning a boolean indicating if the `case` is selected.
 
-## 2 - Cases collection
+## 3 - Cases collection
 
 ### `@parametrize_with_cases`
 
@@ -282,27 +295,30 @@ argvalues = get_parametrize_args(host_class_or_module_of_f, cases_funs)
 
  - `filter`: a callable receiving the case function and returning `True` or a truth value in case the function needs to be selected.
 
- - `ids`: optional custom ids, similar to the one in `pytest.mark.parametrize`. Users may either provide an iterable of string ids, or a callable. If a callable is provided it will receive the case functions. Users may wish to use [`get_case_id`](#get_case_id) or other helpers in the [API](#1---case-functions) to inspect the case functions.
+ - `ids`: optional custom ids, similar to the one in `pytest.mark.parametrize`. Users may either provide an iterable of string ids, or a callable. If a callable is provided it will receive the case functions. Users may wish to use [`get_case_id`](#get_case_id) or other helpers in the [API](#2-case-functions) to inspect the case functions.
 
  - `idstyle`: This is mostly for debug. Style of ids to be used in the "union" fixtures generated by [`@parametrize`](#parametrize) if some cases are transformed into fixtures behind the scenes. `idstyle` possible values are `'compact'`, `'explicit'` or `None`/`'nostyle'` (default), or a callable. `idstyle` has no effect if no cases are transformed into fixtures. As opposed to `ids`, a callable provided here will receive a `ParamAlternative` object indicating which generated fixture should be used. See [`@parametrize`](#parametrize) for details.
 
  - `scope`: The scope of the union fixture to create if `fixture_ref`s are found in the argvalues
 
  - `import_fixtures`: experimental feature. Turn this to `True` in order to automatically import all fixtures defined in the cases module into the current module.
 
-### `get_current_case_id`
+### `get_current_cases`
 
 ```python
-def get_current_case_id(request_or_item, 
-                        argnames: Union[Iterable[str], str]
-                        ):
+def get_current_cases(request_or_item):
 ```
 
-A helper function to return the current case id for a given `pytest` item (available in some hooks) or `request` 
-(available in hooks, and also directly as a fixture).
+Returns a dictionary containing all case parameters for the currently active `pytest` item. You can either pass the `pytest` item (available in some hooks) or the `request` (available in hooks, and also directly as a fixture).
+
+For each test function argument parametrized using a [`@parametrize_with_case(<argname>, ...)`](#parametrize_with_cases) this dictionary contains an entry `{<argname>: (actual_id, case_function)}`. If several argnames are parametrized this way, a dedicated entry will be present for each argname.
+
+If a fixture parametrized with cases is active, the dictionary will contain an entry `{<fixturename>: <dct>}` where `<dct>` is a dictionary `{<argname>: (actual_id, case_function)}`.
+
+To get more information on a case function, you can use [`get_case_id(f)`](#get_case_id), [`get_case_marks(f)`](#get_case_marks), [`get_case_tags(f)`](#get_case_tags). You can also use [`matches_tag_query`](#matches_tag_query) to check if a case function matches some expectations either concerning its id
+or its tags. See [filters and tags documentation](https://smarie.github.io/python-pytest-cases/#filters-and-tags).
 
-You need to provide the argname(s) used in the corresponding `@parametrize_with_cases` so that this method finds
-the right id.
+Note that you can get the same contents directly by using the [`current_cases`](#current_cases) fixture.
 
 ### `get_all_cases`
 
@@ -336,7 +352,7 @@ Transforms a list of cases (obtained from [`get_all_cases`](#get_all_cases)) int
 
  - Otherwise, `case_fun` represents a single case: in that case a single `lazy_value` is returned.
 
-## 3 - Pytest goodies
+## 4 - Pytest goodies
 
 ### `@fixture`
 
@@ -383,9 +399,9 @@ The created fixtures are automatically registered into the callers' module, but
 
 ```python
 import pytest
-from pytest_cases import unpack_fixture, fixture_plus
+from pytest_cases import unpack_fixture, fixture
 
-@fixture_plus
+@fixture
 @pytest.mark.parametrize("o", ['hello', 'world'])
 def c(o):
     return o, o[0]

docs/index.md

@@ -7,6 +7,8 @@
 [![Documentation](https://img.shields.io/badge/doc-latest-blue.svg)](https://smarie.github.io/python-pytest-cases/) [![PyPI](https://img.shields.io/pypi/v/pytest-cases.svg)](https://pypi.python.org/pypi/pytest-cases/) [![Downloads](https://pepy.tech/badge/pytest-cases)](https://pepy.tech/project/pytest-cases) [![Downloads per week](https://pepy.tech/badge/pytest-cases/week)](https://pepy.tech/project/pytest-cases) [![GitHub stars](https://img.shields.io/github/stars/smarie/python-pytest-cases.svg)](https://github.com/smarie/python-pytest-cases/stargazers)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3937829.svg)](https://doi.org/10.5281/zenodo.3937829)
 
+!!! success "New `current_cases` fixture to easily know the current case for each parameter ! See [below](#c-accessing-the-current-case) for details."
+
 !!! success "Major refactoring of test ids in v3.0.0 ! See [below](#d-test-ids) for details."
 
 !!! success "`@parametrize` now automatically detects fixture symbols ! See [documentation](./pytest_goodies.md#parametrize) for details."
@@ -475,22 +477,50 @@ def test_caching(cached_a, d):
 
 !!! warning "If you add a cache mechanism, make sure that your test functions do not modify the returned objects !"
 
-### c- Accessing the current case id
+### c- Accessing the current case
+
+In some scenarii you may wish to access the case functions that are currently used to provide the parameter values. This may be
+
+ - to make your test behave differently depending on the case function, case id or case tags
+ - to `pytest.skip` some combinations of parameters/cases that do not make sense
+ - ...
 
-You may need to access the current case id from within a `pytest` hook or the test itself. For this the `get_current_case_id` helper function is provided:
+With `pytest-cases` starting in version `3.5`, this is now possible thanks to the `current_cases` fixture. Simply use this fixture to get a dictionary containing the actual parameter id and case function for all parameters parametrized with cases in the current test node. Parametrized fixtures, if any, will appear in a sub-dictionary indexed by the fixture name.
 
 ```python
-from pytest_cases import parametrize_with_cases, get_current_case_id
+from pytest_cases import parametrize_with_cases, fixture
 
 def case_a():
     return 1
 
+@fixture
+@parametrize_with_cases("foo", cases=case_a)
+def my_fixture(foo):
+    return foo
+
 @parametrize_with_cases("data", cases=case_a)
-def test_lazy_val_case(data, request):
-    assert get_current_case_id(request, "data") == "a"
+def test_get_current_case(data, my_fixture, current_cases):
+    
+    # this is how to access the case function for a test parameter
+    actual_case_id, case_fun = current_cases["data"]
+
+    # this is how to access the case function for a fixture parameter
+    fix_actual_case_id, fix_case_fun = current_cases["my_fixture"]["foo"]
+    
+    # let's print everything
+    print(current_cases)
 ```
 
-See [API reference](./api_reference.md#get_current_case_id) for details.
+yields
+
+```
+{'data': ('a', <function case_a at 0x00000205BED1CF28>),
+ 'my_fixture': {'foo': ('a', <function case_a at 0x00000205BED1CF28>)}}
+```
+
+To get more information on the case function, you can use `get_case_id(f)`, `get_case_marks(f)`, `get_case_tags(f)`. You can also use `matches_tag_query` to check if a case function matches some expectations either concerning its id or its tags. See [API reference](./api_reference.md#matches_tag_query).
+
+Note: you can get the same information from a pytest hook, using the `get_current_cases` function. See [API reference](./api_reference.md#get_current_cases) for details.
 
 ### d- Test ids
 

pytest_cases/plugin.py

@@ -1468,10 +1468,7 @@ def current_cases(request):
     """
     A fixture containing `get_current_cases(request)`
 
-    Returns a dictionary containing all case parameters for the currently active `pytest` item.
-    You can either pass the `pytest` item (available in some hooks) or the `request` (available in hooks, and also
-    directly as a fixture).
-
+    This is a dictionary containing all case parameters for the currently active `pytest` item.
     For each test function argument parametrized using a `@parametrize_with_case(<argname>, ...)` this dictionary
     contains an entry `{<argname>: (actual_id, case_function)}`. If several argnames are parametrized this way,
     a dedicated entry will be present for each argname.