meta_package_manager.definitions module

Declarative package managers: the TOML schema and its class factory.

A [mpm.managers.<id>] configuration section describes a manager as data. This module owns everything that turns such a description into a live PackageManager subclass:

• the schema vocabulary: which manager attributes a section may set, both on a shipped manager (OVERRIDABLE_FIELDS) and on a brand-new definition (DEFINITION_CLI_FIELDS, the operations DSL constants);

• the validation and parsing layer (parse_manager_definition()), shared by --validate-config and the runtime registration path so a config that survives one survives the other;

• the class factory (build_manager_class()), which synthesizes a ConfigDrivenManager subclass implementing exactly the operations the definition declares;

• the bundled-definition loader (load_bundled_definitions(), build_bundled_managers()): mpm ships some managers as *.toml package data under meta_package_manager/managers/, each a single [mpm.managers.<id>] section in the exact schema a user would write.

The runtime policy around definitions stays in meta_package_manager.config: where sections may be loaded from, the trust gate on local files, the override-application pass and the registration passes wired into the CLI. The split keeps this module dependent on meta_package_manager.manager and the leaf meta_package_manager.cooldown vocabulary only, so the configuration layer can build on it without a circular import.

meta_package_manager.definitions.OVERRIDABLE_FIELDS: Final[Mapping[str, Callable[[Any], Any]]] = {'cli_names': <function _to_str_tuple>, 'cli_search_path': <function _to_str_tuple>, 'cooldown_policy': <function _to_cooldown_policy>, 'dry_run': <function _to_bool>, 'extra_env': <function _to_str_dict>, 'ignore_auto_updates': <function _to_bool>, 'plan': <function _to_bool>, 'post_args': <function _to_str_tuple>, 'pre_args': <function _to_str_tuple>, 'pre_cmds': <function _to_str_tuple>, 'requirement': <function _to_str>, 'stop_on_error': <function _to_bool>, 'sudo': <function _to_bool>, 'timeout': <function _to_int>, 'unmaintained': <function _to_bool>, 'version_cli_options': <function _to_str_tuple>, 'version_regexes': <function _to_str_tuple>}

Per-manager attributes a user is allowed to override from the [mpm.managers.<id>] configuration section.

Each entry maps a meta_package_manager.manager.PackageManager attribute name to a converter that validates the raw TOML value and returns the value as the attribute’s expected runtime type. Lists are coerced into tuples to match the attributes’ tuple types.

Note

id, name, platforms, homepage_url and virtual are intentionally excluded: they are identity, lookup or platform-classification attributes that the pool’s registration relies on. Phase 1 of TOML-driven configuration only exposes attributes whose runtime override is safe.

meta_package_manager.definitions.VALID_PLATFORM_TOKENS: Final[frozenset[str]] = frozenset({'aix', 'all_agents', 'all_architectures', 'all_arm', 'all_ci', 'all_mips', 'all_platforms', 'all_shells', 'all_sparc', 'all_terminals', 'all_traits', 'all_windows', 'almalinux', 'alpine', 'altlinux', 'amzn', 'android', 'arch', 'arch_32_bit', 'arch_64_bit', 'big_endian', 'bourne_shells', 'bsd', 'bsd_without_macos', 'buildroot', 'c_shells', 'cachyos', 'centos', 'chromeos', 'clearlinux', 'cloudlinux', 'cygwin', 'debian', 'dragonfly_bsd', 'endeavouros', 'exherbo', 'fedora', 'freebsd', 'generic_linux', 'gentoo', 'gpu_terminals', 'guix', 'haiku', 'hurd', 'ibm_mainframe', 'ibm_powerkvm', 'illumos', 'kali', 'kvmibm', 'linux', 'linux_layers', 'linux_like', 'linuxmint', 'little_endian', 'loongarch', 'macos', 'mageia', 'mandriva', 'manjaro', 'midnightbsd', 'multiplexers', 'native_terminals', 'netbsd', 'nixos', 'nobara', 'openbsd', 'opensuse', 'openwrt', 'oracle', 'os400', 'other_posix', 'other_shells', 'parallels', 'pidora', 'pikaos', 'powerpc', 'raspbian', 'rhel', 'riscv', 'rocky', 'scientific', 'slackware', 'sles', 'slitaz', 'solaris', 'sourcemage', 'sunos', 'system_v', 'tuxedo', 'ubuntu', 'ultramarine', 'unix', 'unix_layers', 'unix_without_macos', 'void', 'web_terminals', 'webassembly', 'windows', 'windows_shells', 'wsl1', 'wsl2', 'x86', 'xenserver'})

