vcti-error

Shared exception classes for vcti packages, plus exception-to-exit-code contracts: the mechanics and the VCollab vocabularies.

Overview

vcti-error serves two purposes. It is the home of the shared exception classes of the vcti family (vcti.error.errors): common failure kinds such as LicenseError and ConfigError, defined once so every vcti package and application raises and catches the same class objects — no exit-code machinery involved. It also provides the exception-to-exit-code contract story: when a Python script runs as a subprocess, the one value the caller can reliably branch on is the process exit code, and making that integer mean the same thing to both sides requires an agreed vocabulary — a contract. vcti.error.mechanics validates, composes, and resolves such contracts (plain read-only Mapping[type[BaseException], int] data), and vcti.error.contract.* publishes the VCollab vocabularies as pure mappings from the shared classes to codes. The two purposes compose but don't require each other, and any team can define its own contract on the same mechanics.

Installation

pip install vcti-error

Upgrading from vcti-error 1.x: the exit-code values are preserved (in vcti.error.contract.legacy), but the Python API changed — see Migration below.

In requirements.txt

vcti-error>=2.0.0

In pyproject.toml dependencies

dependencies = [
    "vcti-error>=2.0.0",
]

Quick Start

Resolve an escaped exception to its exit code, using the codes existing applications already emit (the legacy contract):

from vcti.error.contract.legacy import exit_code

def main() -> int:
    try:
        run()
        return 0
    except Exception as err:
        return exit_code(err)      # MRO-aware; unmapped -> 1

Raise the shared exception classes — from any vcti package or application, with or without exit-code contracts:

from vcti.error.errors import ConfigError

raise ConfigError("missing required key 'output_dir'")

Composing a contract leaf with an application's own codes:

from vcti.error.contract import legacy
from vcti.error.mechanics import combine, resolve_code
from myapp.errors import CODE_MAP as APP_CODES   # your contract

CODE_MAP = combine(legacy.CODE_MAP, APP_CODES)

def main() -> int:
    try:
        run()
        return 0
    except Exception as err:
        return resolve_code(err, CODE_MAP, default=legacy.ExitCode.UNSPECIFIED)

Using the mechanics alone — a contract is a dict:

from vcti.error.mechanics import resolve_code, validate

CODE_MAP = {Exception: 1, FileNotFoundError: 2}
validate(CODE_MAP)     # fail fast at startup

sys.exit(resolve_code(err, CODE_MAP, default=1))

Errno-correct OS errors for programmatic raises:

from vcti.error.mechanics import system_error

raise system_error(FileNotFoundError, "config.yaml")
# FileNotFoundError(ENOENT, "No such file or directory", "config.yaml")
# -> err.errno / err.strerror / err.filename all set, as if the OS raised it

The three parts

The contract leaves

The two leaves are independent: they share no obligations, and nothing ties their code values together — an application speaks one contract, not both. Every leaf is just an ExitCode enum and a CODE_MAP; its exit_code() and exception_class() resolvers are produced by bind(CODE_MAP, default=...), so every leaf behaves identically and no leaf reimplements resolution. The exception classes a leaf maps live in vcti.error.errors, never in the leaf itself.

Leaf lifecycle: a leaf named <name>_draft is mutable and promises nothing; all other leaves are append-only (a released code is never reassigned or removed, though new codes may still be added within the claim). legacy is not a frozen snapshot — it grows if the existing applications it serves grow. Production code should never import a _draft leaf. See docs/design.md.

Other teams can publish their own contract leaves (or standalone contract packages) on the same mechanics — see docs/extending.md.

The mechanics (vcti.error.mechanics)

Rules baked into validate: codes are 1–255 (0 is success), stay ≤125 in practice (126+ collides with shell/signal conventions), and bool codes are rejected. The mechanics hold no state, pre-register nothing, and define no codes — not even "unspecified"; vocabulary belongs to the contract leaves.

Migration from vcti-error 1.x

The exit-code values are unchanged — callers see no difference. The Python surface changed at 2.0.0:

# before (1.x)
# from vcti.error import error_code, ExceptionType, LicenseError

# after
from vcti.error.contract.legacy import ExitCode, exit_code
from vcti.error.errors import LicenseError

• ExceptionType → ExitCode; error_code() → exit_code().
• exception_class(name) (case-insensitive string) → exception_class(code) (exit-code int → exception class). The name-based lookup is gone.
• Exception classes (LicenseError, VariableUndefined) moved to vcti.error.errors.
• system_error moved to vcti.error.mechanics.
• Resolution is now MRO-aware: exception subclasses classify to their parent's code instead of falling back to 1.

Dependencies

None. Standard library only.

Documentation