debby 1.0.0__py3-none-any.whl

debby/__init__.py

@@ -0,0 +1,14 @@
+"""
+.. include:: ../README.md
+"""
+
+import importlib.metadata as metadata
+
+__version__ = metadata.version(__package__ or __name__)
+
+from .control_file import ControlFile
+from .files import Files
+from .meta import Meta
+from .package import Package
+
+__all__ = ("Package", "ControlFile", "Files", "Meta")

debby/__main__.py

@@ -0,0 +1,28 @@
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from debby.args import Args
+from debby.control_file import ControlFile
+from debby.exceptions import DebbyError
+from debby.files import Files
+from debby.meta import MetaLoaderFactory
+from debby.package import Package
+
+
+def main(argv: Sequence[str] | None = None):
+    print(create_package(Args.parse(argv)))
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except DebbyError as e:
+        print(e, file=sys.stderr)
+
+
+def create_package(args: Args) -> Path:
+    meta = MetaLoaderFactory(args).loader().load()
+    files = Files(args.files)
+    package = Package(meta, ControlFile(meta, files, args.template), files)
+    return package.create(args.out_dir)

debby/args.py

@@ -0,0 +1,189 @@
+import os
+from argparse import ArgumentParser
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal, Self, Sequence
+
+
+@dataclass
+class Args:
+    files: Sequence[tuple[Path, Path]]
+    template: Path | None
+    out_dir: Path
+    pyproject: Path | None
+    poetry: Path | None
+    name: str | None
+    source: str | None
+    version: str | None
+    section: str | None
+    priority: str | None
+    architecture: str | None
+    essential: Literal["yes", "no"] | None
+    maintainer: str | None
+    description: str | None
+    homepage: str | None
+    depends: str | None
+    pre_depends: str | None
+    recommends: str | None
+    suggests: str | None
+    enhances: str | None
+    breaks: str | None
+    conflicts: str | None
+    no_size: bool = False
+
+    @classmethod
+    def parse(cls, argv: Sequence[str] | None = None) -> Self:
+        parser = ArgumentParser()
+        parser.add_argument(
+            "-f",
+            "--file",
+            dest="files",
+            help="Path to the files to package. Can be passed multiple times. E.g. --file SOURCE1 DESTINATION1 --file SOURCE2 DESTINATION2. Sources must point to existing files or directories and destinations will be treated as relative to the package root.",
+            type=Path,
+            nargs=2,
+            action="append",
+            default=[],
+        )
+        parser.add_argument(
+            "-t",
+            "--template",
+            help="Path to the control file template",
+            type=Path,
+        )
+        parser.add_argument(
+            "-o",
+            "--out-dir",
+            help="Path to the output directory",
+            type=Path,
+            default=Path("debian/build"),
+        )
+        parser.add_argument(
+            "--no-size",
+            help="Do not include the total size of the package in the control file",
+            action="store_true",
+        )
+        cls._add_meta_source_group(parser)
+        cls._add_meta_override_args(parser)
+        return cls(**vars(parser.parse_args(argv)))
+
+    @classmethod
+    def _add_meta_source_group(cls, parser: ArgumentParser) -> None:
+        meta_source_group = parser.add_mutually_exclusive_group(required=True)
+        meta_source_group.add_argument(
+            "--pyproject",
+            help="Read metadata according to PEP 621 from the given pyproject.toml file",
+            type=Path,
+            metavar="pyproject.toml",
+        )
+        meta_source_group.add_argument(
+            "--poetry",
+            help="Read poetry metadata from the given pyproject.toml file",
+            type=Path,
+            metavar="pyproject.toml",
+        )
+
+    @classmethod
+    def _add_meta_override_args(cls, parser: ArgumentParser) -> None:
+        meta_overrides_group = parser.add_argument_group(
+            "Metadata Overrides",
+            "Override metadata fields. Environment variables such as DEBBY_META_VERSION can be used to set these fields.",
+        )
+        meta_overrides_group.add_argument(
+            "-n",
+            "--name",
+            help="Specify the package name",
+            default=os.environ.get("DEBBY_META_NAME"),
+        )
+        meta_overrides_group.add_argument(
+            "-s",
+            "--source",
+            help="Specify the package source",
+            default=os.environ.get("DEBBY_META_SOURCE"),
+        )
+        meta_overrides_group.add_argument(
+            "-v",
+            "--version",
+            help="Specify the package version",
+            default=os.environ.get("DEBBY_META_VERSION"),
+        )
+        meta_overrides_group.add_argument(
+            "--section",
+            help="Specify the package section",
+            default=os.environ.get("DEBBY_META_SECTION"),
+        )
+        meta_overrides_group.add_argument(
+            "-p",
+            "--priority",
+            help="Specify the package priority",
+            default=os.environ.get("DEBBY_META_PRIORITY"),
+        )
+        meta_overrides_group.add_argument(
+            "-a",
+            "--architecture",
+            help="Specify the package architecture",
+            default=os.environ.get("DEBBY_META_ARCHITECTURE"),
+        )
+        meta_overrides_group.add_argument(
+            "-e",
+            "--essential",
+            choices=["yes", "no"],
+            help="Specify whether the package is essential",
+            default=os.environ.get("DEBBY_META_ESSENTIAL"),
+        )
+        meta_overrides_group.add_argument(
+            "-m",
+            "--maintainer",
+            help="Specify the package maintainer",
+            default=os.environ.get("DEBBY_META_MAINTAINER"),
+        )
+        meta_overrides_group.add_argument(
+            "-d",
+            "--description",
+            help="Specify the package description",
+            default=os.environ.get("DEBBY_META_DESCRIPTION"),
+        )
+        meta_overrides_group.add_argument(
+            "--homepage",
+            help="Specify the package homepage",
+            default=os.environ.get("DEBBY_META_HOMEPAGE"),
+        )
+        cls._add_dependencies_args(meta_overrides_group)
+
+    @classmethod
+    def _add_dependencies_args(cls, parser: ArgumentParser | Any) -> None:
+        parser.add_argument_group("Dependencies", "Specify package dependencies")
+        parser.add_argument(
+            "--depends",
+            help="Specify package dependencies",
+            default=os.environ.get("DEBBY_META_DEPENDS"),
+        )
+        parser.add_argument(
+            "--pre-depends",
+            help="Specify package pre-dependencies",
+            default=os.environ.get("DEBBY_META_PRE_DEPENDS"),
+        )
+        parser.add_argument(
+            "--recommends",
+            help="Specify package recommendations",
+            default=os.environ.get("DEBBY_META_RECOMMENDS"),
+        )
+        parser.add_argument(
+            "--suggests",
+            help="Specify package suggestions",
+            default=os.environ.get("DEBBY_META_SUGGESTS"),
+        )
+        parser.add_argument(
+            "--enhances",
+            help="Specify package enhancements",
+            default=os.environ.get("DEBBY_META_ENHANCES"),
+        )
+        parser.add_argument(
+            "--breaks",
+            help="Specify package breaks",
+            default=os.environ.get("DEBBY_META_BREAKS"),
+        )
+        parser.add_argument(
+            "--conflicts",
+            help="Specify package conflicts",
+            default=os.environ.get("DEBBY_META_CONFLICTS"),
+        )