Platform and group IDs accepted in a definition’s platforms list.

Union of every extra_platforms.Platform ID and every group ID, so both a specific platform (ubuntu) and a group (linux, all_platforms) resolve.

meta_package_manager.definitions.DEFINITION_CLI_FIELDS: Final[Mapping[str, Callable[[Any], Any]]] = {'brewfile_entry_type': <function _to_str>, 'brewfile_skip_warning': <function _to_str>, 'cli_names': <function _to_str_tuple>, 'cli_search_path': <function _to_str_tuple>, 'default_sudo': <function _to_bool>, 'extra_env': <function _to_str_dict>, 'internal_sudo': <function _to_bool>, 'maintenance_note': <function _to_str>, 'post_args': <function _to_str_tuple>, 'pre_args': <function _to_str_tuple>, 'pre_cmds': <function _to_str_tuple>, 'requirement': <function _to_str>, 'timeout': <function _to_int>, 'unmaintained': <function _to_bool>, 'unmaintained_message': <function _to_str>, 'version_cli': <function _to_str>, 'version_cli_options': <function _to_str_tuple>, 'version_regexes': <function _to_str_tuple>}

CLI-execution attributes a definition may set, mostly reusing the override converters.

The runtime-preference fields (dry_run, ignore_auto_updates, plan, stop_on_error) are excluded: they are command-line/global concerns, not part of a manager’s identity, and resolve through the usual option precedence. unmaintained is reused from the override converters so a TOML-defined manager can flag its own upstream as abandoned (see docs/cooldown.md for the affected managers).

Seven fields are definition-only:

• brewfile_entry_type maps the manager onto a Homebrew Bundle DSL entry so its installed packages join mpm dump --brewfile exports (see brewfile_entry_type).

• brewfile_skip_warning is the message emitted when the manager’s packages are deliberately left out of such an export (see brewfile_skip_warning).

• default_sudo is the manager’s built-in escalation policy (see default_sudo). Operations marked sudo = true escalate by default, while the user’s global --no-sudo flag or a sudo override still win.

• internal_sudo marks a manager whose CLI invokes sudo itself mid-run (see internal_sudo). mpm never wraps its commands in sudo; priming instead reuses a warm credential cache for these internal escalations. See docs/sudo.md.

• maintenance_note renders a {note} admonition atop the manager’s page for a still-maintained upstream under watch (see maintenance_note).

• unmaintained_message documents an abandoned upstream, rendering a {warning} admonition and the ⚠️ table markers (see unmaintained_message).

• version_cli names an alternate binary for the version probe (see version_cli), for suites whose own binaries expose no version flag (OpenBSD’s pkg_add).

meta_package_manager.definitions.DEFINITION_IDENTITY_FIELDS: Final[frozenset[str]] = frozenset({'homepage_url', 'logo', 'name', 'operations', 'platforms'})

Top-level keys of a definition section that are not CLI-execution fields.

meta_package_manager.definitions.QUERY_OPERATIONS: Final[frozenset[str]] = frozenset({'installed', 'orphans', 'outdated', 'search'})

Operations that parse the command’s stdout into packages.

meta_package_manager.definitions.COMMAND_OPERATIONS: Final[frozenset[str]] = frozenset({'cleanup_cache', 'cleanup_orphan', 'cleanup_repair', 'doctor', 'install', 'remove', 'remove_orphan', 'sync', 'upgrade_all', 'upgrade_one'})

Operations that only run a command and produce no inventory to parse.

cleanup itself is deliberately absent: it is not an operation a manager defines anymore, but the fixed composition of the declared cleanup categories (see meta_package_manager.manager.PackageManager.cleanup()). A definition declaring it is rejected with a targeted error.

