Merge branch 'master' into add_config_report_dead_links

.gitignore

@@ -1,7 +1,7 @@
 .idea
 .venv*
 .pvenv
-
+.nox
 node_modules
 
 .envrc

.pre-commit-config.yaml

@@ -1,11 +1,11 @@
 repos:
   - repo: https://github.com/psf/black
-    rev: 22.12.0
+    rev: 23.7.0
     hooks:
       - id: black
 
   - repo: https://github.com/PyCQA/flake8
-    rev: 6.0.0
+    rev: 6.1.0
     hooks:
       - id: flake8
         additional_dependencies:
@@ -20,7 +20,7 @@ repos:
       - id: isort
 
   - repo: https://github.com/asottile/pyupgrade
-    rev: v3.3.1
+    rev: v3.10.1
     hooks:
       - id: pyupgrade
         args:
@@ -36,6 +36,6 @@ repos:
         pass_filenames: false
 
   - repo: https://github.com/python-poetry/poetry
-    rev: 1.3.0
+    rev: 1.5.0
     hooks:
       - id: poetry-check

docs/api.rst

@@ -11,7 +11,7 @@ to keep the final configuration transparent for the Sphinx project authors.
 
 For some implementation ideas, take a look into the Sphinx extension
 `Sphinx-Test-Reports <https://sphinx-test-reports.readthedocs.io/en/latest/>`_ and its
-`source code <https://github.com/useblocks/sphinx-test-reports/blob/master/sphinxcontrib/test_reports/test_reports.py#L51>`_.
+`source code <https://github.com/useblocks/sphinx-test-reports/blob/master/sphinxcontrib/test_reports/test_reports.py>`_.
 
 .. _api_configuration:
 

docs/changelog.rst

@@ -30,6 +30,9 @@ Released: under development
 * Improvement: Added configuration option :ref:`needs_report_dead_links`, which can deactivate log messages of
   outgoing dead links.
   (`#920 <https://github.com/useblocks/sphinx-needs/issues/920>`_)
+* Improvement: Configuration option :ref:`needs_allow_unsafe_filters` added, which allows unsafe filter for
+  :ref:`filter_func`.
+  (`#831 <https://github.com/useblocks/sphinx-needs/issues/831>`_)
 
 1.2.2
 -----

docs/configuration.rst

@@ -535,6 +535,27 @@ The defined extra filter data can also be used like:
       :style: green_border
 
 
+.. _needs_allow_unsafe_filters:
+
+needs_allow_unsafe_filters
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Allow unsafe filter for :ref:`filter_func`. Default is ``False``.
+
+If set to True, the filtered results will keep all fields as they are returned by the dynamic functions.
+Fields can be added or existing fields can even be manipulated.
+
+.. note::
+
+   Keep in mind this only affects the filter results, original needs as displayed somewhere else are not modified.
+
+If set to False, the filter results contains the original need fields and any manipulations of need fields are lost.
+
+|ex|
+
+.. code-block:: python
+
+   needs_allow_unsafe_filters = True
 
 .. _needs_flow_show_links:
 

docs/requirements.txt

@@ -7,4 +7,4 @@ sphinxcontrib-programoutput
 sphinx-design
 click
 tabulate
-sphinx-immaterial==0.11.2
+sphinx-immaterial==0.11.6

noxfile.py

@@ -97,3 +97,10 @@ def benchmark_memory(session):
         env={"ON_CI": "true", "FAST_BUILD": "true"},
     )
     session.run("memray", "flamegraph", "-o", "mem_out.html", "mem_out.bin")
+
+
+@session(python="3.8")
+def pre_commit(session):
+    session.run_always("poetry", "install", external=True)
+    session.install("pre-commit")
+    session.run("pre-commit", "run", "--all-files", external=True)

pyproject.toml

@@ -59,8 +59,6 @@ types-requests = "^2.27.25"
 types-setuptools = "^65.6.0.2"
 docutils-stubs = "^0.0.22"
 
-sphinx-immaterial = { version = "==0.7.3", optional = true }
-
 # formatting dependencies
 black = "^22.3"
 isort = "^5.7.0"
@@ -127,10 +125,6 @@ module = [
 ]
 ignore_errors = true
 
