python-sbom 0.1.1__py3-none-any.whl

python_sbom/_model/_iri.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import ipaddress
+import re
+import string
+from typing import Final, cast
+from urllib.parse import quote
+
+# RFC 3986 appendix B: splits any text into scheme, authority, path, query and fragment
+_PARTS: Final[re.Pattern[str]] = re.compile(
+    r"(?:([^:/?#]+):)?(?://([^/?#]*))?([^?#]*)(?:\?([^#]*))?(?:#(.*))?", re.DOTALL
+)
+_SCHEME: Final[re.Pattern[str]] = re.compile(r"[A-Za-z][A-Za-z0-9+.-]*")
+# what may follow the host: nothing, or a colon and the port's digits
+_PORT: Final[re.Pattern[str]] = re.compile(r"(?::[0-9]*)?")
+_IP_FUTURE: Final[re.Pattern[str]] = re.compile(r"v[0-9A-Fa-f]+\.[A-Za-z0-9._~!$&'()*+,;=:-]+")
+# a valid percent-encoding, or any one character
+_TOKEN: Final[re.Pattern[str]] = re.compile(r"%[0-9A-Fa-f]{2}|.", re.DOTALL)
+_REG_NAME: Final[str] = f"{string.ascii_letters}{string.digits}-._~!$&'()*+,;="
+_USERINFO: Final[str] = f"{_REG_NAME}:"
+_PATH: Final[str] = f"{_USERINFO}@/"
+# the query and the fragment allow the same characters
+_QUERY: Final[str] = f"{_PATH}?"
+# the characters beyond ASCII an IRI holds unencoded, RFC 3987's ucschar
+_UCSCHAR: Final[tuple[tuple[int, int], ...]] = (
+    (0xA0, 0xD7FF),
+    (0xF900, 0xFDCF),
+    (0xFDF0, 0xFFEF),
+    *((plane << 16, plane << 16 | 0xFFFD) for plane in range(1, 14)),
+    (0xE1000, 0xEFFFD),
+)
+
+
+def iri_reference(text: str) -> str | None:
+    # the form CycloneDX requires of a URL: a character no part of an IRI reference allows is percent-encoded, which
+    # keeps what the text points at; a scheme, IP literal or port no encoding mends, as in the scp-style
+    # git@github.com:org/repo.git, leaves None; the pattern matches any text, every part of it optional
+    match: Final = cast("re.Match[str]", _PARTS.fullmatch(text))
+    scheme, authority, path, query, fragment = match.groups()
+    if scheme is not None and not _SCHEME.fullmatch(scheme):
+        return None
+    parts: Final[list[str]] = [] if scheme is None else [f"{scheme}:"]
+    if authority is not None:
+        if (encoded := _authority(authority)) is None:
+            return None
+        parts.append(f"//{encoded}")
+    parts.append(_encoded(path, _PATH))
+    if query is not None:
+        parts.append(f"?{_encoded(query, _QUERY)}")
+    if fragment is not None:
+        parts.append(f"#{_encoded(fragment, _QUERY)}")
+    return "".join(parts)
+
+
+def _authority(authority: str) -> str | None:
+    userinfo, at, host_port = authority.rpartition("@")
+    if host_port.startswith("["):
+        literal, _, port = host_port[1:].partition("]")
+        if not _ip_literal(literal):
+            return None
+        host = f"[{literal}]"
+    else:
+        name, colon, number = host_port.partition(":")
+        host, port = _encoded(name, _REG_NAME), f"{colon}{number}"
+    if not _PORT.fullmatch(port):
+        return None
+    return f"{_encoded(userinfo, _USERINFO)}{at}{host}{port}"
+
+
+def _ip_literal(literal: str) -> bool:
+    if _IP_FUTURE.fullmatch(literal):
+        return True
+    # a zone index has no place in a URI's IP literal
+    if "%" in literal:
+        return False
+    try:
+        ipaddress.IPv6Address(literal)
+    except ValueError:
+        return False
+    return True
+
+
+def _encoded(text: str, allowed: str) -> str:
+    return "".join(token if _kept(token, allowed) else quote(token, safe="") for token in _TOKEN.findall(text))
+
+
+def _kept(token: str, allowed: str) -> bool:
+    # a token longer than a character is a valid percent-encoding
+    if len(token) > 1 or token in allowed:
+        return True
+    return any(low <= ord(token) <= high for low, high in _UCSCHAR)
+
+
+__all__ = [
+    "iri_reference",
+]

