Package formats (`package`)

The package-format registry and its built-in formats. build writes one package per declared package from the file DB and the build root. A third-party format subclasses PackageFormat with its own NAME and advertises it in the pkgforge.package_formats entry-point group. The packages' user and group names, modes and times are read from the DB and the build root the same way for every format.

`pkgforge.package.build(db, fmt, output, *, buildroot, config=None, config_path=None, arch=None, compression=None)`

Build one package per declared package from the live entries of db and the files under buildroot, in the format fmt.

output is the directory the packages are written into (created with the first package; a failed build leaves nothing behind). config names the packages (default: an empty configuration, which no format accepts) and config_path is the file it was read from. arch names the architecture of an any package in the format's own spelling (default: this machine's); compression is one the format offers (default: its first). Build-time stamps and file times are SOURCE_DATE_EPOCH when it is set, so two builds of one build root are byte-identical.

Returns the paths written, the main package first, then each [[packages]] element in order.

Raises :class:~pkgforge.exceptions.UsageError for an unknown format, a compression or architecture the format cannot take, a [package] key the format needs, a SOURCE_DATE_EPOCH that is not a number, an entry of a package config does not declare, a recorded path missing from (or of another type in) buildroot or below a symlink that leads outside it, or a missing optional dependency; :class:~pkgforge.exceptions.InvalidEntryError for an entry no format can represent and :class:~pkgforge.exceptions.DumpError for one this format cannot.

Source code in src/pkgforge/package/__init__.py

def build(
    db: typing.Mapping[str, typing.Optional[FileEntry]],
    fmt: str,
    output: StrPath,
    *,
    buildroot: StrPath,
    config: typing.Optional[ProjectConfig] = None,
    config_path: typing.Optional[StrPath] = None,
    arch: typing.Optional[str] = None,
    compression: typing.Optional[str] = None,
) -> typing.List[Path]:
    """Build one package per declared package from the live entries of ``db``
    and the files under ``buildroot``, in the format ``fmt``.

    ``output`` is the directory the packages are written into (created with the
    first package; a failed build leaves nothing behind). ``config`` names the
    packages (default: an empty configuration, which no format accepts) and
    ``config_path`` is the file it was read from.
    ``arch`` names the architecture of an ``any`` package in the format's own
    spelling (default: this machine's); ``compression`` is one the format
    offers (default: its first). Build-time stamps and file times are
    ``SOURCE_DATE_EPOCH`` when it is set, so two builds of one build root are
    byte-identical.

    Returns the paths written, the main package first, then each
    ``[[packages]]`` element in order.

    Raises :class:`~pkgforge.exceptions.UsageError` for an unknown format, a
    compression or architecture the format cannot take, a ``[package]`` key the
    format needs, a ``SOURCE_DATE_EPOCH`` that is not a number, an entry of a
    package ``config`` does not declare, a recorded path missing from (or of
    another type in) ``buildroot`` or below a symlink that leads outside it,
    or a missing optional dependency;
    :class:`~pkgforge.exceptions.InvalidEntryError` for an entry no format can
    represent and :class:`~pkgforge.exceptions.DumpError` for one this format
    cannot.
    """
    cls = PackageFormat.get(fmt)
    if compression is None:
        chosen = cls.COMPRESSIONS[0] if cls.COMPRESSIONS else None
    elif not cls.COMPRESSIONS:
        raise UsageError(f"{cls.NAME} takes no --compression")
    elif compression not in cls.COMPRESSIONS:
        raise UsageError(
            f"{cls.NAME} takes --compression {', '.join(cls.COMPRESSIONS)}"
        )
    else:
        chosen = compression
    if arch is not None and not _ARCH_RE.fullmatch(arch):
        raise UsageError(f"--arch {arch!r} is not an architecture name ([a-z0-9_]+)")
    config = config if config is not None else ProjectConfig()
    _require_keys(cls.NAME, config, cls.REQUIRED, cls.SUB_REQUIRED)
    epoch = _source_date_epoch()
    entries = _surviving_entries(db, ())
    _validate_entries(entries)
    payloads = _payloads(entries, config)
    writer = PackageWriter()
    context = BuildContext(
        config=config,
        buildroot=Path(os.fspath(buildroot)),
        output=Path(os.fspath(output)),
        compression=chosen,
        arch=arch,
        epoch=epoch,
        config_path=None if config_path is None else Path(os.fspath(config_path)),
        writer=writer,
    )
    try:
        written = cls().build(payloads, context)
        writer.commit()
    except BaseException:
        writer.abort()
        raise
    for path in written:
        _LOGGER.info("Wrote %s", path)
    _LOGGER.info("built %d package(s) with %s", len(written), cls.NAME)
    return written