debby/control_file.py

@@ -0,0 +1,63 @@
+from pathlib import Path
+from typing import Iterable
+
+from debby.files import Files
+from debby.meta import Meta
+
+
+class ControlFile:
+    def __init__(
+        self,
+        meta: Meta,
+        files: Files,
+        template: Path | None = None,
+        include_size: bool = True,
+    ) -> None:
+        self._meta = meta
+        self._files = files
+        self._template = template
+        self._include_size = include_size
+
+    def create(self, path: Path) -> None:
+        path.write_text("\n".join(self._lines()) + "\n")
+
+    def _lines(self) -> Iterable[str]:
+        if not self._template:
+            return self._default_lines()
+        return (
+            line.format(metadata=self._meta, files=self._files)
+            for line in self._template.read_text().splitlines()
+        )
+
+    def _default_lines(self) -> Iterable[str]:
+        yield f"Package: {self._meta.name}"
+        if self._meta.source:
+            yield f"Source: {self._meta.source}"
+        yield f"Version: {self._meta.version}"
+        if self._meta.section:
+            yield f"Section: {self._meta.section}"
+        if self._meta.priority:
+            yield f"Priority: {self._meta.priority}"
+        yield f"Architecture: {self._meta.architecture}"
+        if self._meta.essential:
+            yield f"Essential: {self._meta.essential}"
+        if self._include_size and self._files.total_size:
+            yield f"Installed-Size: {self._files.total_size}"
+        yield f"Maintainer: {self._meta.maintainer}"
+        yield f"Description: {self._meta.description}"
+        if homepage := self._meta.homepage:
+            yield f"Homepage: {homepage}"
+        if depends := self._meta.depends:
+            yield f"Depends: {depends}"
+        if pre_depends := self._meta.pre_depends:
+            yield f"Pre-Depends: {pre_depends}"
+        if recommends := self._meta.recommends:
+            yield f"Recommends: {recommends}"
+        if suggests := self._meta.suggests:
+            yield f"Suggests: {suggests}"
+        if enhances := self._meta.enhances:
+            yield f"Enhances: {enhances}"
+        if breaks := self._meta.breaks:
+            yield f"Breaks: {breaks}"
+        if conflicts := self._meta.conflicts:
+            yield f"Conflicts: {conflicts}"