meta_package_manager.definitions.ALL_DEFINITION_OPERATIONS: Final[frozenset[str]] = frozenset({'cleanup_cache', 'cleanup_orphan', 'cleanup_repair', 'doctor', 'install', 'installed', 'orphans', 'outdated', 'remove', 'remove_orphan', 'search', 'sync', 'upgrade_all', 'upgrade_one'})

Every operation name a definition may declare.

meta_package_manager.definitions.RECOGNIZED_PARSE_FIELDS: Final[frozenset[str]] = frozenset({'installed_version', 'latest_version', 'package_id'})

Named regex groups / JSON field keys a query parser may map to a package.

meta_package_manager.definitions.REQUIRED_PARSE_FIELDS: Final[Mapping[str, frozenset[str]]] = {'installed': frozenset({'package_id'}), 'orphans': frozenset({'package_id'}), 'outdated': frozenset({'latest_version', 'package_id'}), 'search': frozenset({'package_id'})}

Parse fields each query operation must extract to be useful.

installed needs only the package ID: some tools genuinely track no per-package version (Clear Linux bundles under swupd, Cygwin listings under apt-cyg), and mpm’s package model treats the installed version as optional everywhere. outdated without a latest_version would report nothing actionable, so there the version capture stays mandatory.

meta_package_manager.definitions.OPERATION_ARG_PLACEHOLDER: Final[Mapping[str, str]] = {'install': 'package_id', 'remove': 'package_id', 'remove_orphan': 'package_id', 'upgrade_one': 'package_id'}

Placeholder each operation’s args must reference, so a value is actually passed to the CLI (a remove with no {package_id} would target nothing).

search is deliberately absent: its {query} placeholder is optional. A tool with no real search command can still declare the operation by listing its whole catalog (opkg list, swupd bundle-list --all) and letting meta_package_manager.manager.PackageManager.refiltered_search() narrow the results, mirroring the search-from-scratch augmentation some built-in managers use.

meta_package_manager.definitions.SEARCH_REFINEMENT_KEYS: Final[frozenset[str]] = frozenset({'exact_args', 'extended_args', 'id_name_only_args'})

Optional per-refinement argument templates of the search operation.

Each key holds the CLI arguments spliced into the args template — at the position of the matching {exact_args}-style marker — when the refinement is active: exact_args for an --exact search, extended_args for an --extended one, and id_name_only_args for the default ID/name-restricted mode (mpm’s --id-name-only, for tools like Chocolatey whose unrestricted search is the default and take a flag to narrow it). An inactive refinement expands its marker to nothing.

Declaring a key advertises native support for the matching mpm flag (exact_args sets the search method’s exact_support introspection attribute, either of the other two sets extended_support), which feeds the augmentations documentation. meta_package_manager.manager.PackageManager.refiltered_search() still refines the results client-side either way, exactly as for the built-in managers.

meta_package_manager.definitions.ALLOWED_ARG_PLACEHOLDERS: Final[Mapping[str, frozenset[str]]] = {'install': frozenset({'package_id'}), 'remove': frozenset({'package_id'}), 'remove_orphan': frozenset({'package_id'}), 'search': frozenset({'exact_args', 'extended_args', 'id_name_only_args', 'query'}), 'upgrade_one': frozenset({'package_id'})}

Placeholders each operation’s args may reference.

Operations absent from this mapping take no placeholder at all. Any {token} outside the operation’s set is rejected at parse time: a typoed {qeury} would otherwise reach the CLI as a literal argument and fail in silent, tool-specific ways.

meta_package_manager.definitions.ARG_PLACEHOLDER_REGEX: Final = re.compile('\\{([a-z_]+)\\}')

Match {placeholder} tokens in an operation’s args, for validation.

meta_package_manager.definitions.QUERY_OPERATION_KEYS: Final[frozenset[str]] = frozenset({'args', 'cli', 'fields', 'format', 'list_path', 'regex', 'sudo'})

Keys allowed in a query operation’s table.

cli is the same alternate-binary hook as on command operations. sudo = true marks the query as privileged, for the rare tool that gates even its read-only listings behind root (deb-get’s upgradable check); escalation then follows the usual per-manager policy.

meta_package_manager.definitions.SEARCH_OPERATION_KEYS: Final[frozenset[str]] = frozenset({'args', 'cli', 'exact_args', 'extended_args', 'fields', 'format', 'id_name_only_args', 'list_path', 'regex', 'sudo'})

