🔧 Add better typing for global_options config variable (#1120)

sphinx_needs/api/need.py

@@ -23,7 +23,7 @@
     NeedsTagNotAllowed,
     NeedsTemplateException,
 )
-from sphinx_needs.config import NeedsSphinxConfig
+from sphinx_needs.config import GlobalOptionsType, NeedsSphinxConfig
 from sphinx_needs.data import NeedsInfoType, SphinxNeedsData
 from sphinx_needs.directives.needuml import Needuml, NeedumlException
 from sphinx_needs.filter_common import filter_single_need
@@ -797,7 +797,7 @@ def _merge_extra_options(
 
 
 def _merge_global_options(
-    app: Sphinx, needs_info: NeedsInfoType, global_options: dict[str, Any]
+    app: Sphinx, needs_info: NeedsInfoType, global_options: GlobalOptionsType
 ) -> None:
     """Add all global defined options to needs_info"""
     if global_options is None:
@@ -817,7 +817,9 @@ def _merge_global_options(
             continue
 
         for single_value in values:
+            # TODO should first match break loop?
             if len(single_value) < 2 or len(single_value) > 3:
+                # TODO this should be validated earlier at the "config" level
                 raise NeedsInvalidException(
                     f"global option tuple has wrong amount of parameters: {key}"
                 )

sphinx_needs/config.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from dataclasses import MISSING, dataclass, field, fields
-from typing import TYPE_CHECKING, Any, Callable, Literal, TypedDict
+from typing import TYPE_CHECKING, Any, Callable, Dict, Literal, TypedDict
 
 from sphinx.application import Sphinx
 from sphinx.config import Config as _SphinxConfig
@@ -101,6 +101,20 @@ class ExternalSource(TypedDict, total=False):
     """Added as the `external_css` field for each need item (optional)"""
 
 
+GlobalOptionsType = Dict[str, Any]
+"""Default values given to specified fields of needs
+
+Values can be:
+
+- a tuple: ``(value, filter_string)``, where the default is only applied if the filter_string is fulfilled
+- a tuple: ``(value, filter_string, alternative default)``, 
+    where the default is applied if the filter_string is fulfilled, 
+    otherwise the alternative default is used
+- a list of the tuples above
+- otherwise, always set as the given value
+"""
+
+
 @dataclass
 class NeedsSphinxConfig:
     """A wrapper around the Sphinx configuration,
@@ -236,9 +250,10 @@ def __setattr__(self, name: str, value: Any) -> None:
     functions: list[Callable[..., Any]] = field(
         default_factory=list, metadata={"rebuild": "html", "types": (list,)}
     )
-    global_options: dict[str, Any] = field(
+    global_options: GlobalOptionsType = field(
         default_factory=dict, metadata={"rebuild": "html", "types": (dict,)}
     )
+    """Default values given to specified fields of needs"""
     duration_option: str = field(
         default="duration", metadata={"rebuild": "html", "types": (str,)}
     )