python_sbom/_model/_licenses.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Final
+
+from packaging.licenses import InvalidLicenseExpression, canonicalize_license_expression
+
+if TYPE_CHECKING:
+    from ._metadata import CoreMetadata
+    from ._types import License
+
+
+def licenses(metadata: CoreMetadata) -> list[License]:
+    # a License-Expression is taken as declared; otherwise each License field and License classifier name is declared,
+    # and the SPDX ids they map to are added as concluded
+    if expression := metadata.first("license_expression"):
+        try:
+            return [{"expression": canonicalize_license_expression(expression), "acknowledgement": "declared"}]
+        except InvalidLicenseExpression:
+            # an expression SPDX rejects, such as "MIT WITH GPL-3.0-only", stays as the name the metadata gives
+            return [{"license": {"name": expression, "acknowledgement": "declared"}}]
+    names = [entry.rsplit(" :: ", 1)[-1] for entry in metadata.values("classifiers") if entry.startswith("License :: ")]
+    if (declared := metadata.first("license")) and "\n" not in declared:
+        names.append(declared)
+    found: Final[list[License]] = [{"license": {"name": name, "acknowledgement": "declared"}} for name in names]
+    # a license policy judges SPDX ids only, so the names stay bare when any one of them does not resolve, and the
+    # policy reports that instead of judging a partial set
+    identifiers = [identifier for name in names if (identifier := _spdx_license(name)) is not None]
+    if len(identifiers) == len(names):
+        found.extend(
+            {"license": {"id": identifier, "acknowledgement": "concluded"}} for identifier in dict.fromkeys(identifiers)
+        )
+    return found
+
+
+def _spdx_license(name: str) -> str | None:
+    # only the license classifiers that name exactly one SPDX license; "BSD License" or "Apache Software License" leave
+    # the version or variant open
+    if identifier := {
+        "ISC License (ISCL)": "ISC",
+        "MIT License": "MIT",
+        "MIT No Attribution License (MIT-0)": "MIT-0",
+        "Mozilla Public License 2.0 (MPL 2.0)": "MPL-2.0",
+        "Python Software Foundation License": "PSF-2.0",
+        "The Unlicense (Unlicense)": "Unlicense",
+    }.get(name):
+        return identifier
+    try:
+        canonical = canonicalize_license_expression(name)
+    except InvalidLicenseExpression:
+        return None
+    # a CycloneDX license id holds one entry of the SPDX license list, never an expression or a LicenseRef
+    return canonical if re.fullmatch(r"[A-Za-z0-9.-]+", canonical) and not canonical.startswith("LicenseRef-") else None
+
+
+__all__ = [
+    "licenses",
+]

python_sbom/_model/_markers.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final
+
+from packaging.markers import Marker, UndefinedComparison
+
+if TYPE_CHECKING:
+    from packaging._parser import MarkerAtom, MarkerList  # see _extra_verdict
+    from packaging.requirements import Requirement
+
+
+def applies_without_extras(requirement: Requirement) -> bool:
+    # the conditions on extra are decided with no extra requested and every other condition stays unknown, so the
+    # requirement applies unless its extra conditions alone rule it out; dep-logic reduces markers the same way, but it
+    # rejects extra comparisons other than == and != through assert, which python -O strips, and on import it replaces
+    # packaging's marker grammar for the whole build process
+    if requirement.marker is None:
+        return True
+    try:
+        verdict = _extra_verdict(requirement.marker._markers)  # ruff: ignore[private-member-access] # see _extra_verdict
+    # packaging keeps the parsed tree private, so a release that moves or renames it leaves the requirement listed
+    # rather than dropping one that applies
+    except (AttributeError, ImportError):
+        return True
+    return verdict is not False
+
+
+def _extra_verdict(markers: MarkerList | MarkerAtom) -> bool | None:
+    from packaging._parser import Op, Value, Variable  # ruff: ignore[import-private-name, import-outside-top-level] # packaging keeps the marker tree private, the caller handles its absence
+
+    # three-valued, with "and" binding tighter than "or", as packaging's own evaluation groups them
+    groups: list[list[bool | None]] = [[]]
+    for item in markers:
+        if item == "or":
+            groups.append([])
+        elif isinstance(item, list):
+            groups[-1].append(_extra_verdict(item))
+        elif isinstance(item, tuple):
+            match item:
+                case Variable(value="extra"), Op(value=operator), Value(value=value):
+                    groups[-1].append(_no_extra_verdict(f"extra {operator} {value!r}"))
+                case Value(value=value), Op(value=operator), Variable(value="extra"):
+                    groups[-1].append(_no_extra_verdict(f"{value!r} {operator} extra"))
+                case _:
+                    groups[-1].append(None)
+    # ranked False < unknown < True: "and" takes the lowest verdict of a group, "or" the highest of the groups
+    verdicts: Final[tuple[bool | None, ...]] = (False, None, True)
+    return verdicts[max(min(map(verdicts.index, group), default=2) for group in groups)]
+
+
+def _no_extra_verdict(condition: str) -> bool | None:
+    try:
+        return Marker(condition).evaluate({"extra": ""})
+    # extra compared as a version, such as extra ~= "1.0", has no answer, so it stays unknown
+    except UndefinedComparison:
+        return None
+
+
+__all__ = [
+    "applies_without_extras",
+]

