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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.