Keys allowed in the search operation’s table: a query operation plus the per-refinement argument templates of SEARCH_REFINEMENT_KEYS.

meta_package_manager.definitions.COMMAND_OPERATION_KEYS: Final[frozenset[str]] = frozenset({'args', 'cli', 'sudo'})

Keys allowed in a command operation’s table.

cli names an alternate binary for this operation, resolved on the search path at call time: it lets one definition span sibling binaries (urpmq querying while urpmi installs). sudo = true marks the operation as privileged, mirroring the sudo=True flag built-in managers pass to run_cli: escalation then follows the per-manager policy (the definition’s default_sudo, overridden by the user’s --sudo/--no-sudo).

class meta_package_manager.definitions.OperationSpec(args, cli=None, sudo=False, exact_args=None, extended_args=None, id_name_only_args=None, parse_mode='none', regex=None, list_path=None, fields=None)

Bases: object

Declarative specification of one operation of a config-defined manager.

args: tuple[str, ...]

CLI arguments appended after the resolved binary, before post_args.

May embed the {package_id} and {query} placeholders, substituted at call time. {version} is intentionally unsupported: config-defined managers do not pin versions (see _make_install()).

cli: str | None = None

Alternate binary name for this operation, or None for the manager’s main cli_path.

Resolved with which() at call time, so one definition can span sibling binaries (urpmi/urpme/ urpmq, cast/dispel/gaze). The operation fails with FileNotFoundError when the binary is missing rather than silently falling back to the main CLI.

sudo: bool = False

Mark the operation as privileged, mirroring the sudo=True flag built-in managers pass to run_cli().

Escalation still follows the per-manager policy: the definition’s default_sudo, overridden by the user’s --sudo/--no-sudo. Command operations are the usual bearers; a query may also set it, for the rare tool that gates its read-only listings behind root (deb-get).

exact_args: tuple[str, ...] | None = None

Arguments spliced at the {exact_args} marker of a search’s args when an exact match is requested, or None when the tool has no native exact mode. See SEARCH_REFINEMENT_KEYS.

extended_args: tuple[str, ...] | None = None

Arguments spliced at the {extended_args} marker of a search’s args when the extended (description-reaching) mode is requested, or None when the tool has no native switch for it. See SEARCH_REFINEMENT_KEYS.

id_name_only_args: tuple[str, ...] | None = None

Arguments spliced at the {id_name_only_args} marker of a search’s args when the default ID/name-restricted mode is requested, for tools whose unrestricted search is the default (Chocolatey’s --by-id-only), or None. See SEARCH_REFINEMENT_KEYS.

parse_mode: str = 'none'

How to turn the command’s stdout into packages: "regex" (per-line named groups), "json" (structured extraction), or "none" for command-only operations that produce no inventory (install, remove, sync, …).

regex: str | None = None

Regular expression matched against each stdout line in "regex" mode.

Recognized named groups: package_id (required), installed_version and latest_version (optional). Compiled with re.MULTILINE.

list_path: str | None = None

Dotted path to the package array inside the JSON document in "json" mode.

None or empty means the document is itself the array.

fields: dict[str, str] | None = None

Mapping of recognized package field (package_id, installed_version, latest_version) to its JSON selector, in "json" mode.

A selector is a key name with an optional [N] list index (versions[0]); see JSON_FIELD_SELECTOR_REGEX.

class meta_package_manager.definitions.ManagerDefinition(manager_id, name, platforms, homepage_url, logo, cli_fields, operations)

Bases: object

A brand-new package manager declared from a [mpm.managers.<id>] section.

Produced by parse_manager_definition() after validation, consumed by build_manager_class().

manager_id: str

Manager ID, taken from the configuration section name.

name: str

Human-readable manager name.

platforms: tuple[str, ...]

Platform and group ID strings, resolved to extra_platforms.Platform members at build time.

homepage_url: str | None

Project home page, for documentation reference only.

logo: str | None

Slug of the brand mark vendored under docs/assets/managers/, or None.

cli_fields: dict[str, object]

Overridable CLI-execution attributes (cli_names, requirement, version_regexes, …), pre-coerced to their runtime types.

operations: dict[str, OperationSpec]

