Skip to main content

vcti-error

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

Overview

vcti-error provides two features, usable together or separately. Shared exception classes (vcti.error.errors) are a common set of exception types, such as ConfigError and LicenseError, so an error raised in one vcti package can be caught by the same class in another. Exit-code contracts decide which exit code a program returns for the exception that ended it, so a caller that runs the program as a subprocess can tell from the exit code what went wrong. A contract is a mapping from exception classes to exit codes: vcti.error.contract provides ready-made VCollab contracts, and vcti.error.mechanics provides the functions that check, combine and apply any contract, including your own.

Installation

pip install vcti-error

In requirements.txt

vcti-error>=2.0.2

In pyproject.toml dependencies

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

Quick Start

Shared exception classes

Raise a shared class where the failure happens; catch it by the same class anywhere:

from vcti.error.errors import ConfigError


def load(config: dict[str, str]) -> None:
    if "output_dir" not in config:
        raise ConfigError("missing required key 'output_dir'")


try:
    load({})
except ConfigError as err:
    print(f"configuration problem: {err}")

Exit-code contracts

Return the exit code a provided contract assigns to whatever exception ended the program:

import sys

from vcti.error.contract.legacy import exit_code


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


if __name__ == "__main__":
    sys.exit(main())

Add your program's own codes to a provided contract:

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

CODE_MAP = combine(legacy.CODE_MAP, APP_CODES)   # raises if both map one class differently


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

Or define a contract as a plain dictionary:

import sys

from vcti.error.mechanics import resolve_code, validate

CODE_MAP = {FileNotFoundError: 2, PermissionError: 3}
validate(CODE_MAP)   # every code an int in 1..255

try:
    run()
except Exception as err:
    sys.exit(resolve_code(err, CODE_MAP, default=1))

OS errors with errno set

system_error() builds an OS exception the way the operating system would, with errno, strerror and filename filled in:

from vcti.error.mechanics import system_error

err = system_error(FileNotFoundError, "config.yaml")
# err.errno == errno.ENOENT, err.filename == "config.yaml"

Shared exception classes (vcti.error.errors)

Class Raise when
ConfigError Configuration is invalid or missing
DataFormatError Input data does not match the expected format
LicenseError License validation fails
VariableUndefined An undefined workflow variable is referenced

Each class derives directly from Exception; subclass one to describe a more specific failure. A class has no exit code of its own — each contract decides which code, if any, it maps the class to.


Exit-code contracts

How a contract resolves an exception

A contract is a read-only mapping from exception classes to exit codes. Resolution follows the exception's class hierarchy: the nearest mapped base class decides the code, so a class QuotaExceeded(LicenseError) gets LicenseError's code. An exception with nothing mapped in its hierarchy gets the contract's default, its UNSPECIFIED code. A program uses one contract; the provided contracts number their codes independently.

Provided contracts (vcti.error.contract)

Module Codes Stability
vcti.error.contract.legacy UNSPECIFIED(1), FILE_NOT_FOUND(2), LICENSE_ERROR(3), KEY_ERROR(4), VARIABLE_UNDEFINED(5) Stable — a released code never changes; new codes may be added within 1–5
vcti.error.contract.base_draft 11 codes within 1–63, among them INVALID_INPUT, PERMISSION_DENIED, CONFIG_ERROR, DATA_FORMAT_ERROR Draft — may change in any release; not for production use

Every contract module exposes the same four names:

Name Purpose
ExitCode IntEnum of the contract's codes
CODE_MAP The read-only class → code mapping
exit_code(exc) Exception (instance or class) → exit code
exception_class(code) Exit code → exception class (Exception if unmapped)

To publish a contract of your own, see docs/extending.md.

Mechanics (vcti.error.mechanics)

Name Kind Purpose
CodeMap type alias Mapping[type[BaseException], int] — a contract
validate(code_map, *, claim) function Checks keys and codes; claim limits codes to a declared range
combine(*code_maps) function Read-only merge; one class mapped to two codes → CodeCollisionError
resolve_code(exc, code_map, *, default) function Exception → code, by class hierarchy; default when nothing matches
resolve_class(code, code_map, *, default=Exception) function Code → exception class (one class if several share a code)
bind(code_map, *, default) function Returns the (exit_code, exception_class) pair for a contract
system_error(cls, *args) function Builds an OS exception with the matching errno
ERRNO_MAP constant Read-only OS-exception → errno table used by system_error
MAX_EXIT_CODE constant 255, the highest exit code a process can report
CodeMapError exception Base of CodeRangeError and CodeCollisionError

validate() accepts codes 1–255 — 0 means success, and the operating system keeps only the low 8 bits, so 256 would arrive as 0 — and rejects bool codes. Keep codes at or below 125: shells and process tools reserve 126 and above.


Dependencies

None. Standard library only.


Documentation

If you want to… Read
Get started using the package Quick Start above
Understand the architecture and the design decisions docs/design.md
Navigate and understand the source docs/source-guide.md
See practical, real-world usage docs/patterns.md
Extend the library (add a shared class or a contract) docs/extending.md

Metadata

Release files for vcti-error 2.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for vcti-error 2.0.2
File Size Uploaded Provenance Actions
vcti_error-2.0.2.tar.gz 26.4 kB With provenance Details for vcti_error-2.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vcti-error 2.0.2
File Interpreter ABI Platform Actions
vcti_error-2.0.2-py3-none-any.whl Python 3 none any Details for vcti_error-2.0.2-py3-none-any.whl

Total release size: 41.5 kB

Release files / vcti_error-2.0.2.tar.gz

Download URL vcti_error-2.0.2.tar.gz
Size 26.4 kB
Tags Source
SHA-256 checksum
How to use checksums
4d0d831cde448f4146a630523d5783b94fe2ca643e1f8a2ff4a3434e68017e77
BLAKE2b-256 checksum
How to use checksums
af8c0d519afc22df9787620a9bc238207b838769724600b6155f2e67a63ba2d4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / vcti_error-2.0.2-py3-none-any.whl

Download URL vcti_error-2.0.2-py3-none-any.whl
Size 15.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a7fd8237bf338110d3923059c7348a3861a4aaf502c4c453fb351e5143f96d4d
BLAKE2b-256 checksum
How to use checksums
bf4019d8e658d6af1a33c36a9763d388cfe677338710641866e8a31ac038b561
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for vcti-error 2.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for vcti_error-2.0.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page