`pkgforge.package.BuildContext(config, buildroot, output, compression, arch, epoch, config_path=None, writer=PackageWriter())` `dataclass`

What a format builds against besides the payloads.

config is the project configuration, buildroot the directory that maps to / in the DB, output the directory the packages are written into, compression the chosen payload compression (None for a format that offers none), arch the --arch value, epoch the SOURCE_DATE_EPOCH seconds (None when unset) and config_path the file config was read from when known. A format creates every file it writes through writer, which keeps the build all or nothing and makes output only once there is a file to put in it.

`arch` `instance-attribute`

`buildroot` `instance-attribute`

`compression` `instance-attribute`

`config` `instance-attribute`

`config_path = None` `class-attribute` `instance-attribute`

`epoch` `instance-attribute`

`output` `instance-attribute`

`writer = dataclasses.field(default_factory=PackageWriter, repr=False, compare=False)` `class-attribute` `instance-attribute`

`pkgforge.package.PackagePayload`

Bases: NamedTuple

One package to build.

`arch` `instance-attribute`

`entries` `instance-attribute`

`info` `instance-attribute`

`main` `instance-attribute`

`name` `instance-attribute`

`pkgforge.package.PackageFormat`

Bases: Registered, ABC

A package format, selected by package -f NAME.

A subclass registers by declaring its own NAME (plus, optionally, ALIASES); see :class:pkgforge._registry.Registered.

`ALIASES = ()` `class-attribute`

`ALL_ARCH = 'all'` `class-attribute`

`COMPRESSIONS = ()` `class-attribute`

`MACHINES = {}` `class-attribute`

`NAME = ''` `class-attribute`

`REQUIRED = ()` `class-attribute`

`SUB_REQUIRED = ()` `class-attribute`

`arch_name(payload, context)`

The architecture name payload carries in this format: :attr:ALL_ARCH for an all package, else context.arch verbatim, else this machine's through :attr:MACHINES.

Raises :class:~pkgforge.exceptions.UsageError for a machine the table lacks.

Source code in src/pkgforge/package/__init__.py

def arch_name(self, payload: PackagePayload, context: BuildContext) -> str:
    """The architecture name ``payload`` carries in this format:
    :attr:`ALL_ARCH` for an ``all`` package, else ``context.arch``
    verbatim, else this machine's through :attr:`MACHINES`.

    Raises :class:`~pkgforge.exceptions.UsageError` for a machine the
    table lacks.
    """
    if payload.arch == "all":
        return self.ALL_ARCH
    if context.arch:
        return context.arch
    machine = platform.machine().lower()
    try:
        return self.MACHINES[machine]
    except KeyError:
        raise UsageError(
            f"{self.NAME}: no architecture name for machine {machine!r}: "
            "pass --arch"
        ) from None

`build(payloads, context)` `abstractmethod`

Write one package per payload into context.output and return their paths in payload order.

Source code in src/pkgforge/package/__init__.py

@abc.abstractmethod
def build(
    self, payloads: typing.Sequence[PackagePayload], context: BuildContext
) -> typing.List[Path]:
    """Write one package per payload into ``context.output`` and return
    their paths in payload order."""

`pkgforge.package.PackageWriter()`

Creates the package files of one :func:~pkgforge.package.build.

Every file is written to a sibling .NAME.pkgforge-tmp and renamed over its final path by :meth:commit, so a build that fails leaves every target as it was. The output directory, and any parent it lacks, is created with the first file and removed again when the build fails.