✨ Add ids option for needimport

A more performant alternative to the `filter` option.

Also, add and to improve the `needimport` tests

docs/directives/needimport.rst

@@ -56,13 +56,25 @@ In most cases this should be the latest available version.
 tags
 ~~~~
 
-You can attach tags to existing tags of imported needs using the ``:tags:`` option.
+You can attach tags to existing tags of imported needs using the ``:tags:`` option
+(as a comma-separated list).
 This may be useful to mark easily imported needs and to create specialised filters for them.
 
+ids
+~~~
+
+.. versionadded:: 3.1.0
+
+You can use the ``:ids:`` option to import only the needs with the given ids
+(as a comma-separated list).
+This is useful if you want to import only a subset of the needs from the JSON file.
+
 filter
 ~~~~~~
 
 You can use the ``:filter:`` option to imports only the needs which pass the filter criteria.
+This is a string that is evaluated as a Python expression,
+it is less performant than the ``:ids:`` option, but more flexible.
 
 Please read :ref:`filter` for more information.
 

sphinx_needs/directives/needimport.py

@@ -37,6 +37,7 @@ class NeedimportDirective(SphinxDirective):
         "version": directives.unchanged_required,
         "hide": directives.flag,
         "collapse": string_to_boolean,
+        "ids": directives.unchanged_required,
         "filter": directives.unchanged_required,
         "id_prefix": directives.unchanged_required,
         "tags": directives.unchanged_required,
@@ -56,10 +57,6 @@ def run(self) -> Sequence[nodes.Node]:
         filter_string = self.options.get("filter")
         id_prefix = self.options.get("id_prefix", "")
 
-        tags = self.options.get("tags", [])
-        if len(tags) > 0:
-            tags = [tag.strip() for tag in re.split("[;,]", tags)]
-
         need_import_path = self.arguments[0]
 
         # check if given arguemnt is downloadable needs.json path
@@ -146,6 +143,13 @@ def run(self) -> Sequence[nodes.Node]:
 
         needs_config = NeedsSphinxConfig(self.config)
         data = needs_import_list["versions"][version]
+
+        if ids := self.options.get("ids"):
+            id_list = [i.strip() for i in ids.split(",") if i.strip()]
+            data["needs"] = {
+                key: data["needs"][key] for key in id_list if key in data["needs"]
+            }
+
         # TODO this is not exactly NeedsInfoType, because the export removes/adds some keys
         needs_list: dict[str, NeedsInfoType] = data["needs"]
         if schema := data.get("needs_schema"):
@@ -206,8 +210,13 @@ def run(self) -> Sequence[nodes.Node]:
                     )
 
         # tags update
-        for need in needs_list.values():
-            need["tags"] = need["tags"] + tags
+        if tags := [
+            tag.strip()
+            for tag in re.split("[;,]", self.options.get("tags", ""))
+            if tag.strip()
+        ]:
+            for need in needs_list.values():
+                need["tags"] = need["tags"] + tags
 
         known_options = (
             "title",