meta_package_manager.cooldown module

Vocabulary and resolution of the release-age cooldown gate.

The cooldown is a supply-chain safeguard with two independent axes:

• the window: the minimum age a package version must reach before it can be installed or upgraded, expressed as a duration;

• the policy: what happens to managers that cannot natively enforce an active window (CooldownPolicy).

The CLI spells both axes on the single --cooldown option (a duration, or one of the policy keywords), while the configuration file spells them as the two keys of the [mpm.cooldown] table (period and policy). Resolution (resolve_cooldown()) merges the two sources axis by axis: a value set on one side only leaves the other axis to the configuration, so –cooldown best-effort``reuses the configured window, and`–cooldown 7d` reuses the configured policy.

The gate itself (per-manager environment injection, the fail-closed skips) lives in meta_package_manager.execution and meta_package_manager.cli_maintenance.cooldown_permits(); this module only owns the input grammar and the merge rules.

meta_package_manager.cooldown.POLICY_CONFIG_KEYS = ('period', 'policy')

Recognized keys of the [mpm.cooldown] configuration table.

period carries the window as a duration string, policy one of the CooldownPolicy keywords accepted in configuration files. Kept here as the single enumeration both the parser and the error messages read.

class meta_package_manager.cooldown.CooldownPolicy(*values)

Bases: StrEnum

Enforcement posture of an active release-age cooldown window.

Only applies to managers without native release-age support; managers that can enforce the window natively always do, whatever the policy. The values double as the CLI keywords of the --cooldown option and (except off) as the policy values of the [mpm.cooldown] configuration table, so they spell exactly like the user types them.

enforce = 'enforce'

Skip the managers that cannot enforce the window (fail-closed). The default posture: nothing slips in unguarded.

best_effort = 'best-effort'

Run the managers that cannot enforce the window anyway, without the supply-chain safeguard.

off = 'off'

Disable the gate entirely for this run, on every manager. A CLI-only keyword, equivalent to a 0 duration: the configuration expresses the same state with period = "0" (or no period at all).

class meta_package_manager.cooldown.Cooldown

Bases: ParamType

Parse the --cooldown value: a window duration or a policy keyword.

Returns a datetime.timedelta for a duration, a CooldownPolicy for a keyword (0 collapses to CooldownPolicy.off, matching the “zero disables the gate” rule of click-extra’s Duration), and None for an empty value, which reads as “unspecified”: resolution then inherits both axes from the configuration.

name: str = 'cooldown'

the descriptive name of this type

convert(value, param, ctx)

Coerce value to a window, a policy, or None (unspecified).

Already-parsed values flow through untouched so defaults and re-processing stay idempotent.

Return type:

timedelta | CooldownPolicy | None

class meta_package_manager.cooldown.CooldownSettings(duration, policy, legacy=False)

Bases: object

The cooldown axes carried by the configuration, before merging.

An axis left unset is None: resolution substitutes the default only after the CLI flag had a chance to override the other axis.

duration: timedelta | None

The configured window (period key), or None when unset or zero.

policy: CooldownPolicy | None

The configured posture (policy key), or None when unset.

legacy: bool = False

Whether the section used the deprecated [mpm] cooldown = "<duration>" top-level string spelling, accepted as the window for one migration window.

meta_package_manager.cooldown.parse_policy_token(token)

Map token to a CooldownPolicy, case-insensitively.

Returns None when the token names no policy, so callers decide how to report the miss.

Return type:

CooldownPolicy | None

meta_package_manager.cooldown.parse_cooldown_section(section)

Parse the [mpm.cooldown] configuration section into settings.

Accepts the table shape (period and policy keys) and, as a migration aid, the deprecated top-level string spelling, read as the window. Pure parsing: no logging, so the load-time validator and the runtime resolution can share it without duplicated diagnostics.

Raises:

• ValueError – on an unknown key, an unparsable period, a policy that is not enforce or best-effort (off is a CLI-only keyword), or a policy without a period, which would be a standing no-op gate.

• TypeError – when the section is neither a table nor a string.

Return type:

CooldownSettings

meta_package_manager.cooldown.resolve_cooldown(flag, settings)

Merge the parsed --cooldown flag with the configuration settings.

Axis-by-axis precedence: a flag duration overrides the configured window but inherits the configured policy; a flag policy overrides the configured policy but inherits the configured window (off forces the window off too); an unset flag inherits both axes. Returns the effective (window, policy) pair, the policy defaulted to CooldownPolicy.enforce when neither side sets it.

Return type:

tuple[timedelta | None, CooldownPolicy]