specitems 1.1.1__tar.gz

specitems-1.1.1/PKG-INFO

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: specitems
+Version: 1.1.1
+Summary: Provides interfaces to work with specification items.
+Keywords: certification,documentation,markdown,qualification,requirements-management,traceability
+Author: The specitems Authors
+Author-email: The specitems Authors <specthings@embedded-brains.de>
+License-Expression: BSD-2-Clause
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Typing :: Typed
+Requires-Dist: mdformat>=0.7.22
+Requires-Dist: mdformat-deflist>=0.1.3
+Requires-Dist: mdformat-footnote>=0.1.3
+Requires-Dist: mdformat-frontmatter>=2.0.10
+Requires-Dist: mdformat-myst>=0.3.0
+Requires-Dist: mdformat-tables>=1.0.0
+Requires-Dist: pyyaml>=6.0.3
+Requires-Python: >=3.11
+Project-URL: Source Code, https://github.com/specthings/specitems
+Project-URL: Bug Tracker, https://github.com/specthings/specitems/issues
+Description-Content-Type: text/markdown
+
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+
+Copyright (C) 2026 embedded brains GmbH & Co. KG
+-->
+## Overview
+
+The *specitems* Python package provides interfaces to work with specification
+items.  Specifications are written in specification items which may contain
+dictionaries, lists, integers, floating-point numbers, and strings.  The format
+of these items is extensible, human readable, machine readable, Git friendly,
+and can be customized according to domain-specific needs.  The items are
+connected through links which may contain role-specific extra information.
+This enables different views to a specification item graph depending on the use
+case.
+
+The package is maintained by the
+[specthings](https://github.com/specthings)
+project.  Users of the package are
+[specware](https://github.com/specthings/specitems)
+and
+[specbuild](https://github.com/specthings/specbuild).
+
+## Contributing
+
+Please refer to our
+[Contributing Guidelines](https://github.com/specthings/specitems/blob/main/CONTRIBUTING.md).

specitems-1.1.1/README.md

@@ -0,0 +1,27 @@
+<!--
+SPDX-License-Identifier: CC-BY-SA-4.0
+
+Copyright (C) 2026 embedded brains GmbH & Co. KG
+-->
+## Overview
+
+The *specitems* Python package provides interfaces to work with specification
+items.  Specifications are written in specification items which may contain
+dictionaries, lists, integers, floating-point numbers, and strings.  The format
+of these items is extensible, human readable, machine readable, Git friendly,
+and can be customized according to domain-specific needs.  The items are
+connected through links which may contain role-specific extra information.
+This enables different views to a specification item graph depending on the use
+case.
+
+The package is maintained by the
+[specthings](https://github.com/specthings)
+project.  Users of the package are
+[specware](https://github.com/specthings/specitems)
+and
+[specbuild](https://github.com/specthings/specbuild).
+
+## Contributing
+
+Please refer to our
+[Contributing Guidelines](https://github.com/specthings/specitems/blob/main/CONTRIBUTING.md).

specitems-1.1.1/pyproject.toml

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: BSD-2-Clause
+
+# Copyright (C) 2026 embedded brains GmbH & Co. KG
+
+[project]
+name = "specitems"
+version = "1.1.1"
+description = "Provides interfaces to work with specification items."
+authors = [
+    {name = "The specitems Authors", email = "specthings@embedded-brains.de"}
+]
+license = "BSD-2-Clause"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "mdformat>=0.7.22",
+    "mdformat-deflist>=0.1.3",
+    "mdformat-footnote>=0.1.3",
+    "mdformat-frontmatter>=2.0.10",
+    "mdformat-myst>=0.3.0",
+    "mdformat-tables>=1.0.0",
+    "pyyaml>=6.0.3",
+]
+keywords = [
+  "certification",
+  "documentation",
+  "markdown",
+  "qualification",
+  "requirements-management",
+  "traceability",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Text Processing :: Markup",
+    "Typing :: Typed",
+]
+
+[project.urls]
+"Source Code" = "https://github.com/specthings/specitems"
+"Bug Tracker" = "https://github.com/specthings/specitems/issues"
+
+[project.scripts]
+specpickle = "specitems.clipickle:clipickle"
+specdocitems = "specitems.clispecdoc:clispecdocitems"
+spechash = "specitems.clihash:clihash"
+specyamlquery = "specitems.cliyamlquery:cliyamlquery"
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "coverage>=7.13.3",
+    "flake8>=7.3.0",
+    "mypy>=1.19.1",
+    "pylint>=4.0.4",
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "sphinx>=9.0.4",
+    "sphinx-autodoc-napoleon-typehints>=2.1.6",
+    "sphinx-autodoc-typehints>=3.6.1",
+    "sphinx-rtd-theme>=3.1.0",
+    "types-pyyaml>=6.0.12.20250915",
+    "yapf>=0.43.0",
+]
+
+[tool.pytest.ini_options]
+addopts = "--cov=specitems --cov-fail-under=100 --cov-branch --cov-report=term-missing"

specitems-1.1.1/src/specitems/__init__.py

@@ -0,0 +1,218 @@
+# SPDX-License-Identifier: BSD-2-Clause
+""" The specitems package. """
+
+# Copyright (C) 2019, 2026 embedded brains GmbH & Co. KG
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# 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 .cliutil import (
+    create_argument_parser,
+    create_config,
+    init_logging,
+    load_config,
+)
+from .content import (
+    Content,
+    ContentAddContext,
+    Copyright,
+    Copyrights,
+    GenericContent,
+    GenericContentIterable,
+    MARKDOWN_ROLES,
+    get_value_plural,
+    list_terms,
+    make_copyright_statement,
+    split_copyright_statement,
+    to_camel_case,
+)
+from .contenttext import (
+    TextContent,
+    TextMapper,
+    latex_escape,
+    make_label,
+)
+from .contentmarkdown import (
+    MarkdownContent,
+    MarkdownMapper,
+)
+from .contentsphinx import (
+    SphinxContent,
+    SphinxMapper,
+    escape_code_line,
+    get_reference,
+)
+from .getvaluesubprocess import get_value_subprocess
+from .glossary import (
+    DocumentGlossaryConfig,
+    GlossaryConfig,
+    augment_glossary_terms,
+    generate_glossary,
+)
+from .hashutil import (
+    base64_to_hex,
+    base64_to_hex_text,
+    hash_file,
+    hash_file_lines,
+    hash_file_lines_md5,
+    hash_file_lines_sha256,
+    hash_file_md5,
+    hash_file_sha256,
+)
+from .items import (
+    EmptyItem,
+    EmptyItemCache,
+    EnabledSet,
+    IS_ENABLED_OPS,
+    IsEnabled,
+    IsLinkEnabled,
+    Item,
+    ItemCache,
+    ItemCacheConfig,
+    ItemDataByUID,
+    ItemSelection,
+    ItemType,
+    ItemTypeProvider,
+    ItemView,
+    ItemViewGetMissing,
+    JSONItemCache,
+    Link,
+    SpecTypeProvider,
+    create_unique_link,
+    data_digest,
+    is_enabled,
+    is_enabled_with_ops,
+    item_is_enabled,
+    link_is_enabled,
+    load_data,
+    load_data_by_uid,
+    pickle_load_data_by_uid,
+    save_data,
+    to_collection,
+    to_iterable,
+)
+from .itemmapper import (
+    ItemGetValue,
+    ItemGetValueContext,
+    ItemGetValueMap,
+    ItemMapper,
+    ItemValueProvider,
+    get_value_default,
+    unpack_arg,
+)
+from .specdoc import SpecDocumentConfig, generate_specification_documentation
+from .specverify import (
+    SpecVerifier,
+    VerifyStatus,
+    verify_specification_format,
+)
+from .subprocessaction import (
+    make_subprocess_environment,
+    run_subprocess_action,
+)
+
+__all__ = [
+    "BibTeXCitationProvider",
+    "Content",
+    "ContentAddContext",
+    "Copyright",
+    "Copyrights",
+    "DocumentGlossaryConfig",
+    "EmptyItem",
+    "EmptyItemCache",
+    "EnabledSet",
+    "GenericContent",
+    "GenericContentIterable",
+    "GlossaryConfig",
+    "IS_ENABLED_OPS",
+    "IsEnabled",
+    "IsLinkEnabled",
+    "Item",
+    "ItemCache",
+    "ItemCacheConfig",
+    "ItemDataByUID",
+    "ItemGetValue",
+    "ItemGetValueContext",
+    "ItemGetValueMap",
+    "ItemMapper",
+    "ItemSelection",
+    "ItemType",
+    "ItemTypeProvider",
+    "ItemValueProvider",
+    "ItemView",
+    "ItemViewGetMissing",
+    "JSONItemCache",
+    "Link",
+    "MARKDOWN_ROLES",
+    "MarkdownContent",
+    "MarkdownMapper",
+    "SpecDocumentConfig",
+    "SpecTypeProvider",
+    "SpecVerifier",
+    "SphinxContent",
+    "SphinxMapper",
+    "TextContent",
+    "TextMapper",
+    "VerifyStatus",
+    "augment_glossary_terms",
+    "base64_to_hex",
+    "base64_to_hex_text",
+    "create_argument_parser",
+    "create_config",
+    "create_unique_link",
+    "data_digest",
+    "escape_code_line",
+    "generate_glossary",
+    "generate_specification_documentation",
+    "get_reference",
+    "get_value_default",
+    "get_value_plural",
+    "get_value_subprocess",
+    "hash_file",
+    "hash_file_lines",
+    "hash_file_lines_md5",
+    "hash_file_lines_sha256",
+    "hash_file_md5",
+    "hash_file_sha256",
+    "init_logging",
+    "is_enabled",
+    "is_enabled_with_ops",
+    "item_is_enabled",
+    "latex_escape",
+    "link_is_enabled",
+    "list_terms",
+    "load_config",
+    "load_data",
+    "load_data_by_uid",
+    "make_copyright_statement",
+    "make_label",
+    "make_subprocess_environment",
+    "pickle_load_data_by_uid",
+    "run_subprocess_action",
+    "save_data",
+    "split_copyright_statement",
+    "to_camel_case",
+    "to_collection",
+    "to_iterable",
+    "unpack_arg",
+    "verify_specification_format",
+]

specitems-1.1.1/src/specitems/cite.py

@@ -0,0 +1,149 @@
+# SPDX-License-Identifier: BSD-2-Clause
+""" Provides an item value provider for citations. """
+
+# Copyright (C) 2025, 2026 embedded brains GmbH & Co. KG
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+from typing import Callable
+
+from .items import Item
+from .itemmapper import ItemGetValueContext, ItemType, ItemValueProvider
+from .content import list_terms
+from .contenttext import TextContent, TextMapper, latex_escape
+
+_Fields = dict[str, str | list[str]]
+_GetFields = Callable[[Item], tuple[str, _Fields]]
+
+_FIELDS = {
+    "author", "booktitle", "chapter", "doi", "edition", "editor",
+    "howpublished", "institution", "journal", "month", "note", "number",
+    "organization", "pages", "publisher", "school", "series", "title",
+    "volume", "year"
+}
+
+_NO_LATEX_ESCAPE = {"url"}
+
+_DOUBLE_QUOTE = {
+    "author", "booktitle", "editor", "howpublished", "institution",
+    "organization", "publisher", "school", "title"
+}
+
+_PERSONS = {"author", "editor"}
+
+
+def _get_fields(item: Item) -> tuple[str, _Fields]:
+    _, _, publication_type = item.type.partition("/")
+    fields: _Fields = dict(
+        (key, item[key]) for key in _FIELDS.intersection(item.data.keys()))
+    url = item.get("work-url", None)
+    if url is not None:
+        fields["url"] = url
+    return publication_type, fields
+
+
+class BibTeXCitationProvider(ItemValueProvider):
+    """ Provides citation values and BibTeX entries. """
+
+    def __init__(self, mapper: TextMapper) -> None:
+        super().__init__(mapper)
+        self._citations: set[Item] = set()
+        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)
+
+    def reset(self) -> None:
+        self._citations.clear()
+
+    def get_cite_group(self, ctx: ItemGetValueContext) -> str:
+        """
+        Get the citations associated with the citation group key provided by
+        the arguments of the context.
+        """
+        citations: list[str] = []
+        for link in ctx.item.links_to_children("citation-group-member"):
+            if link["citation-group-key"] == ctx.args:
+                citations.append(f"${{{link.uid}:/cite}}")
+        return ctx.substitute(list_terms(citations))
+
+    def get_bibtex_entries(self, ctx: ItemGetValueContext) -> str:
+        """ Get the BibTeX entries for the collected citations. """
+        mapper = ctx.mapper
+        assert isinstance(mapper, TextMapper)
+        content = mapper.create_content()
+        self.add_bibtex_entries(content)
+        return content.join()
+
+    def _add_get_fields_for_subtypes(self, spec_type: ItemType, type_path: str,
+                                     get_fields: _GetFields) -> None:
+        if spec_type.refinements:
+            for key, refinement in spec_type.refinements.items():
+                self._add_get_fields_for_subtypes(refinement,
+                                                  f"{type_path}/{key}",
+                                                  get_fields)
+        else:
+            self._get_fields[type_path] = get_fields
+
+    def add_get_fields(self, item_type: str, get_fields: _GetFields) -> None:
+        """ Add the get fields method for the item type. """
+        self.mapper.add_get_value(f"{item_type}:/cite", self._get_cite)
+        self.mapper.add_get_value(f"{item_type}:/cite-long",
+                                  self._get_cite_long)
+        spec_type = self.mapper.item.cache.type_provider.root_type
+        for name in item_type.split("/"):
+            spec_type = spec_type.refinements[name]
+        self._add_get_fields_for_subtypes(spec_type, item_type, get_fields)
+
+    def add_bibtex_entries(self, content: TextContent) -> None:
+        """ Add BibTeX entries for the collected citations to the content. """
+        for item in sorted(self._citations):
+            publication_type, fields = self._get_fields.get(
+                item.type, _get_fields)(item)
+            for key in _PERSONS.intersection(fields.keys()):
+                if isinstance(fields[key], list):
+                    fields[key] = " and ".join(fields[key])
+            content.append(f"@{publication_type}{{{item.ident},")
+            for field, value in sorted(fields.items()):
+                assert isinstance(value, str)
+                value = self.mapper.substitute(value)
+                if field not in _NO_LATEX_ESCAPE:
+                    value = latex_escape(value)
+                if field in _DOUBLE_QUOTE:
+                    value = f"{{{value}}}"
+                content.append(f"  {field} = {{{value}}},")
+            content.append("}")
+
+    def _get_cite(self, ctx: ItemGetValueContext) -> str:
+        self._citations.add(ctx.item)
+        assert isinstance(self.mapper, TextMapper)
+        content = self.mapper.create_content()
+        return content.cite(ctx.item.ident)
+
+    def _get_cite_long(self, ctx: ItemGetValueContext) -> str:
+        self._citations.add(ctx.item)
+        _, fields = self._get_fields.get(ctx.item.type, _get_fields)(ctx.item)
+        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)}"

specitems-1.1.1/src/specitems/clihash.py

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: BSD-2-Clause
+""" Provides a command line interface to hash a list of files. """
+
+# Copyright (C) 2023, 2026 embedded brains GmbH & Co. KG
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+import argparse
+import sys
+
+from .hashutil import (base64_to_hex, hash_file, hash_file_lines,
+                       hash_file_md5, hash_file_lines_md5, hash_file_sha256,
+                       hash_file_lines_sha256)
+
+_HASH_FILE = {
+    "MD5": hash_file_md5,
+    "SHA256": hash_file_sha256,
+    "SHA512": hash_file
+}
+
+_HASH_FILE_LINES = {
+    "MD5": hash_file_lines_md5,
+    "SHA256": hash_file_lines_sha256,
+    "SHA512": hash_file_lines
+}
+
+
+def _identity(digest: str) -> str:
+    return digest
+
+
+_FORMATTER = {"base64url": _identity, "hex": base64_to_hex}
+
+
+def clihash(argv: list[str] = sys.argv) -> None:
+    """ Hash the list of files. """
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--algorithm',
+                        choices=["MD5", "SHA256", "SHA512"],
+                        type=str.upper,
+                        default="SHA512",
+                        help="hash algorithm (default: SHA512)")
+    parser.add_argument('--format',
+                        choices=["base64url", "hex"],
+                        type=str.lower,
+                        default="base64url",
+                        help="digest format (default: base64url)")
+    parser.add_argument('--line',
+                        action="append",
+                        default=None,
+                        help=("hash line B (format: B) or lines "
+                              "from B to E excluding E (format B:E); "
+                              "the line numbering starts with one"))
+    parser.add_argument("files",
+                        metavar="FILES",
+                        nargs="+",
+                        help="the files to hash")
+    args = parser.parse_args(argv[1:])
+    formatter = _FORMATTER[args.format]
+    if args.line:
+        lines: list[tuple[int, int]] = []
+        do_hash_file_lines = _HASH_FILE_LINES[args.algorithm]
+        for line in args.line:
+            begin, _, end = line.partition(":")
+            if not end:
+                end = int(begin) + 1
+            lines.append((int(begin), int(end)))
+        for path in args.files:
+            print(path, formatter(do_hash_file_lines(path, lines)))
+    else:
+        do_hash_file = _HASH_FILE[args.algorithm]
+        for path in args.files:
+            print(path, formatter(do_hash_file(path)))

specitems-1.1.1/src/specitems/clipickle.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: BSD-2-Clause
+"""
+Provides a command line interface to convert specification items inside
+specification directories to a pickle data file.
+"""
+
+# Copyright (C) 2025 embedded brains GmbH & Co. KG
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+import argparse
+import os
+import pickle
+import sys
+
+from .items import ItemCache, ItemCacheConfig
+
+
+def _filter(data: dict) -> dict:
+    return dict((key, value) for key, value in sorted(data.items())
+                if not key.startswith("_"))
+
+
+def clipickle(argv: list[str] = sys.argv) -> None:
+    """
+    Convert specification items inside specification directories to a pickle
+    data file.
+    """
+
+    parser = argparse.ArgumentParser()
+    parser.add_argument("specdirs",
+                        metavar="SPECIFICATION_DIRECTORIES",
+                        nargs="+",
+                        help="a non-empty list of specification directories")
+    parser.add_argument("pickle",
+                        metavar="PICKLE",
+                        nargs=1,
+                        help="the pickle file to generate")
+    args = parser.parse_args(argv[1:])
+    config = ItemCacheConfig(paths=args.specdirs, initialize_links=False)
+    item_cache = ItemCache(config)
+    data = dict(
+        (uid, _filter(item.data)) for uid, item in sorted(item_cache.items()))
+    pickle_file = args.pickle[0]
+    os.makedirs(os.path.dirname(pickle_file), exist_ok=True)
+    with open(pickle_file, "wb") as out:
+        pickle.dump(data, out)