-[tool.poetry.extras]
-docs = ["sphinx"]
-immaterial = ["sphinx-immaterial"]
-
 [build-system]
 requires = ["setuptools", "poetry_core>=1.0.8"]  # setuptools for deps like plantuml
 build-backend = "poetry.core.masonry.api"

sphinx_needs/api/need.py

@@ -210,7 +210,6 @@ def run():
     if tags is None:
         tags = []
     if len(tags) > 0:
-
         # tags should be a string, but it can also be already a list, which can be used.
         if isinstance(tags, str):
             tags = [tag.strip() for tag in re.split("[;,]", tags)]
@@ -238,7 +237,6 @@ def run():
     if constraints is None:
         constraints = []
     if len(constraints) > 0:
-
         # tags should be a string, but it can also be already a list,which can be used.
         if isinstance(constraints, str):
             constraints = [constraint.strip() for constraint in re.split("[;,]", constraints)]
@@ -733,7 +731,6 @@ def _merge_global_options(app: Sphinx, needs_info, global_options) -> None:
     if global_options is None:
         return
     for key, value in global_options.items():
-
         # If key already exists in needs_info, this global_option got overwritten manually in current need
         if key in needs_info and needs_info[key]:
             continue

sphinx_needs/builder.py

@@ -80,7 +80,6 @@ def get_target_uri(self, _docname: str, _typ: Optional[str] = None) -> str:
 
 
 def build_needs_json(app: Sphinx, _exception: Exception) -> None:
-
     env = unwrap(app.env)
 
     if not env.config.needs_build_json:

sphinx_needs/directives/needextend.py

@@ -94,7 +94,6 @@ def process_needextend(app: Sphinx, doctree: nodes.document, fromdocname: str) -
         link_names = [x["option"] for x in app.config.needs_extra_links]
 
         for current_needextend in env.need_all_needextend.values():
-
             # Check if filter is just a need-id.
             # In this case create the needed filter string
             need_filter = current_needextend["filter"]

sphinx_needs/directives/needextract.py

