🐛 Inject build_tags to variant filter strings (#1531)

Instead of passing Sphinx tags directly into the context variable scope
for filter strings, a new variable `build_tags` is injected which is a
`set[str]`.
This avoids namespace clutter and also `NameError`s when checking for
tags.

For now, this is only available for variants. Need to discuss whether to
apply this to all filter strings.

Author: ubmarco

docs/configuration.rst

@@ -2226,7 +2226,7 @@ For example, in ``conf.py``:
 .. code-block:: python
 
    needs_variants = {
-     "var_a": "'var_a' in sphinx_tags"  # filter_string
+     "var_a": "'var_a' in build_tags"  # filter_string
      "var_b": "assignee == 'me'"
    }
 

docs/directives/need.rst

@@ -51,13 +51,14 @@ Rules for specifying variant definitions
 * When evaluating a variant definition, we use data from the current need object,
   `Sphinx-Tags <https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-t>`_,
   and :ref:`needs_filter_data` as the context for filtering.
+  Sphinx tags are injected under the name ``build_tags`` as a set of strings.
 * You can set a *need option* to multiple variant definitions by separating each definition with either
-  the ``,`` symbol, like ``var_a:open, ['name' in tags]:assigned``. |br|
+  the ``,`` symbol, like ``var_a:open, ['name' in tags]:assigned``.|br|
   With multiple variant definitions, we set the first matching variant as the *need option's* value.
 * When you set a *need option* to multiple variant definitions, you can specify the last definition as
   a default "variant-free" option which we can use if no variant definition matches. |br|
-  Example; In this multi-variant definitions, ``[status in tags]:added, var_a:changed, unknown``, *unknown* will be used
-  if none of the other variant definitions are True.
+  Example; In this multi-variant definitions, ``[status in tags]:added, var_a:changed, unknown``,
+  *unknown* will be used if none of the other variant definitions are True.
 * If you prefer your variant definitions to use rules instead of keys, then you should put your filter string
   inside square brackets like this: ``['name' in tags]:assigned``.
 * For multi-variant definitions, you can mix both rule and variant-named options like this:
@@ -82,7 +83,7 @@ For example, in your ``conf.py``:
 .. code-block:: python
 
    needs_variants = {
-     "var_a": "'var_a' in sphinx_tags"  # filter_string
+     "var_a": "'var_a' in build_tags"  # filter_string, check for Sphinx tags
      "var_b": "assignee == 'me'"
    }
 
@@ -95,7 +96,7 @@ In your ``.rst`` file:
       :status: <<var_a:open, var_b:closed, unknown>>
 
 From the above example, if a *need option* has variants defined, then we get the filter string
-from our ``needs_variants`` configuration and evaluate it.
+from the ``needs_variants`` configuration and evaluate it.
 If a variant definition is true, then we set the *need option* to the value of the variant definition.
 
 Use Case 2
@@ -139,7 +140,7 @@ In your ``.rst`` file:
 
    .. req:: Example
       :id: VA_003
-      :status: <<[tag_a and tag_b]:open, closed>>
+      :status: <<['tag_a' in build_tags and 'tag_b' in build_tags]:open, closed>>
 
 From the above example, if a tag is defined, the plugin can access it in the filter context when handling variants.
 If a variant definition is true, then we set the *need option* to the value of the variant definition.

sphinx_needs/functions/functions.py

@@ -314,7 +314,7 @@ def resolve_functions(
                         var_context: dict[str, Any] = {
                             **need,
                             **needs_config.filter_data,
-                            **dict.fromkeys(app.builder.tags, True),
+                            "build_tags": set(app.builder.tags),
                         }
                         if (
                             var_return := _get_variant(

tests/__snapshots__/test_variants.ambr

@@ -14,7 +14,7 @@
             'sections': list([
               'Empty Variant Options Handling Test',
             ]),
-            'status': '<<[tag_a]:open, unknown>>',
+            'status': 'open',
             'title': 'Empty Variant Options',
             'type': 'spec',
             'type_name': 'Specification',
@@ -75,6 +75,7 @@
             'sections': list([
               'Variant Handling Test',
             ]),
+            'status': 'unknown',
             'title': 'Unknown Variant',
             'type': 'spec',
             'type_name': 'Specification',

tests/doc_test/variant_doc/index.rst

@@ -7,7 +7,7 @@ Variant Handling Test
 
 .. spec:: Tags Example
    :id: VA_003
-   :status: <<[tag_a and tag_b]:tags_implemented, closed>>
+   :status: <<[all(x in build_tags for x in ['tag_a', 'tag_b'])]:tags_implemented, closed>>
 
 .. story:: Test story
    :id: ST_001
@@ -24,11 +24,11 @@ Variant Handling Test
 
 .. spec:: Variant Specification
    :id: SPEC_003
-   :status: <<[tag_a]:open, unknown>>
+   :status: <<['tag_a' in build_tags]:open, unknown>>
 
 .. spec:: Unknown Variant
    :id: SPEC_004
-   :status: <<[tag_c]:open, unknown>>
+   :status: <<['tag_c' in build_tags]:open, unknown>>
 
 .. needtable::
    :filter: status in ("open", "close", "progress")

tests/doc_test/variant_options/conf.py

@@ -38,7 +38,7 @@
     },
 ]
 needs_variants = {"change_author": "assignee == 'Randy Duodu'"}
-needs_variant_options = []
+needs_variant_options = ["status"]
 needs_filter_data = {"assignee": "Randy Duodu"}
 needs_extra_options = [
     "my_extra_option",

tests/doc_test/variant_options/index.rst

@@ -3,7 +3,7 @@ Empty Variant Options Handling Test
 
 .. spec:: Empty Variant Options
    :id: EMPTY_VAR_003
-   :status: <<[tag_a]:open, unknown>>
+   :status: <<['tag_a' in build_tags]:open, unknown>>
 
 .. toctree::
    :maxdepth: 2

tests/test_variants.py

@@ -65,10 +65,7 @@ def test_variant_options_html(test_app, snapshot):
     app.build()
 
     warnings = strip_colors(app._warning.getvalue()).splitlines()
-    # print(warnings)
-    assert warnings == [
-        f"{Path(str(app.srcdir)) / 'index.rst'}:29: WARNING: Error while resolving dynamic values for field 'status', of need 'SPEC_004': name 'tag_c' is not defined [needs.dynamic_function]"
-    ]
+    assert warnings == []
 
     needs = json.loads(Path(app.outdir, "needs.json").read_text())
     assert needs == snapshot(