specitems 1.7.0__tar.gz → 1.7.2__tar.gz

{specitems-1.7.0 → specitems-1.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specitems
-Version: 1.7.0
+Version: 1.7.2
 Summary: Provides interfaces to work with specification items.
 Keywords: certification,documentation,markdown,qualification,requirements-management,traceability
 Author: The specitems Authors

{specitems-1.7.0 → specitems-1.7.2}/pyproject.toml

@@ -4,7 +4,7 @@
 
 [project]
 name = "specitems"
-version = "1.7.0"
+version = "1.7.2"
 description = "Provides interfaces to work with specification items."
 authors = [
     {name = "The specitems Authors", email = "specthings@embedded-brains.de"}

{specitems-1.7.0 → specitems-1.7.2}/src/specitems/__init__.py

@@ -24,7 +24,8 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 
-from .cite import BibTeXCitationProvider
+from .cite import (BibTeXCitationProvider, get_reference_target,
+                   get_reference_work, make_anchor, ReferenceTarget)
 from .clangformat import ClangFormatter
 from .cliutil import (
     LoggingStatus,
@@ -144,9 +145,10 @@ from .itemmapper import (
 from .licenseinfo import (LicenseAggregate, LicenseEntry, LicenseProvider)
 from .spdx import (get_license_list_version, parse_license_expression,
                    parse_license_identifier, permits)
-from .specconfig import (CONFIG_FILE, CONFIG_UID, check_license_items,
-                         create_content_context, create_type_provider,
-                         find_config_file, load_config_item, yield_tasks)
+from .specconfig import (CONFIG_FILE, CONFIG_UID, add_inline_items,
+                         check_license_items, create_content_context,
+                         create_type_provider, find_config_file,
+                         load_config_item, yield_tasks)
 from .specdoc import (SpecDocumentConfig, add_specification_documentation,
                       generate_specification_documentation)
 from .specformatter import SpecYAMLFormatter
@@ -207,6 +209,7 @@ __all__ = [
     "MarkdownContent",
     "MarkdownMapper",
     "ROW_SPAN",
+    "ReferenceTarget",
     "SpecDocumentConfig",
     "SpecTypeProvider",
     "SpecVerifier",
@@ -216,6 +219,7 @@ __all__ = [
     "SubstitutionError",
     "TextContent",
     "TextMapper",
+    "add_inline_items",
     "add_license_arguments",
     "add_specification_documentation",
     "atomic_dump_to_file",
@@ -238,6 +242,8 @@ __all__ = [
     "get_item_cache_arguments",
     "get_license_list_version",
     "get_reference",
+    "get_reference_target",
+    "get_reference_work",
     "get_value_default",
     "get_value_plural",
     "get_value_subprocess",
@@ -258,6 +264,7 @@ __all__ = [
     "load_config_item",
     "load_data",
     "load_data_by_uid",
+    "make_anchor",
     "make_copyright_statement",
     "make_label",
     "make_lines",

{specitems-1.7.0 → specitems-1.7.2}/src/specitems/cite.py

@@ -24,9 +24,11 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 
-from typing import Callable
+import dataclasses
+import re
+from typing import Callable, Optional
 
-from .items import Item
+from .items import Item, Link
 from .itemmapper import ItemGetValueContext, ItemType, ItemValueProvider
 from .content import list_terms
 from .contenttext import TextContent, TextMapper, latex_escape
@@ -50,6 +52,79 @@ _DOUBLE_QUOTE = {
 
 _PERSONS = {"author", "editor"}
 
+_NOT_ID_CHARS = re.compile(r"[^a-z0-9]+")
+
+
+def make_anchor(label: str) -> str:
+    """
+    Make the anchor of the label in the way Sphinx makes the identifier of a
+    label target.
+    """
+    return _NOT_ID_CHARS.sub("-", label.lower()).strip("-")
+
+
+@dataclasses.dataclass
+class ReferenceTarget:
+    """ Represents the target of a reference link. """
+
+    # pylint: disable=too-many-instance-attributes
+
+    #: The referenced work.
+    work: Item
+
+    #: The name of the area within the work.
+    name: Optional[str]
+
+    #: The label of the area within the work.
+    label: Optional[str]
+
+    #: The location of the area within the work.
+    location: Optional[str]
+
+    #: The path of the area relative to the base URL of the work.
+    path: str
+
+    #: The URL of the area.  The caller substitutes it in the context of the
+    #: work.
+    url: Optional[str]
+
+
+def get_reference_work(item: Item) -> Item:
+    """
+    Get the referenced work of the reference or reference location item.
+    """
+    if item.type == "reference-location":
+        works = list(item.parents("reference-location"))
+        if len(works) != 1:
+            raise ValueError(f"{item.uid}: a reference location shall have "
+                             "exactly one link to the referenced work")
+        return works[0]
+    return item
+
+
+def get_reference_target(item: Item,
+                         link: Optional[Link] = None) -> ReferenceTarget:
+    """
+    Get the target of the reference or reference location item.
+
+    The attributes of the optional reference link take precedence over the
+    attributes of the reference location.  The paths of the reference location
+    and the reference link are concatenated.
+    """
+    work = get_reference_work(item)
+    link_data = {} if link is None else link.data
+    area = item.data if item is not work else {}
+    name = area.get("name")
+    label = link_data.get("label", area.get("label"))
+    location = link_data.get("location", area.get("location"))
+    path = f"{area.get('path', '')}{link_data.get('path', '')}"
+    base = work.get("work-base-url")
+    url: Optional[str] = None
+    if base is not None:
+        anchor = "" if label is None else f"#{make_anchor(label)}"
+        url = f"{base}{path}{anchor}"
+    return ReferenceTarget(work, name, label, location, path, url)
+
 
 def _get_fields(item: Item) -> tuple[str, _Fields]:
     _, _, publication_type = item.type.partition("/")
@@ -70,6 +145,10 @@ class BibTeXCitationProvider(ItemValueProvider):
         self._get_fields: dict[str, _GetFields] = {}
         mapper.add_get_value("reference:/cite", self._get_cite)
         mapper.add_get_value("reference:/cite-long", self._get_cite_long)
+        mapper.add_get_value("reference-location:/cite",
+                             self._get_cite_location)
+        mapper.add_get_value("reference-location:/cite-long",
+                             self._get_cite_long_location)
 
     def reset(self) -> None:
         self._citations.clear()
@@ -135,18 +214,37 @@ class BibTeXCitationProvider(ItemValueProvider):
                 content.append(f"  {field} = {{{value}}},")
             content.append("}")
 
-    def _get_cite(self, ctx: ItemGetValueContext) -> str:
-        self._citations.add(ctx.item)
+    def _cite(self, work: Item) -> str:
+        self._citations.add(work)
         assert isinstance(self.mapper, TextMapper)
         content = self.mapper.create_content()
-        return content.cite(ctx.item.ident)
+        return content.cite(work.ident)
 
-    def _get_cite_long(self, ctx: ItemGetValueContext) -> str:
-        self._citations.add(ctx.item)
-        _, fields = self.get_fields(ctx.item)
+    def _cite_long(self, ctx: ItemGetValueContext, work: Item,
+                   name: Optional[str]) -> str:
+        _, fields = self.get_fields(work)
         assert isinstance(self.mapper, TextMapper)
         content = self.mapper.create_content()
         title = fields["title"]
         assert isinstance(title, str)
-        title = content.emphasize(ctx.substitute_and_transform(title))
-        return f"{title} {content.cite(ctx.item.ident)}"
+        if work is ctx.item:
+            title = ctx.substitute(title)
+        else:
+            title = self.mapper.substitute_data(title, work)
+        title = content.emphasize(ctx.transform(title))
+        if name is not None:
+            title = f"{title}, {ctx.substitute_and_transform(name)}"
+        return f"{title} {self._cite(work)}"
+
+    def _get_cite(self, ctx: ItemGetValueContext) -> str:
+        return self._cite(ctx.item)
+
+    def _get_cite_long(self, ctx: ItemGetValueContext) -> str:
+        return self._cite_long(ctx, ctx.item, None)
+
+    def _get_cite_location(self, ctx: ItemGetValueContext) -> str:
+        return self._cite(get_reference_work(ctx.item))
+
+    def _get_cite_long_location(self, ctx: ItemGetValueContext) -> str:
+        return self._cite_long(ctx, get_reference_work(ctx.item),
+                               ctx.item.get("name"))

{specitems-1.7.0 → specitems-1.7.2}/src/specitems/specconfig.py

@@ -24,6 +24,7 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 
+import copy
 import logging
 from pathlib import Path
 from typing import Any, Iterator, Optional
@@ -31,8 +32,8 @@ from typing import Any, Iterator, Optional
 from .cliutil import load_config
 from .content import ContentContext
 from .licenseinfo import LicenseAggregate, LicenseProvider
-from .items import (EmptyItemCache, Item, ItemDataByUID, ItemTypeProvider,
-                    SpecTypeProvider)
+from .items import (EmptyItemCache, Item, ItemCache, ItemDataByUID,
+                    ItemTypeProvider, SpecTypeProvider)
 from .specverify import SpecVerifier
 
 #: The name of the configuration file of a tree.
@@ -204,6 +205,41 @@ def check_license_items(config: Item, provider: LicenseProvider) -> None:
         raise ValueError("\n".join(errors))
 
 
+def add_inline_items(config: Item, item_cache: ItemCache) -> None:
+    """
+    Add the inline items of the configuration to the item cache.
+
+    An inline item is part of the configuration file.  It takes the license
+    and the copyrights of the configuration item, unless it states its own.
+    An inline item without links gets an empty list of links.  An inline item
+    without an enabled-by attribute is enabled.  An inline item without a type
+    has the inline type.  An inline item may link to another inline item.
+
+    Args:
+        config: The configuration item.
+        item_cache: The item cache of the tree.
+
+    Raises:
+        ValueError: An inline item exists already in the item cache or in the
+            configuration.
+    """
+    data_by_uid: ItemDataByUID = {}
+    for entry in config.get("inline-items", []):
+        uid = entry["uid"]
+        if (uid in item_cache or uid in item_cache.proxies
+                or uid in data_by_uid):
+            raise ValueError(f"the inline item {uid} exists already")
+        data = copy.deepcopy(entry["data"])
+        for key, value in (("SPDX-License-Identifier",
+                            config["SPDX-License-Identifier"]),
+                           ("copyrights", config["copyrights"]),
+                           ("enabled-by", True), ("links", []), ("type",
+                                                                 "inline")):
+            data.setdefault(key, copy.deepcopy(value))
+        data_by_uid[uid] = data
+    item_cache.add_items(data_by_uid)
+
+
 def yield_tasks(config: Item, task_type: str) -> Iterator[dict]:
     """
     Yield the tasks of the type in the order of the configuration.

{specitems-1.7.0 → specitems-1.7.2}/src/specitems/items.py

@@ -1215,11 +1215,11 @@ class ItemCache(dict):
                 data_by_uid.update(
                     load_data_by_uid(path, self._cache_directory, uid_prefix,
                                      the_format))
-        self.add_items(data_by_uid, config.initialize_links, False)
         if type_provider is None:
             type_provider = ItemTypeProvider(data_by_uid,
                                              config.spec_type_root_uid)
         self.type_provider = type_provider
+        self.add_items(data_by_uid, config.initialize_links, False)
         for item in self.values():
             self.type_provider.set_type(item)