Skip to content

Commit c160dcc

Browse files
authored
docs: note that numeric cases filtering requires Sphinx-Needs >= 6 (#139)
## Summary Follow-up to #136. That PR switched the filter examples to direct numeric comparisons (`cases > 4`, `cases >= 5`), which is correct for **Sphinx-Needs >= 6**: there the count fields are registered with an integer schema (`sphinxcontrib/test_reports/test_reports.py:245-250`) and the directives pass real `int` values. On Sphinx-Needs < 6 (the `else` branch at `test_reports.py:260-266`) those fields have no integer schema and are stored as strings, so `cases > 4` raises a `TypeError` during filtering — which is why the original `cases.isdigit() and int(cases) > 4` form was used. The two forms are version-specific inverses, so this is a documentation note rather than a code change. This adds a `.. note::` to `docs/filter.rst` stating that numeric filtering requires Sphinx-Needs >= 6 and pointing users on older versions to the `isdigit()` / `int()` form. ## Alternative The runtime dependency floor is still `sphinx-needs>=1.0.1` (`pyproject.toml`), while the test extra already pins `>=6`. If support for Sphinx-Needs < 6 is no longer intended, an alternative to this note would be to bump the runtime floor to `>=6` and drop the legacy `else` branch in `sphinx_needs_update()`. Happy to do that instead if preferred. ## Validation - Documentation-only change; no code paths touched.
1 parent 6677baa commit c160dcc

1 file changed

Lines changed: 8 additions & 0 deletions

File tree

docs/filter.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,14 @@ Usage::
9292
``filter`` supports complex-filter operations by using a Python-statement.
9393
In this case, we check that the ``cases`` value is greater than 4.
9494

95+
.. note::
96+
97+
Numeric comparisons such as ``cases > 4`` require Sphinx-Needs 6.0 or newer,
98+
where the count fields (``suites``, ``cases``, ``passed``, ``skipped``,
99+
``failed`` and ``errors``) are stored as integers. On older Sphinx-Needs
100+
versions these values are strings, so use
101+
``cases.isdigit() and int(cases) > 4`` instead.
102+
95103
Take a look into the
96104
`Filter string section <https://sphinx-needs.readthedocs.io/en/latest/filter.html#filter-string>`_
97105
of the Sphinx-Needs documentations for more details and ideas how to use it.

0 commit comments

Comments
 (0)