python_sbom/_model/_metadata.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from email.parser import HeaderParser
+from email.policy import compat32
+from typing import TYPE_CHECKING, Final, Literal, TypeAlias
+
+from packaging.metadata import parse_email
+
+if TYPE_CHECKING:
+    from packaging.metadata import RawMetadata
+
+# the fields python-sbom reads, by their key in packaging's RawMetadata
+Field: TypeAlias = Literal[
+    "author",
+    "author_email",
+    "classifiers",
+    "home_page",
+    "license",
+    "license_expression",
+    "license_files",
+    "maintainer",
+    "maintainer_email",
+    "name",
+    "provides_extra",
+    "requires_dist",
+    "requires_python",
+    "summary",
+    "version",
+]
+
+# the empty line that ends the headers, as the email parser ends them; a line of whitespace continues a header
+_BODY: Final[re.Pattern[str]] = re.compile(r"^\r?\n", re.MULTILINE)
+# unparsed keys a field by its header name, lowercased, which is the RawMetadata key with dashes except for these
+_HEADERS: Final[dict[str, str]] = {"classifiers": "classifier", "license_files": "license-file"}
+
+
+def parse_metadata(text: str) -> CoreMetadata:
+    # not validated: the SBOM describes a distribution whose metadata breaks the specification as well, as written; the
+    # body holds the long description, which nothing reads, and parsing it took most of the time
+    headers: Final = text[: match.start()] if (match := _BODY.search(text)) else text
+    raw, unparsed = parse_email(headers)
+    return CoreMetadata(raw=raw, unparsed=unparsed, headers=headers)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CoreMetadata:
+    raw: RawMetadata
+    unparsed: dict[str, list[str]]
+    # the header block as written, for the values packaging reshapes
+    headers: str = ""
+
+    @property
+    def name(self) -> str:
+        return self.first("name") or ""
+
+    def first(self, field: Field) -> str | None:
+        return next(iter(self.values(field)), None)
+
+    def values(self, field: Field) -> list[str]:
+        # packaging keeps a field it cannot take as declared, such as a single-use field given twice, out of raw and its
+        # values as written in unparsed, from where they are still described
+        match self.raw.get(field):
+            case str() as value:
+                return [value]
+            case list() as values:
+                return values
+        return self.unparsed.get(_HEADERS.get(field, field.replace("_", "-")), [])
+
+    @property
+    def version(self) -> str:
+        return self.first("version") or ""
+
+    def keywords(self) -> list[str]:
+        # packaging splits Keywords at commas and strips each keyword, so the header is read again, as the distribution
+        # wrote it, only when one is there; packaging parses the block with the same policy
+        if "keywords" in self.raw:
+            return HeaderParser(policy=compat32).parsestr(self.headers).get_all("keywords", [])
+        return self.unparsed.get("keywords", [])
+
+    def project_urls(self) -> list[tuple[str, str]]:
+        # a label given twice sends every Project-URL to unparsed, where each splits at its first comma as packaging
+        # splits them; an entry without a URL names nothing to reference
+        pairs: Final[list[tuple[str, str]]] = (
+            list(self.raw["project_urls"].items())
+            if "project_urls" in self.raw
+            else [
+                (label.strip(), url.strip())
+                for label, _, url in (entry.partition(",") for entry in self.unparsed.get("project-url", []))
+            ]
+        )
+        return [(label, url) for label, url in pairs if url]
+
+
+__all__ = [
+    "CoreMetadata",
+    "Field",
+    "parse_metadata",
+]

