API Reference

Defining checks

Upgrade checks are defined as a mapping of target versions and the checks that must pass to allow upgrading to said target version. The minimum configuration is specifying a minimum version that the application must currently be on:

from upgrade_check import UpgradeCheck, VersionRange

UPGRADE_CHECK_PATHS = {
    "2.0.0": UpgradeCheck(VersionRange(minimum="1.0.2")),
}

More advanced use cases may also specify an upper limit or a collection of version ranges that are allowed. Additionally, you can specify management commands that must complete without errors:

from upgrade_check import CommandCheck, UpgradeCheck, VersionRange

UPGRADE_CHECK_PATHS = {
    "2.0.0": UpgradeCheck(
        VersionRange(minimum="1.0.2"),
        code_checks=[
            CommandCheck("my_management_command", options={"interactive": False}),
        ],
    ),
}

Available checks

class upgrade_check.CommandCheck(command: str, *, options: dict[str, object] | None = None)

A management command and its options to call as part of the upgrade check.

Parameters:

command – Name of the management command to call.
options – Any additional keyword arguments are forwarded to the call_command call.

execute() → bool

Execute the management command.

If it doesn’t return, treat the check as success. If it raises CommandError, fail the check. Management commands are responsible for their own output.

Returns:: True indicating success, False if the check failed.

class upgrade_check.UpgradeCheck(valid_range: VersionRange | Collection[VersionRange], code_checks: Sequence[CodeCheck] = ())

Define the conditions for a valid upgrade check.

Provide either a VersionRange or a collection of version ranges to test if this check passes. The version number check passes as soon as one range satisfies the provided version.

check_version(current_version: Version) → bool

Check if the provided version is contained in any of the valid ranges.

Parameters:: current_version – The version the application is currently at.

class upgrade_check.VersionRange(minimum: str, maximum: str = '')

Describe a minimum required version and optional upper bound.

The version range bounds are inclusive. E.g. a range of 1.0.3 - 1.0.5 covers the versions 1.0.3, 1.0.4 and 1.0.5.

VersionRange instances are intended to be immutable.

maximum: str

The upper bound, optional. If unspecified, there is no upper bound.

If you specify a partial range like 2.0, anything newer than 2.0.0 will be considered out of range.

minimum: str

The minimum version, typically expressed as major.minor.patch.

You can specify partial versions like 1.1 if the exact patch version is not relevant.

Code checks

Management command checks are built-in specializations of the generic upgrade_check.constraints.CodeCheck protocol. You can define your own custom code checks and hook them up if desired.

class upgrade_check.constraints.CodeCheck(*args, **kwargs)

Run a code-based check.

The execute method must return a boolean indicating a pass (True) or fail (False). Code checks are responsible for their own error reporting to stdout/stderr.

execute() → bool