Declared operations keyed by name (installed, install, …).

class meta_package_manager.definitions.ConfigDrivenManager

Bases: PackageManager

Base class for managers synthesized from configuration.

Carries no operation methods on purpose: only the dynamically-created subclass returned by build_manager_class() defines the operations the user actually declared, so meta_package_manager.capabilities.implements() reports an accurate capability set. Defining an operation here would make every config-defined manager falsely advertise it.

Exists mainly as a marker (isinstance(manager, ConfigDrivenManager) distinguishes user-defined managers from built-ins) and as a shared home for any future config-driven behavior.

Initialize cli_errors list.

cli_names: tuple[str, ...] = ('configdrivenmanager',)

List of CLI names the package manager is known as.

This list of recognized CLI names is ordered by priority. That way we can influence the search of the right binary.

..hint::

This was helpful in the case of the Python transition from 2.x to 3.x, where multiple versions of the same executable were named python or python3.

By default, this property’s value is derived from the manager’s ID (see the MetaPackageManager.__init__ method above).

id: str = 'configdrivenmanager'

Package manager’s ID.

Derived by defaults from the lower-cased class name in which underscores _ are replaced by dashes -.

This ID must be unique among all package manager definitions and lower-case, as they’re used as feature flags for the mpm CLI.

name: str = 'ConfigDrivenManager'

Return package manager’s common name.

Default value is based on class name.

virtual: bool = False

Should we expose the package manager to the user?

Virtual package manager are just skeleton classes used to factorize code among managers of the same family.

definition_source: str | None = None

Repo-relative path to the bundled TOML file this manager was defined in.

Set by build_bundled_managers() for the managers mpm ships as package data; stays None for a manager defined in a user’s own configuration file. The documentation generator links a bundled manager’s benchmark entry to this file, a config-defined manager having no Python source line to point at.

meta_package_manager.definitions.parse_manager_definition(manager_id, section)

Validate and parse one [mpm.managers.<id>] definition section.

Returns a ManagerDefinition ready for build_manager_class(). Raises click_extra.ValidationError (path relative to the [mpm.managers] root) on any problem, so the same function backs both --validate-config and the runtime registration path.

Return type:

ManagerDefinition

meta_package_manager.definitions.build_manager_class(definition)

Synthesize a PackageManager subclass from a validated definition.

Assembles a class namespace from the definition’s identity and CLI fields, then adds one method (or property) per declared operation. Only the declared operations land in the namespace, so meta_package_manager.capabilities.implements() reflects exactly what the user configured. Single- and all-package upgrades map to upgrade_one_cli() / upgrade_all_cli() so the inherited upgrade() orchestrator drives them, just like the built-in managers.

Return type:

type[ConfigDrivenManager]

meta_package_manager.definitions.BUNDLED_DEFINITIONS_PACKAGE: Final[str] = 'meta_package_manager.managers'

Import package whose *.toml resources hold mpm’s bundled manager definitions.

meta_package_manager.definitions.load_bundled_definitions() → tuple[tuple[ManagerDefinition, str], ...]

Parse every bundled [mpm.managers.<id>] definition shipped as package data.

Reads each *.toml resource of BUNDLED_DEFINITIONS_PACKAGE via importlib.resources (so it works the same from an unpacked install, a zip or a Nuitka onefile), and validates every section with parse_manager_definition(). Returns (definition, source) pairs, where source is the repo-relative path used to link the manager’s documentation. Cached because the shipped files never change at runtime.

A malformed bundled file is a packaging bug, but it is logged and skipped rather than raised so one bad resource cannot break mpm startup for everyone. The hermetic test_bundled_inventory and test_bundled_registered keep the shipped files valid.

Return type:

tuple[tuple[ManagerDefinition, str], ...]

meta_package_manager.definitions.bundled_manager_ids()

IDs of the managers mpm ships as bundled configuration definitions.

Return type:

frozenset[str]

meta_package_manager.definitions.build_bundled_managers()

Instantiate every bundled definition into a live, pool-ready manager.

Each ConfigDrivenManager subclass records the TOML file it came from in ConfigDrivenManager.definition_source, so the documentation generator can link to it. Called once by meta_package_manager.pool.ManagerPool.register.

Return type:

list[PackageManager]