pitloom 0.1.0__py3-none-any.whl

pitloom/__about__.py

@@ -0,0 +1,7 @@
+# SPDX-FileCopyrightText: 2026-present Arthit Suriyawongkul
+# SPDX-FileType: SOURCE
+# SPDX-License-Identifier: Apache-2.0
+
+"""Package information for Pitloom."""
+
+__version__ = "0.1.0"

pitloom/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2026-present Arthit Suriyawongkul
+# SPDX-FileType: SOURCE
+# SPDX-License-Identifier: Apache-2.0
+
+"""Pitloom: Creating SBOM during the build process."""
+
+from pitloom.__about__ import __version__
+
+__all__ = ["__version__"]

pitloom/__main__.py

@@ -0,0 +1,143 @@
+# SPDX-FileCopyrightText: 2026-present Arthit Suriyawongkul
+# SPDX-FileType: SOURCE
+# SPDX-License-Identifier: Apache-2.0
+
+"""Command-line interface for Pitloom SBOM generator."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import traceback
+from pathlib import Path
+
+from pitloom.__about__ import __version__
+from pitloom.assemble import generate_sbom
+from pitloom.core.creation import CreationMetadata
+
+_SPDX3_JSON_EXT = ".spdx3.json"
+
+
+def _resolve_output_path(explicit: Path | None, project_dir: Path) -> Path:
+    """Return the SBOM output path to use.
+
+    Priority:
+    1. Explicit ``-o`` / ``--output`` argument.
+    2. ``[tool.pitloom] sbom-basename`` from ``pyproject.toml``
+       → ``<basename>.spdx3.json``.
+    3. ``<name>-<version>.spdx3.json`` derived from project metadata.
+    4. Fallback: ``sbom.spdx3.json``.
+    """
+    if explicit is not None:
+        return explicit
+
+    try:
+        # pylint: disable=import-outside-toplevel
+        from pitloom.extract.pyproject import read_pyproject
+
+        metadata, pitloom_config = read_pyproject(project_dir / "pyproject.toml")
+
+        if pitloom_config.sbom_basename:
+            return Path(f"{pitloom_config.sbom_basename}{_SPDX3_JSON_EXT}")
+
+        parts = [metadata.name] if metadata.name else ["sbom"]
+        if metadata.version:
+            parts.append(metadata.version)
+        return Path("-".join(parts) + _SPDX3_JSON_EXT)
+
+    except Exception:  # pylint: disable=broad-exception-caught
+        return Path(f"sbom{_SPDX3_JSON_EXT}")
+
+
+def main() -> int:
+    """Main entry point for the Pitloom CLI.
+
+    Returns:
+        int: Exit code (0 for success, 1 for error)
+    """
+    parser = argparse.ArgumentParser(
+        description="Pitloom - Generate SPDX 3 SBOM for Python projects",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"Pitloom {__version__}",
+    )
+    parser.add_argument(
+        "project_dir",
+        type=Path,
+        help="Path to the project directory (containing pyproject.toml)",
+    )
+    parser.add_argument(
+        "-o",
+        "--output",
+        type=Path,
+        default=None,
+        help=(
+            "Output file path. "
+            "Default: <name>-<version>.spdx3.json derived from pyproject.toml, "
+            "or the basename from [tool.pitloom] sbom-basename if set."
+        ),
+    )
+    parser.add_argument(
+        "--creator-name",
+        type=str,
+        help="Name of the SBOM creator (default: Pitloom)",
+    )
+    parser.add_argument(
+        "--creator-email",
+        type=str,
+        help="Email of the SBOM creator",
+    )
+    parser.add_argument(
+        "--pretty",
+        action="store_true",
+        default=None,
+        help=(
+            "Pretty-print the SBOM output with 2-space indentation. "
+            "Overrides 'pretty' in [tool.pitloom] in pyproject.toml. "
+            "Default is compact output (machine-optimized)."
+        ),
+    )
+
+    args = parser.parse_args()
+
+    try:
+        project_dir = args.project_dir.resolve()
+        if not project_dir.exists():
+            print(f"Error: Project directory not found: {project_dir}", file=sys.stderr)
+            return 1
+
+        pyproject_path = project_dir / "pyproject.toml"
+        if not pyproject_path.exists():
+            print(
+                f"Error: pyproject.toml not found in {project_dir}",
+                file=sys.stderr,
+            )
+            return 1
+
+        output_path = _resolve_output_path(args.output, project_dir)
+
+        print(f"Generating SBOM for project in: {project_dir}")
+        generate_sbom(
+            project_dir,
+            output_path=output_path,
+            creation_info=CreationMetadata(
+                creator_name=args.creator_name or "Pitloom",
+                creator_email=args.creator_email or "",
+            ),
+            pretty=args.pretty,
+        )
+        print(f"SBOM written to: {output_path}")
+        return 0
+
+    except Exception as e:  # pylint: disable=broad-exception-caught
+        print(f"Error generating SBOM: {e}", file=sys.stderr)
+        traceback.print_exc()
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

pitloom/assemble/__init__.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: 2026-present Arthit Suriyawongkul
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileType: SOURCE
+
+"""SBOM assemblers for different output specifications."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pitloom.assemble.spdx3.assembler import build
+from pitloom.assemble.spdx3.fragments import merge_fragments
+from pitloom.core.creation import CreationMetadata
+from pitloom.core.document import DocumentModel
+from pitloom.extract.pyproject import read_pyproject
+
+
+def generate_sbom(
+    project_dir: Path,
+    output_path: Path | None = None,
+    creation_info: CreationMetadata | None = None,
+    pretty: bool | None = None,
+) -> str:
+    """Generate an SPDX 3 SBOM for a Python project.
+
+    Args:
+        project_dir: Path to the project directory containing ``pyproject.toml``.
+        output_path: If given, the JSON-LD output is also written to this path.
+        pretty: If ``True``, indent the JSON output with 2 spaces.
+            If ``False``, produce compact output (no extra whitespace).
+            If ``None`` (default), read the setting from ``[tool.pitloom] pretty``
+            in ``pyproject.toml`` (which itself defaults to ``False``).
+        creation_info: Creator and timestamp metadata for the SBOM document.
+            When ``None`` a default :class:`~pitloom.core.creation.CreationMetadata`
+            is used (creator ``"Pitloom"``, current UTC time).
+
+    Returns:
+        JSON-LD string of the generated SPDX 3 SBOM.
+
+    Raises:
+        FileNotFoundError: If ``pyproject.toml`` is not found in ``project_dir``.
+        ValueError: If required project metadata (e.g., ``name``) is missing.
+    """
+    metadata, pitloom_config = read_pyproject(project_dir / "pyproject.toml")
+    effective_pretty: bool = pitloom_config.pretty if pretty is None else pretty
+
+    doc = DocumentModel(
+        project=metadata,
+        creation=creation_info or CreationMetadata(),
+    )
+    exporter = build(doc)
+    merge_fragments(project_dir, pitloom_config.fragments, exporter)
+
+    sbom_json = exporter.to_json(pretty=effective_pretty)
+
+    if output_path is not None:
+        output_path.write_text(sbom_json, encoding="utf-8")
+
+    return sbom_json
+
+
+__all__ = ["generate_sbom"]