debby/exceptions.py

@@ -0,0 +1,9 @@
+class DebbyError(Exception):
+    """Base class for all Debby exceptions."""
+
+
+class MissingMetadataError(DebbyError):
+    """Raised when required metadata is missing."""
+
+    def __str__(self) -> str:
+        return f"Missing some required metadata. Make sure it's present in any of the sources, or provide it as a command-line argument or environment variable. {super().__str__()}"

debby/files.py

@@ -0,0 +1,60 @@
+from functools import cached_property
+from pathlib import Path
+from typing import Iterable, Iterator, Mapping
+
+
+class Files(Mapping[Path, Path]):
+    """A mapping of target paths in the package to source paths on the filesystem.
+
+    Args:
+        files: An iterable of pairs of source paths and destination paths.
+    """
+
+    def __init__(self, files: Iterable[tuple[Path, Path]]) -> None:
+        self._files = self._normalize_files(files)
+
+    def __post_init__(self) -> None:
+        if any(
+            not src.exists() or dst.is_absolute() for dst, src in self._files.items()
+        ):
+            raise ValueError(
+                "source files must all exist and destination paths must all be relative"
+            )
+
+    def package(self, path: Path) -> None:
+        for dst, src in self.items():
+            target = path / dst
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.symlink_to(src)
+
+    @classmethod
+    def _normalize_files(
+        cls, files: Iterable[tuple[Path, Path]]
+    ) -> Mapping[Path, Path]:
+        return {
+            dst.relative_to(dst.anchor) if dst.is_absolute() else dst: src
+            for src, dst in files
+        }
+
+    @property
+    def sources(self) -> Iterable[Path]:
+        return self._files.values()
+
+    @property
+    def destinations(self) -> Iterable[Path]:
+        return self._files.keys()
+
+    @cached_property
+    def total_size(self) -> int:
+        return sum(
+            (max(f.resolve().stat().st_size, 1024) // 1024) * 1024 for f in self.sources
+        )
+
+    def __getitem__(self, key: Path) -> Path:
+        return self._files[key]
+
+    def __iter__(self) -> Iterator[Path]:
+        return iter(self._files)
+
+    def __len__(self) -> int:
+        return len(self._files)

debby/meta/__init__.py

@@ -0,0 +1,5 @@
+from .meta import Meta
+from .meta_loader import MetaLoader
+from .meta_loader_factory import MetaLoaderFactory
+
+__all__ = ("Meta", "MetaLoader", "MetaLoaderFactory")

debby/meta/meta.py

@@ -0,0 +1,51 @@
+from dataclasses import dataclass
+from typing import Literal, TypedDict
+
+
+class MetaVars(TypedDict, total=False):
+    """A dictionary of metadata variables."""
+
+    name: str
+    source: str
+    version: str
+    section: str
+    priority: str
+    architecture: str
+    essential: Literal["yes", "no"]
+    maintainer: str
+    description: str
+    homepage: str
+    depends: str
+    pre_depends: str
+    recommends: str
+    suggests: str
+    enhances: str
+    breaks: str
+    conflicts: str
+
+
+@dataclass(kw_only=True, frozen=True, slots=True)
+class Meta:
+    """Metadata for a Debian package."""
+
+    name: str
+    source: str | None = None
+    version: str
+    section: str | None = None
+    priority: str | None = None
+    architecture: str = "all"
+    essential: Literal["yes", "no"] | None = None
+    maintainer: str
+    description: str
+    homepage: str | None = None
+    depends: str | None = None
+    pre_depends: str | None = None
+    recommends: str | None = None
+    suggests: str | None = None
+    enhances: str | None = None
+    breaks: str | None = None
+    conflicts: str | None = None
+
+    @property
+    def full_name(self) -> str:
+        return f"{self.name}_{self.version}_{self.architecture}"

debby/meta/meta_loader.py

@@ -0,0 +1,68 @@
+from debby.args import Args
+from debby.exceptions import MissingMetadataError
+
+from .meta import Meta, MetaVars
+
+
+class MetaLoader:
+    """Load metadata from a source.
+
+    Classes that inherit from this class should implement the `load_from_source` method. The value they return will be overridden by the values specified by the user in the command-line arguments, and the resulting metadata will be returned.
+
+    Args:
+        args: The command-line arguments.
+    """
+
+    def __init__(self, args: Args) -> None:
+        self._args = args
+
+    def load(self) -> Meta:
+        """Load the metadata."""
+        kwargs: MetaVars = {**self.load_from_source(), **self.overrides()}
+        try:
+            return Meta(**kwargs)
+        except TypeError as e:
+            raise MissingMetadataError(str(e)) from None
+
+    def load_from_source(self) -> MetaVars:
+        """Load the metadata from the source."""
+        return {}
+
+    def overrides(self) -> MetaVars:
+        """Return metadata overrides as specified by the user."""
+        result: MetaVars = {}
+        if self._args.name:
+            result["name"] = self._args.name
+        if self._args.source:
+            result["source"] = self._args.source
+        if self._args.version:
+            result["version"] = self._args.version
+        if self._args.section:
+            result["section"] = self._args.section
+        if self._args.priority:
+            result["priority"] = self._args.priority
+        if self._args.architecture:
+            result["architecture"] = self._args.architecture
+        if self._args.essential:
+            result["essential"] = self._args.essential
+        if self._args.maintainer:
+            result["maintainer"] = self._args.maintainer
+        if self._args.description:
+            result["description"] = self._args.description
+        if self._args.homepage:
+            result["homepage"] = self._args.homepage
+        if self._args.depends:
+            result["depends"] = self._args.depends
+        if self._args.pre_depends:
+            result["pre_depends"] = self._args.pre_depends
+        if self._args.recommends:
+            result["recommends"] = self._args.recommends
+        if self._args.suggests:
+            result["suggests"] = self._args.suggests
+        if self._args.enhances:
+            result["enhances"] = self._args.enhances
+        if self._args.breaks:
+            result["breaks"] = self._args.breaks
+        if self._args.conflicts:
+            result["conflicts"] = self._args.conflicts
+        return result

debby/meta/meta_loader_factory.py

@@ -0,0 +1,24 @@
+from debby.args import Args
+
+from .meta_loader import MetaLoader
+from .poetry_meta_loader import PoetryMetaLoader
+from .pyproject_meta_loader import PyprojectMetaLoader
+
+
+class MetaLoaderFactory:
+    """Factory for creating an appropriate MetaLoader according to the given arguments.
+
+    Args:
+        args: The command-line arguments.
+    """
+
+    def __init__(self, args: Args) -> None:
+        self._args = args
+
+    def loader(self) -> MetaLoader:
+        """Create the appropriate MetaLoader."""
+        if self._args.pyproject:
+            return PyprojectMetaLoader(self._args)
+        if self._args.poetry:
+            return PoetryMetaLoader(self._args)
+        return MetaLoader(self._args)

debby/meta/poetry_meta_loader.py

@@ -0,0 +1,28 @@
+import tomllib
+from pathlib import Path
+
+from .meta import MetaVars
+from .meta_loader import MetaLoader
+
+
+class PoetryMetaLoader(MetaLoader):
+    """Load poetry metadata from a pyproject.toml file."""
+
+    @property
+    def _pyproject(self) -> Path:
+        assert self._args.poetry is not None
+        return self._args.poetry
+
+    def load_from_source(self) -> MetaVars:
+        poetry_data = tomllib.loads(self._pyproject.read_text())["tool"]["poetry"]
+        result: MetaVars = {
+            "name": poetry_data["name"],
+            "version": poetry_data["version"],
+            "description": poetry_data["description"],
+            "maintainer": next(
+                iter((*poetry_data.get("maintainers", ()), *poetry_data["authors"]))
+            ),
+        }
+        if homepage := poetry_data.get("homepage"):
+            result["homepage"] = homepage
+        return result

debby/meta/pyproject_meta_loader.py

@@ -0,0 +1,57 @@
+import tomllib
+from pathlib import Path
+from typing import Any, Iterable, Mapping, TypedDict
+
+from .meta import MetaVars
+from .meta_loader import MetaLoader
+
+
+class PyprojectMetaLoader(MetaLoader):
+    """Load python project metadata according to PEP621 from a pyproject.toml file."""
+
+    @property
+    def _pyproject(self) -> Path:
+        assert self._args.pyproject is not None
+        return self._args.pyproject
+
+    def load_from_source(self) -> MetaVars:
+        project_data = tomllib.loads(self._pyproject.read_text())["project"]
+        result: MetaVars = {
+            "name": project_data["name"],
+        }
+        if "version" not in project_data["dynamic"]:
+            result["version"] = project_data["version"]
+        if maintainer := self._get_maintainer(project_data):
+            result["maintainer"] = maintainer
+        if description := project_data.get("description"):
+            result["description"] = description
+        if homepage := self._get_homepage(project_data.get("urls", {})):
+            result["homepage"] = homepage
+
+        return result
+
+    def _get_maintainer(self, project_data: Mapping[str, Any]) -> str | None:
+        people: Iterable[_Person] = (
+            project_data.get("maintainers") or project_data.get("authors") or ()
+        )
+        person = next(iter(people), None)
+        if person is None:
+            return None
+        if person.get("name") and person.get("email"):
+            return f"{person.get('name')} <{person.get('email')}>"
+        if person.get("name"):
+            return person.get("name")
+        if person.get("email"):
+            return person.get("email")
+        return None
+
+    def _get_homepage(self, urls: Mapping[str, str]) -> str | None:
+        for key in ("Homepage", "Repository", "Documentation"):
+            if url := urls.get(key):
+                return url
+        return next(iter(urls.values()), None)
+
+
+class _Person(TypedDict, total=False):
+    name: str
+    email: str

debby/package.py

@@ -0,0 +1,30 @@
+from pathlib import Path
+
+from debby.control_file import ControlFile
+from debby.files import Files
+from debby.meta.meta import Meta
+
+
+class Package:
+    """A directory containing a Debian package.
+
+    Args:
+        metadata: The metadata for the package.
+        control: The control file for the package.
+        files: The files to put in the package.
+    """
+
+    def __init__(self, metadata: Meta, control: ControlFile, files: Files) -> None:
+        self.metadata = metadata
+        self.control = control
+        self.files = files
+
+    def create(self, out_dir: Path) -> Path:
+        """Create the directory structure of the package, which can be packaged into a .deb file with dpkg-deb."""
+        directory = out_dir / self.metadata.full_name
+        control_dir = directory / "DEBIAN"
+        control_dir.mkdir(parents=True)
+        control_dir.chmod(0o755)
+        self.control.create(control_dir / "control")
+        self.files.package(directory)
+        return directory

debby/py.typed

@@ -0,0 +1 @@
+