python_sbom/_model/_names.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import re
+from typing import Final
+
+from packageurl import PackageURL
+from packaging.utils import canonicalize_name
+
+#: the metadata property in which a document names its own file; validation checks such documents in full
+SBOM_FILE: Final[str] = "sbom:file"
+#: the metadata property in which a document names the project's repository
+SBOM_REPOSITORY: Final[str] = "sbom:repository"
+# the label normalization and mapping cyclonedx-py applies to Project-URL entries, so the same metadata yields the same
+# reference types whichever generator produced the document, plus the well-known labels of PEP 753 it lacks; funding
+# labels have no CycloneDX type and fall to "other"
+_URL_LABEL_TO_REFERENCE_TYPE: Final[dict[str, str]] = {
+    "bugtracker": "issue-tracker",
+    "issuetracker": "issue-tracker",
+    "issues": "issue-tracker",
+    "issue": "issue-tracker",
+    "bugs": "issue-tracker",
+    "bugreports": "issue-tracker",
+    "tracker": "issue-tracker",
+    "home": "website",
+    "homepage": "website",
+    "download": "distribution",
+    "documentation": "documentation",
+    "docs": "documentation",
+    "changelog": "release-notes",
+    "changes": "release-notes",
+    "whatsnew": "release-notes",
+    "history": "release-notes",
+    "releasenotes": "release-notes",
+    "source": "vcs",
+    "sourcecode": "vcs",
+    "repository": "vcs",
+    "github": "vcs",
+    "chat": "chat",
+}
+
+
+def sbom_property(project: str, key: str) -> str:
+    return f"{project}:{key}"
+
+
+def sbom_file_name(name: str) -> str:
+    return f"{property_prefix(name)}.cdx.json"
+
+
+def property_prefix(name: str) -> str:
+    # the normalized project name, which prefixes the properties this package writes
+    return canonicalize_name(name)
+
+
+def archive_sbom_file_name(archive: str) -> str:
+    # next to the archive, and inside it when embedded, where reading the archive again must skip it
+    return f"{archive}.cdx.json"
+
+
+def purl(name: str, version: str | None = None) -> str:
+    # normalized as PEP 503 does, so every spelling of a project, jaraco.context or jaraco_context, gets one purl and a
+    # component's bom-ref agrees with its purl; packageurl only lowercases and turns underscores into dashes
+    return PackageURL(type="pypi", name=canonicalize_name(name), version=version).to_string()
+
+
+def pypi_url(name: str, version: str | None = None) -> str:
+    return f"https://pypi.org/project/{name}/{version}/" if version else f"https://pypi.org/project/{name}/"
+
+
+def tool_ref(ref: str) -> str:
+    # prefixed because the same distribution can be both a build tool and a component of the artifact
+    return f"tool:{ref}"
+
+
+def reference_type(label: str) -> str:
+    return _URL_LABEL_TO_REFERENCE_TYPE.get(re.sub(r"[^a-z]", "", label.lower()), "other")
+
+
+__all__ = [
+    "SBOM_FILE",
+    "SBOM_REPOSITORY",
+    "archive_sbom_file_name",
+    "property_prefix",
+    "purl",
+    "pypi_url",
+    "reference_type",
+    "sbom_file_name",
+    "sbom_property",
+    "tool_ref",
+]

python_sbom/_model/_tools.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final
+
+from packageurl import PackageURL
+
+from ._components import component_from_metadata, file_component
+from ._names import purl, tool_ref
+
+if TYPE_CHECKING:
+    from ._inputs import BuildFacts
+    from ._types import Component, Dependency
+
+
+def tool_components(facts: BuildFacts) -> tuple[list[Component], list[Dependency]]:
+    interpreter = facts.interpreter
+    package = PackageURL(type="generic", name=interpreter.name, version=interpreter.version).to_string()
+    tools: Final[list[Component]] = [
+        {
+            "type": "platform",
+            "bom-ref": tool_ref(package),
+            "name": interpreter.name,
+            "version": interpreter.version,
+            "purl": package,
+            "properties": [{"name": "python:implementation", "value": interpreter.implementation}],
+        }
+    ]
+    refs: Final[dict[str, str]] = {
+        distribution.name: tool_ref(purl(distribution.name, distribution.metadata.version))
+        for distribution in facts.distributions
+    }
+    dependencies: Final[list[Dependency]] = []
+    for distribution in sorted(facts.distributions, key=lambda entry: entry.name):
+        component = component_from_metadata(distribution.metadata)
+        component["bom-ref"] = refs[distribution.name]
+        if distribution.files:
+            component["components"] = [file_component(component["bom-ref"], row) for row in distribution.files]
+        tools.append(component)
+        dependencies.append({
+            "ref": component["bom-ref"],
+            "dependsOn": sorted(refs[name] for name in distribution.depends_on),
+        })
+    return tools, dependencies
+
+
+__all__ = [
+    "tool_components",
+]