pitloom/assemble/spdx3/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2026-present Arthit Suriyawongkul
+# SPDX-FileType: SOURCE
+# SPDX-License-Identifier: Apache-2.0
+
+"""SPDX 3 SBOM assembler."""
+
+from pitloom.assemble.spdx3.assembler import build
+
+__all__ = ["build"]

pitloom/assemble/spdx3/assembler.py

@@ -0,0 +1,158 @@
+# SPDX-FileCopyrightText: 2026-present Arthit Suriyawongkul
+# SPDX-FileType: SOURCE
+# SPDX-License-Identifier: Apache-2.0
+
+"""SPDX 3 assembler for Python projects."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from uuid import uuid4
+
+from spdx_python_model import v3_0_1 as spdx3
+
+from pitloom.assemble.spdx3.deps import add_dependencies, build_license_elements
+from pitloom.core.document import DocumentModel
+from pitloom.core.models import generate_spdx_id
+from pitloom.export.spdx3_json import Spdx3JsonExporter
+
+
+def build(doc: DocumentModel) -> Spdx3JsonExporter:
+    """Assemble SPDX 3 elements from a :class:`~pitloom.core.document.DocumentModel`.
+
+    Args:
+        doc: Format-neutral document model with project metadata, creation
+            metadata, and any AI model metadata.
+
+    Returns:
+        A populated :class:`~pitloom.export.spdx3_json.Spdx3JsonExporter`
+        containing all SPDX 3 elements for the project and its dependencies.
+    """
+    metadata = doc.project
+    ci = doc.creation
+    created_at = (
+        datetime.fromisoformat(ci.creation_datetime)
+        if ci.creation_datetime
+        else datetime.now(timezone.utc)
+    )
+
+    exporter = Spdx3JsonExporter()
+    doc_uuid = str(uuid4())
+
+    # --- Creation info, creator agent, and creation tool ---
+    spdx_ci = spdx3.CreationInfo(
+        specVersion="3.0.1",
+        created=created_at,
+    )
+    creator = spdx3.Person(
+        spdxId=generate_spdx_id("Person", doc_name=metadata.name, doc_uuid=doc_uuid),
+        name=ci.creator_name,
+        creationInfo=spdx_ci,
+    )
+    if ci.creator_email:
+        creator.externalIdentifier = [
+            spdx3.ExternalIdentifier(
+                externalIdentifierType=spdx3.ExternalIdentifierType.email,
+                identifier=ci.creator_email,
+            )
+        ]
+    tool = spdx3.Tool(
+        spdxId=generate_spdx_id("Tool", doc_name=metadata.name, doc_uuid=doc_uuid),
+        name=ci.creation_tool,
+        creationInfo=spdx_ci,
+    )
+    spdx_ci.createdBy = [creator.spdxId]
+    spdx_ci.createdUsing = [tool.spdxId]
+
+    exporter.add_creation_info(spdx_ci)
+    exporter.add_person(creator)
+    exporter.object_set.add(tool)
+
+    # --- Main package ---
+    copyright_holder = (
+        metadata.authors[0].get("name", metadata.name)
+        if metadata.authors
+        else metadata.name
+    )
+    provenance_comment: str | None = None
+    if metadata.provenance:
+        parts = [f"{field}: {source}" for field, source in metadata.provenance.items()]
+        provenance_comment = "Metadata provenance: " + "; ".join(parts)
+
+    download_location = metadata.urls.get("Source") or metadata.urls.get("Homepage")
+
+    main_package = spdx3.software_Package(
+        spdxId=generate_spdx_id("Package", doc_name=metadata.name, doc_uuid=doc_uuid),
+        name=metadata.name,
+        creationInfo=spdx_ci,
+    )
+    main_package.software_packageVersion = metadata.version or "unknown"
+    main_package.suppliedBy = creator.spdxId
+    if metadata.description:
+        main_package.description = metadata.description
+    if download_location:
+        main_package.software_downloadLocation = download_location
+    if metadata.urls.get("Homepage"):
+        main_package.software_homePage = metadata.urls.get("Homepage")
+    main_package.software_copyrightText = (
+        f"Copyright (c) {datetime.now().year} {copyright_holder}"
+    )
+    main_package.software_primaryPurpose = spdx3.software_SoftwarePurpose.library
+    if ci.build_datetime:
+        main_package.builtTime = datetime.fromisoformat(ci.build_datetime)
+    if provenance_comment:
+        main_package.comment = provenance_comment
+
+    # --- SBOM and document envelope ---
+    sbom = spdx3.software_Sbom(
+        spdxId=generate_spdx_id("Sbom", doc_name=metadata.name, doc_uuid=doc_uuid),
+        creationInfo=spdx_ci,
+        rootElement=[main_package.spdxId],
+    )
+    sbom.software_sbomType = [spdx3.software_SbomType.build]
+
+    spdx_doc = spdx3.SpdxDocument(
+        spdxId=generate_spdx_id(
+            "SpdxDocument", doc_name=metadata.name, doc_uuid=doc_uuid
+        ),
+        creationInfo=spdx_ci,
+        rootElement=[sbom.spdxId],
+    )
+    spdx_doc.profileConformance = [
+        spdx3.ProfileIdentifierType.core,
+        spdx3.ProfileIdentifierType.software,
+    ]
+
+    exporter.add_document(spdx_doc)
+    exporter.add_sbom(sbom)
+    exporter.add_package(main_package)
+
+    # --- License ---
+    if metadata.license_name:
+        rel_declared, rel_concluded = build_license_elements(
+            license_id=metadata.license_name,
+            package_spdx_id=main_package.spdxId,
+            license_provenance=metadata.provenance.get(
+                "license", "Source: pyproject.toml | Field: project.license"
+            ),
+            creation_info=spdx_ci,
+            doc_name=metadata.name,
+            doc_uuid=doc_uuid,
+            exporter=exporter,
+        )
+        exporter.add_relationship(rel_declared)
+        exporter.add_relationship(rel_concluded)
+        spdx_doc.profileConformance.append(spdx3.ProfileIdentifierType.simpleLicensing)
+
+    # --- Dependencies ---
+    add_dependencies(
+        dependencies=metadata.dependencies,
+        dep_provenance=metadata.provenance.get("dependencies", "Unknown source"),
+        main_package_spdx_id=main_package.spdxId,
+        creation_info=spdx_ci,
+        doc_name=metadata.name,
+        doc_uuid=doc_uuid,
+        exporter=exporter,
+    )
+
+    return exporter