🔧 Centralise sphinx env data access (and add schemas) (#987)

The sphinx-needs data stored on the Sphinx `BuildEnvironment` is currently difficult to interpret and work with,
since the dynamic nature of `BuildEnvironment` provides no type safety or static introspection.

This commit centralises access to sphinx-needs data, via `sphinx_needs.data.SphinxNeedsData`,
which is a thin wrapper around the sphinx `BuildEnvironment`,
to define and provide type safe access to the sphinx-need specific data.

`TypedDict` are used to type annotate the dictionary keys for the different data types,
and thus `sphinx_needs.data` essentially provides a schema for the data that sphinx-needs stores.

This is a non-breaking change, since all data can still be accessed via the sphinx `BuildEnvironment`,
(although this is now discouraged).

Author: chrisjsewell

pyproject.toml

@@ -93,6 +93,7 @@ warn_unused_ignores = false
 module = [
   'sphinx_needs.api.need',
   'sphinx_needs.builder',
+  'sphinx_needs.data',
   'sphinx_needs.diagrams_common',
   'sphinx_needs.directives.need',
   'sphinx_needs.directives.needbar',
@@ -116,6 +117,7 @@ module = [
   'sphinx_needs.needs',
   'sphinx_needs.needsfile',
   'sphinx_needs.roles.need_incoming',
+  'sphinx_needs.roles.need_outgoing',
   'sphinx_needs.roles.need_part',
   'sphinx_needs.roles.need_ref',
   'sphinx_needs.services.github',

sphinx_needs/api/need.py

@@ -22,6 +22,7 @@
     NeedsTemplateException,
 )
 from sphinx_needs.config import 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
 from sphinx_needs.logging import get_logger
@@ -271,11 +272,8 @@ def run():
     #############################################################################################
     # Add need to global need list
     #############################################################################################
-    # be sure, global var is available. If not, create it
-    if not hasattr(env, "needs_all_needs"):
-        env.needs_all_needs = {}
 
-    if need_id in env.needs_all_needs:
+    if need_id in SphinxNeedsData(env).get_or_create_needs():
         if id:
             raise NeedsDuplicatedId(
                 f"A need with ID {need_id} already exists! "
@@ -307,7 +305,7 @@ def run():
         doctype = ".rst"
 
     # Add the need and all needed information
-    needs_info = {
+    needs_info: NeedsInfoType = {
         "docname": docname,
         "doctype": doctype,
         "lineno": lineno,
@@ -403,7 +401,7 @@ def run():
         content = new_content
         needs_info["content"] = new_content
 
-    env.needs_all_needs[need_id] = needs_info
+    SphinxNeedsData(env).get_or_create_needs()[need_id] = needs_info
 
     # Template builds
     ##############################
@@ -457,7 +455,7 @@ def run():
         if isinstance(child, Needuml):
             needuml_id = child.rawsource
             try:
-                needuml = env.needs_all_needumls.get(needuml_id)
+                needuml = SphinxNeedsData(env).get_or_create_umls().get(needuml_id)
                 key_name = needuml["key"]
                 if key_name:
                     # check if key_name already exists in needs_info["arch"]
@@ -507,8 +505,9 @@ def del_need(app: Sphinx, need_id: str) -> None:
     :param need_id: Sphinx need id.
     """
     env = unwrap(app.env)
-    if need_id in env.needs_all_needs:
-        del env.needs_all_needs[need_id]
+    needs = SphinxNeedsData(env).get_or_create_needs()
+    if need_id in needs:
+        del needs[need_id]
     else:
         logger.warning(f"Given need id {need_id} not exists! [needs]", type="needs")
 

sphinx_needs/builder.py

@@ -7,6 +7,7 @@
 from sphinx.builders import Builder
 
 from sphinx_needs.config import NeedsSphinxConfig
+from sphinx_needs.data import SphinxNeedsData
 from sphinx_needs.logging import get_logger
 from sphinx_needs.needsfile import NeedsList
 from sphinx_needs.utils import unwrap
@@ -25,8 +26,9 @@ def write_doc(self, docname: str, doctree: nodes.document) -> None:
 
     def finish(self) -> None:
         env = unwrap(self.env)
-        needs = env.needs_all_needs.values()  # We need a list of needs for later filter checks
-        filters = env.needs_all_filters
+        data = SphinxNeedsData(env)
+        needs = data.get_or_create_needs().values()  # We need a list of needs for later filter checks
+        filters = data.get_or_create_filters()
         version = getattr(env.config, "version", "unset")
         needs_list = NeedsList(env.config, self.outdir, self.srcdir)
         needs_config = NeedsSphinxConfig(env.config)
@@ -107,7 +109,7 @@ def write_doc(self, docname: str, doctree: nodes.document) -> None:
 
     def finish(self) -> None:
         env = unwrap(self.env)
-        needumls = env.needs_all_needumls.values()
+        needumls = SphinxNeedsData(env).get_or_create_umls().values()
 
         for needuml in needumls:
             if needuml["save"]: