pkgcore.ebuild.keywording module

Resolving a keywording or stabilization request against a repo.

A request is a list of package specs, each with the arches it asks for, in the form Gentoo’s arch teams use:

=dev-libs/foo-1.2.3 amd64 x86    # stabilize this exact version
dev-libs/bar        ~ppc64       # keyword any suitable version

Three keyword sentinels are understood: ALL_KEYWORDS expands to the arches the package could plausibly be requested for, SAME_KEYWORDS repeats the line above, and NO_KEYWORDS skips the line.

match_packages() turns that into concrete packages and arches. It knows nothing about where the request came from; pkgcore.bugzilla.Bug.match_packages() is the binding for one that came off a bug.

exception pkgcore.ebuild.keywording.KeywordNoMatch[source]

Bases: PackageMatchException

A keyword isn’t known to the repo, or a sentinel can’t be resolved

exception pkgcore.ebuild.keywording.KeywordNoneLeft[source]

Bases: PkgcoreException

No keywords were given and there are none left to suggest.

Deliberately not a PackageMatchException: the request is fine, it simply has nothing to do, and a caller reporting broken requests must not treat this as one.

exception pkgcore.ebuild.keywording.KeywordNotSpecified(packages: Iterable[str], message: str = '')[source]

Bases: PackageMatchException

Some packages were left without keywords

class pkgcore.ebuild.keywording.KeywordRequest(pkg: package, keywords: list[str])[source]

Bases: NamedTuple

A matched package and the arches requested for it

keywords: list[str]

Alias for field number 1

pkg: package

Alias for field number 0

exception pkgcore.ebuild.keywording.PackageInvalid[source]

Bases: PackageMatchException

A spec isn’t one this kind of request may carry

exception pkgcore.ebuild.keywording.PackageListDoneAlready[source]

Bases: PackageListEmpty

Nothing was left because every package is keyworded already

exception pkgcore.ebuild.keywording.PackageListEmpty[source]

Bases: PackageMatchException

Nothing was left to act on

exception pkgcore.ebuild.keywording.PackageMatchException[source]

Bases: PkgcoreException

The request can’t be resolved as written.

Callers routinely catch this broadly to report a request as unusable, which is why KeywordNoneLeft deliberately sits outside it.

exception pkgcore.ebuild.keywording.PackageNoMatch[source]

Bases: PackageMatchException

A spec parses but matches nothing in the repo

pkgcore.ebuild.keywording.can_stabilize_allarches(repo: UnconfiguredTree, requests: Iterable[tuple[package, Iterable[str]]]) → bool[source]

Whether every package already has a stable version on every arch asked for.

That is the precondition for one arch team stabilizing on behalf of all of them: nobody is being asked to take on an arch they never had.

Parameters:

  • repo – repo to look for the packages’ other versions in

  • requests – packages paired with the arches asked for

Returns:

whether an all-arches stabilization is permissible

pkgcore.ebuild.keywording.filter_prefix_keywords(keywords: Iterable[str]) → list[str][source]

Drop prefix keywords, e.g. x86-macos or *-fbsd

pkgcore.ebuild.keywording.match_packages(repo: UnconfiguredTree, requested: Iterable[tuple[atom, Sequence[str]]], *, stable: bool, cc_arches: Sequence[str] = (), only_new: bool = False, filter_arch: Iterable[str] = (), allarches: bool = False) → Iterator[KeywordRequest][source]

Match requested specs against repo, yielding packages and arches.

Parameters:

  • repo – repo to resolve the specs against

  • requested – each package spec paired with the keywords written for it, in order, since SAME_KEYWORDS refers to the line above

  • stable – select stabilization semantics: only = specs are allowed, and ALL_KEYWORDS means “arches stable elsewhere” rather than “arches keyworded elsewhere”

  • cc_arches – the arches the request is addressed to. A line with no keywords of its own inherits them; a line with keywords is narrowed to them, and one left with nothing is skipped

  • only_new – drop the arches the package already carries

  • filter_arch – keep only the arches listed

  • allarches – re-add every candidate arch on top of filter_arch, for an all-arches stabilization

Returns:

the matched packages, each with the arches to request for it

Raises:
pkgcore.ebuild.keywording.select_best_version(matches: Iterable[package]) → package | None[source]

Pick the version a request without an exact one should act on.

The newest keyworded version wins; failing that the newest non-live one, since a live ebuild is never what a keywording request means.

Parameters:

matches – candidate packages, in any order

Returns:

the version to act on, or None if there were no candidates

pkgcore.ebuild.keywording.suggested_keywords(repo: UnconfiguredTree, pkg: package, *, stable: bool) → frozenset[str][source]

The arches ALL_KEYWORDS expands to for pkg.

Stabilizing, that is the arches already stable on some other version and ~arch on this one. Keywording, it is the arches present on some other version and missing here. Prefix keywords are never suggested.

Parameters:

  • repo – repo to look for the package’s other versions in

  • pkg – the version the request names

  • stable – whether the request is a stabilization

Returns:

the arches to request, unordered