@@ -79,7 +79,6 @@ def process_needextract(app: Sphinx, doctree: nodes.document, fromdocname: str,
     env = unwrap(app.env)
 
     for node in found_nodes:
-
         if not app.config.needs_include_needs:
             # Ok, this is really dirty.
             # If we replace a node, docutils checks, if it will not lose any attributes.

sphinx_needs/filter_common.py

@@ -173,11 +173,15 @@ def process_filters(app: Sphinx, all_needs, current_needlist, include_external:
         found_dirty_needs = context["results"]
         found_needs = []
 
-        # Just take the ids from search result and use the related, but original need
-        found_need_ids = [x["id_complete"] for x in found_dirty_needs]
-        for need in all_needs_incl_parts:
-            if need["id_complete"] in found_need_ids:
-                found_needs.append(need)
+        # Check if config allow unsafe filters
+        if app.config.needs_allow_unsafe_filters:
+            found_needs = found_dirty_needs
+        else:
+            # Just take the ids from search result and use the related, but original need
+            found_need_ids = [x["id_complete"] for x in found_dirty_needs]
+            for need in all_needs_incl_parts:
+                if need["id_complete"] in found_need_ids:
+                    found_needs.append(need)
 
     # Store basic filter configuration and result global list.
     # Needed mainly for exporting the result to needs.json (if builder "needs" is used).

sphinx_needs/need_constraints.py

@@ -24,14 +24,12 @@ def process_constraints(app: Sphinx, need: Dict[str, Any]) -> None:
     constraints = need["constraints"]
 
     for constraint in constraints:
-
         # check if constraint is defined in config
         if constraint not in config_constraints.keys():
             raise NeedsConstraintNotAllowed(
                 f"Constraint {constraint} of need id {need_id} is not allowed by config value 'needs_constraints'."
             )
         else:
-
             # access constraints defined in conf.py
             executable_constraints = config_constraints[constraint]
 
@@ -42,7 +40,6 @@ def process_constraints(app: Sphinx, need: Dict[str, Any]) -> None:
             for name, cmd in executable_constraints.items():
                 # compile constraint and check single need if it fulfills constraint
                 if name != "severity":
-
                     # check current need if it meets constraint given in check_0, check_1 in conf.py ...
                     constraint_passed = filter_single_need(app, need, cmd)
                     results_list.append(constraint_passed)
@@ -76,7 +73,6 @@ def process_constraints(app: Sphinx, need: Dict[str, Any]) -> None:
                             )
 
                         if "break" in actions_on_fail:
-
                             raise NeedsConstraintFailed(
                                 f"FAILED a breaking constraint: >> {cmd} << for need "
                                 f"{need_id} FAILED! breaking build process"

sphinx_needs/needs.py

@@ -225,6 +225,7 @@ def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_config_value("needs_report_dead_links", True, "html", types=[bool])
 
     app.add_config_value("needs_filter_data", {}, "html")
+    app.add_config_value("needs_allow_unsafe_filters", False, "html")
 
     app.add_config_value("needs_flow_show_links", False, "html")
     app.add_config_value("needs_flow_link_types", ["links"], "html")

sphinx_needs/services/open_needs.py

@@ -22,7 +22,6 @@ class OpenNeedsService(BaseService):
     options = CONFIG_OPTIONS + EXTRA_DATA_OPTIONS + EXTRA_LINK_OPTIONS
 
     def __init__(self, app: Sphinx, name: str, config: Dict[str, Any], **kwargs: Any) -> None:
-
         self.app = app
         self.name = name
         self.config = config

tests/doc_test/doc_needs_filter_func_allow_dirty_filter/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = needstestdocs
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

tests/doc_test/doc_needs_filter_func_allow_dirty_filter/conf.py

@@ -0,0 +1,57 @@
+# Configuration file for Sphinx-Needs Documentation.
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(os.path.dirname(__file__)))
+
+# -- General configuration ------------------------------------------------
+
+project = "Useblocks Sphinx-Needs Test"
+copyright = "2023, Useblocks GmbH"
+author = "Teams Useblocks"
+version = "1.0"
+
+extensions = ["sphinx_needs", "sphinxcontrib.plantuml"]
+
+needs_id_regex = "^[A-Za-z0-9_]*"
+
+needs_types = [
+    {"directive": "feature", "title": "Feature", "prefix": "FE_", "color": "#FEDCD2", "style": "node"},
+    {"directive": "usecase", "title": "Use Case", "prefix": "USE_", "color": "#DF744A", "style": "node"},
+]
+
+needs_extra_options = ["ti", "tcl"]
+
+needs_extra_links = [
+    {
+        "option": "features",
+        "incoming": "featured by",
+        "outgoing": "features",
+        "copy": False,
+        "style": "#Gold",
+        "style_part": "#Gold",
+    },
+]
+
+needs_allow_unsafe_filters = True
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# Doc info
+source_suffix = ".rst"
+master_doc = "index"
+language = "en"
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "alabaster"

tests/doc_test/doc_needs_filter_func_allow_dirty_filter/filter_func.py

@@ -0,0 +1,14 @@
+def my_own_filter(needs, results, **kwargs):
+    needs_dict = {x["id"]: x for x in needs}
+    curr_need_id = kwargs["arg1"]
+    link_type = kwargs["arg2"]
+
+    for link_id in needs_dict[curr_need_id][link_type]:
+        if needs_dict[curr_need_id]["ti"] == "1":
+            needs_dict[link_id]["tcl"] = "10"
+        elif needs_dict[curr_need_id]["ti"] == "3":
+            needs_dict[link_id]["tcl"] = "30"
+        else:
+            needs_dict[link_id]["tcl"] = "unknown"
+
+        results.append(needs_dict[link_id])

tests/doc_test/doc_needs_filter_func_allow_dirty_filter/index.rst

@@ -0,0 +1,31 @@
+Needs Data to be filtered
+=========================
+
+.. feature:: Feature 001
+   :id: FE_001
+
+   Example feature 001 content.
+
+.. usecase:: Usecase 001
+   :id: USE_001
+   :ti: 1
+   :features: FE_001
+
+   Example tesusecaset 001 content.
+
+   .. needtable:: Filter func table 001
+      :style: table
+      :columns: id, title, tcl
+      :filter-func: filter_func.my_own_filter(USE_001,features)
+
+.. usecase:: Usecase 002
+   :id: USE_002
+   :ti: 3
+   :features: FE_001
+
+   Example usecase 002 content.
+
+   .. needtable:: Filter func table 002
+      :style: table
+      :columns: id, title, tcl
+      :filter-func: filter_func.my_own_filter(USE_002,features)