♻️ Auto-compute certain need fields (#1496)

A number of need fields are actually data that is based on other data:

- `is_need` / `is_part` are based on whether the item is a `NeedItem` or
`NeedPartItem` instance
- `is_modified` is based on if `modifications > 0`
- `id_parent` / `id_complete` are based on the `id` (and part `id` if
`NeedPartItem`)
- `section_name` is the first item in `sections`
- `parent_need` is the first item in the `parent_needs` links
- `constraints` is the keys of `constraints_results`
- `constraints_passed` is derived from `constraints_results`

These are mainly there for user convenience when writing filters, but
are not necessary to specify independently, and could lead to
inconcistencies in the data.

Therefore, these fields are now auto-computed when
initialiasing/modifying the need, rather than being allowed to be
specified / modified independantly.

Author: chrisjsewell

docs/api.rst

@@ -41,7 +41,7 @@ Data
    :members: NeedItem, NeedPartItem, NeedItemSourceProtocol
 
 .. automodule:: sphinx_needs.data
-   :members: NeedsInfoType, NeedsSourceInfoType, NeedsMutable, NeedsPartType
+   :members: NeedsInfoType, NeedsInfoComputedType, NeedsSourceInfoType, NeedsMutable, NeedsPartType
 
 Views
 -----

sphinx_needs/api/need.py

@@ -4,7 +4,7 @@
 import os
 import re
 import warnings
-from collections.abc import Iterable, Iterator
+from collections.abc import Iterable, Iterator, Sequence
 from contextlib import contextmanager
 from pathlib import Path
 from typing import Any, TypeVar
@@ -64,7 +64,7 @@ def generate_need(
     parts: dict[str, NeedsPartType] | None = None,
     arch: dict[str, str] | None = None,
     signature: None | str = None,
-    sections: list[str] | None = None,
+    sections: Sequence[str] | None = None,
     jinja_content: bool | None = None,
     hide: None | bool = None,
     collapse: None | bool = None,
@@ -321,10 +321,6 @@ def generate_need(
         links_no_defaults, needs_config, defaults_ctx, defaults_extras, defaults_links
     )
     _copy_links(links, needs_config)
-    # ensure parent_need is consistent with parent_needs
-    parent_need = (
-        parent_needs[0] if (parent_needs := links.get("parent_needs")) else None
-    )
 
     # Add the need and all needed information
     needs_data: NeedsInfoType = {
@@ -339,9 +335,7 @@ def generate_need(
         "type_style": need_type_data.get("style") or "node",
         "status": status,
         "tags": tags,
-        "constraints": constraints,
-        "constraints_passed": True,
-        "constraints_results": {},
+        "constraints_results": {k: {} for k in constraints},
         "constraints_error": None,
         "id": need_id,
         "title": title,
@@ -355,19 +349,12 @@ def generate_need(
         "hide": hide,
         "jinja_content": jinja_content or False,
         "parts": parts or {},
-        "is_part": False,
-        "is_need": True,
-        "id_parent": need_id,
-        "id_complete": need_id,
         "external_css": external_css or "external_link",
-        "is_modified": False,
         "modifications": 0,
         "has_dead_links": False,
         "has_forbidden_dead_links": False,
-        "sections": sections or [],
-        "section_name": sections[0] if sections else None,
+        "sections": tuple(sections or ()),
         "signature": signature,
-        "parent_need": parent_need,
     }
 
     needs_info = NeedItem(
@@ -653,7 +640,7 @@ def _create_need_node(
         )
 
     # Extract plantuml diagrams and store needumls with keys in arch, e.g. need_info['arch']['diagram']
-    data["arch"] = {}
+    arch = {}
     node_need_needumls_without_key = []
     node_need_needumls_key_names = []
     for child in node_need.children:
@@ -669,7 +656,7 @@ def _create_need_node(
                                 f"Inside need: {data['id']}, found duplicate Needuml option key name: {key_name}"
                             )
                         else:
-                            data["arch"][key_name] = needuml["content"]
+                            arch[key_name] = needuml["content"]
                             node_need_needumls_key_names.append(key_name)
                     else:
                         node_need_needumls_without_key.append(needuml)
@@ -678,9 +665,10 @@ def _create_need_node(
 
     # only store the first needuml-node which has no key option under diagram
     if node_need_needumls_without_key:
-        data["arch"]["diagram"] = node_need_needumls_without_key[0]["content"]
+        arch["diagram"] = node_need_needumls_without_key[0]["content"]
+
+    data["arch"] = arch
 
-    data["parts"] = {}
     need_parts = find_parts(node_need)
     update_need_with_parts(env, data, need_parts)
 

sphinx_needs/data.py

@@ -328,7 +328,7 @@ class CoreFieldParameters(TypedDict):
     },
     "constraints": {
         "description": "List of constraint names, which are defined for this need.",
-        "schema": {"type": "array", "items": {"type": "string"}, "default": []},
+        "schema": {"type": "array", "items": {"type": "string"}, "default": ()},
         "allow_default": "str_list",
         "allow_df": True,
         "allow_extend": True,
@@ -361,7 +361,7 @@ class CoreFieldParameters(TypedDict):
     },
     "sections": {
         "description": "Sections of the need.",
-        "schema": {"type": "array", "items": {"type": "string"}, "default": []},
+        "schema": {"type": "array", "items": {"type": "string"}, "default": ()},
         "exclude_import": True,
     },
     "section_name": {
@@ -424,10 +424,6 @@ class NeedsInfoType(TypedDict):
     style: None | str
     """Comma-separated list of CSS classes (all appended by `needs_style_`)."""
 
-    # TODO why is it called arch?
-    arch: dict[str, str]
-    """Mapping of uml key to uml content."""
-
     external_css: str
     """CSS class name, added to the external reference."""
 
@@ -439,21 +435,11 @@ class NeedsInfoType(TypedDict):
     """Hexadecimal color code of the type."""
     type_style: str
 
-    is_modified: bool
-    """Whether the need was modified by needextend."""
     modifications: int
     """Number of modifications by needextend."""
 
-    # used to distinguish a part from a need
-    is_need: bool
-    is_part: bool
     # Mapping of parts, a.k.a. sub-needs, IDs to data that overrides the need's data
-    parts: dict[str, NeedsPartType]
-    # additional information required for compatibility with parts
-    id_parent: str
-    """<parent ID>, or <self ID> if not a part."""
-    id_complete: str
-    """<parent ID>.<self ID>, or <self ID> if not a part."""
+    parts: Mapping[str, NeedsPartType]
 
     # content creation information
     jinja_content: bool
@@ -463,6 +449,8 @@ class NeedsInfoType(TypedDict):
     content: str
     pre_content: None | str
     post_content: None | str
+    doctype: str
+    """Type of the document where the need is defined, e.g. '.rst'."""
 
     # these default to False and are updated in check_links post-process
     has_dead_links: bool
@@ -473,27 +461,45 @@ class NeedsInfoType(TypedDict):
     """
 
     # constraints information
-    constraints: list[str]
-    """List of constraint names, which are defined for this need."""
     # set in process_need_nodes (-> process_constraints) transform
-    constraints_results: dict[str, dict[str, bool]]
+    constraints_results: Mapping[str, dict[str, bool]]
     """Mapping of constraint name, to check name, to result."""
-    constraints_passed: bool
-    """True if all constraints passed, False if any failed, None if not yet checked."""
     constraints_error: None | str
     """An error message set if any constraint failed, and `error_message` field is set in config."""
 
     # additional source information
-    doctype: str
-    """Type of the document where the need is defined, e.g. '.rst'."""
     # set in analyse_need_locations transform
-    sections: list[str]
-    section_name: None | str
-    """Simply the first section."""
+    sections: tuple[str, ...]
     signature: None | str
     """Derived from a docutils desc_name node."""
+
+    arch: Mapping[str, str]  #  short for architecture.
+    """Mapping of uml key to uml content."""
+
+
+class NeedsInfoComputedType(TypedDict):
+    """Data for a single need, that can be computed from existing data.
+
+    These fields are used for convenience in filters.
+    """
+
+    is_need: bool
+    is_part: bool
+    is_modified: bool
+    """Whether the need was modified by needextend."""
+    # additional information required for compatibility with parts
+    id_parent: str
+    """<parent ID>, or <self ID> if not a part."""
+    id_complete: str
+    """<parent ID>.<self ID>, or <self ID> if not a part."""
+    section_name: None | str
+    """Simply the first section."""
     parent_need: None | str
     """Simply the first parent id."""
+    constraints: tuple[str, ...]
+    """List of constraint names, which are defined for this need."""
+    constraints_passed: bool
+    """True if all constraints passed, False if any failed, None if not yet checked."""
 
 
 class NeedsBaseDataType(TypedDict):

sphinx_needs/directives/need.py

@@ -319,7 +319,7 @@ def analyse_need_locations(app: Sphinx, doctree: nodes.document) -> None:
 
         # first we initialize to default values
         if "sections" not in need_info:
-            need_info["sections"] = []
+            need_info["sections"] = ()
 
         if "section_name" not in need_info:
             need_info["section_name"] = None
@@ -341,15 +341,13 @@ def analyse_need_locations(app: Sphinx, doctree: nodes.document) -> None:
 
         # append / set values from need
         if sections:
-            need_info["sections"] = sections
-            need_info["section_name"] = sections[0]
+            need_info["sections"] = tuple(sections)
 
         if signature:
             need_info["signature"] = str(signature)
 
         if parent_needs:
             need_info["parent_needs"] = parent_needs
-            need_info["parent_need"] = parent_needs[0]
 
         if need_node.get("hidden"):
             hidden_needs.append(need_node)

sphinx_needs/directives/needextend.py

@@ -214,7 +214,6 @@ def extend_needs_data(
         for found_need in found_needs:
             # Work in the stored needs, not on the search result
             need = all_needs[found_need["id"]]
-            need["is_modified"] = True
             need["modifications"] += 1
 
             location = (

sphinx_needs/need_constraints.py

@@ -25,12 +25,8 @@ def process_constraints(needs: NeedsMutable, config: NeedsSphinxConfig) -> None:
 
     for need in needs.values():
         need_id = need["id"]
-        constraints = need["constraints"]
 
-        # flag that is set to False if any check fails
-        need["constraints_passed"] = True
-
-        for constraint in constraints:
+        for constraint in need["constraints_results"]:
             try:
                 executable_constraints = config_constraints[constraint]
             except KeyError:
@@ -46,12 +42,8 @@ def process_constraints(needs: NeedsMutable, config: NeedsSphinxConfig) -> None:
                 # compile constraint and check if need fulfils it
                 constraint_passed = filter_single_need(need, config, cmd)
 
-                if constraint_passed:
-                    need["constraints_results"].setdefault(constraint, {})[name] = True
-                else:
-                    need["constraints_results"].setdefault(constraint, {})[name] = False
-                    need["constraints_passed"] = False
-
+                need["constraints_results"][constraint][name] = constraint_passed
+                if not constraint_passed:
                     if "error_message" in executable_constraints:
                         msg = str(executable_constraints["error_message"])
                         template = error_templates_cache.setdefault(