vcti-error-core 1.0.0__py3-none-any.whl

vcti/error/core/__init__.py

@@ -0,0 +1,25 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.error.core — exit-code mechanics: validate, combine, and resolve code mappings."""
+
+from importlib.metadata import version
+
+from .codes import MAX_EXIT_CODE, ErrorCodes, combine, error_code, validate
+from .errors import CodeCollisionError, CodeRangeError, ErrorCodesError
+from .system_error import EXCEPTION_ERRNO_MAPPING, system_error
+
+__version__ = version("vcti-error-core")
+
+__all__ = [
+    "EXCEPTION_ERRNO_MAPPING",
+    "MAX_EXIT_CODE",
+    "CodeCollisionError",
+    "CodeRangeError",
+    "ErrorCodes",
+    "ErrorCodesError",
+    "combine",
+    "error_code",
+    "system_error",
+    "validate",
+    "__version__",
+]

vcti/error/core/codes.py

@@ -0,0 +1,113 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Pure functions over exception-to-exit-code mappings.
+
+A *contract* is nothing but a read-only ``Mapping[type[BaseException],
+int]`` owned by whoever defines it — typically a contract package that
+exports the mapping and calls :func:`validate` at import time. This
+module holds no state and pre-registers nothing; applications compose
+contracts explicitly with :func:`combine` and resolve exceptions with
+:func:`error_code`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+
+from .errors import CodeCollisionError, CodeRangeError
+
+type ErrorCodes = Mapping[type[BaseException], int]
+"""An exception-to-exit-code contract: class -> code (1..255)."""
+
+#: Highest exit code that survives POSIX truncation (codes are taken
+#: modulo 256; 0 is reserved for success).
+MAX_EXIT_CODE = 255
+
+
+def validate(codes: ErrorCodes, *, claim: range | None = None) -> None:
+    """Check that ``codes`` is a well-formed exit-code contract.
+
+    Contract packages call this at import time so a malformed contract
+    fails at startup, not in an error path.
+
+    Args:
+        codes: The contract mapping to check.
+        claim: The code range this contract claims (e.g.
+            ``range(32, 64)``). When given, every code must fall inside
+            it — the mechanism that keeps separately-owned contracts
+            collision-free by allocation rather than by luck.
+
+    Raises:
+        TypeError: If a key is not an exception class or a code is not
+            an ``int`` (``bool`` is rejected explicitly — ``True`` is
+            almost certainly a bug, not exit code 1).
+        CodeRangeError: If a code is outside ``1..255`` or outside
+            ``claim``.
+    """
+    for cls, code in codes.items():
+        if not (isinstance(cls, type) and issubclass(cls, BaseException)):
+            raise TypeError(f"contract key {cls!r} is not an exception class")
+        if isinstance(code, bool) or not isinstance(code, int):
+            raise TypeError(f"exit code for {cls.__name__} must be an int, got {code!r}")
+        if not 1 <= code <= MAX_EXIT_CODE:
+            raise CodeRangeError(
+                f"exit code {code} for {cls.__name__} is outside 1..{MAX_EXIT_CODE} "
+                f"(0 is reserved for success; POSIX truncates codes modulo 256)"
+            )
+        if claim is not None and code not in claim:
+            raise CodeRangeError(
+                f"exit code {code} for {cls.__name__} is outside the claimed "
+                f"range {claim.start}..{claim.stop - 1}"
+            )
+
+
+def combine(*sets: ErrorCodes) -> ErrorCodes:
+    """Merge contract mappings into one read-only contract.
+
+    Composition is an application-startup act: an app combines the
+    contracts it speaks (its platform's, its own) into the single
+    mapping it resolves against. Later sets may repeat earlier entries
+    verbatim; they may not disagree.
+
+    Returns:
+        A read-only merged mapping.
+
+    Raises:
+        CodeCollisionError: If the same exception class is mapped to
+            two different codes.
+    """
+    merged: dict[type[BaseException], int] = {}
+    for codes in sets:
+        for cls, code in codes.items():
+            existing = merged.get(cls)
+            if existing is not None and existing != code:
+                raise CodeCollisionError(f"{cls.__name__} is mapped to both {existing} and {code}")
+            merged[cls] = code
+    return MappingProxyType(merged)
+
+
+def error_code(
+    exc: BaseException | type[BaseException],
+    codes: ErrorCodes,
+    *,
+    default: int,
+) -> int:
+    """Resolve an exception (instance or class) to its exit code.
+
+    Resolution is MRO-aware: the nearest mapped ancestor wins, so a
+    subclass of a mapped exception inherits its category instead of
+    falling through to ``default``.
+
+    Args:
+        exc: The exception instance or class to classify.
+        codes: The contract to resolve against.
+        default: Returned when no ancestor is mapped. Required — what
+            "unspecified" means is contract vocabulary, and the
+            mechanics have no opinion about it.
+    """
+    cls = exc if isinstance(exc, type) else type(exc)
+    for ancestor in cls.__mro__:
+        if ancestor in codes:
+            return codes[ancestor]
+    return default

vcti/error/core/errors.py

@@ -0,0 +1,33 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Exceptions raised by the exit-code mechanics.
+
+Catch :class:`ErrorCodesError` to handle any mechanics failure
+generically. Each leaf also inherits the closest stdlib exception so
+existing ``except ValueError`` call sites keep working.
+"""
+
+from __future__ import annotations
+
+
+class ErrorCodesError(Exception):
+    """Base class for all vcti-error-core errors."""
+
+
+class CodeRangeError(ErrorCodesError, ValueError):
+    """An exit code is outside the valid or claimed range.
+
+    Valid codes are 1..255: 0 is reserved for success, and POSIX
+    truncates exit codes modulo 256, so anything above 255 would
+    silently alias a smaller code. When a contract declares a claimed
+    range, every code must also fall inside it.
+    """
+
+
+class CodeCollisionError(ErrorCodesError, ValueError):
+    """The same exception class is mapped to two different exit codes.
+
+    Raised by ``combine()`` when contract mappings disagree about a
+    class. Several classes sharing one code is legal — codes are
+    categories — but one class must resolve to exactly one code.
+    """

vcti/error/core/system_error.py

@@ -0,0 +1,49 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Errno-correct construction of OS-level exceptions.
+
+Python's OS exceptions (``FileNotFoundError``, ``IsADirectoryError``,
+...) carry an ``errno`` when the operating system raises them — but
+``errno`` is ``None`` when they are raised programmatically, which
+breaks callers that inspect ``err.errno``. :func:`system_error` builds
+the instance the way the OS would.
+"""
+
+from __future__ import annotations
+
+import errno
+import os
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any
+
+#: OS exception class -> the errno the operating system would set.
+#: (Keyed wide as ``type[Exception]`` so lookups with arbitrary
+#: exception classes type-check; every entry is an OSError subclass.)
+EXCEPTION_ERRNO_MAPPING: Mapping[type[Exception], int] = MappingProxyType(
+    {
+        FileNotFoundError: errno.ENOENT,
+        FileExistsError: errno.EEXIST,
+        IsADirectoryError: errno.EISDIR,
+        NotADirectoryError: errno.ENOTDIR,
+        PermissionError: errno.EACCES,
+    }
+)
+
+
+def system_error(exception_class: type[Exception], *args: Any, **kwargs: Any) -> Exception:
+    """Create an exception instance carrying the appropriate errno.
+
+    Intended for ``OSError`` subclasses, whose two leading constructor
+    arguments are ``(errno, strerror)`` — further ``args`` (e.g. a
+    filename) are appended. Classes without a known errno fall back to
+    ``EINVAL``; for non-``OSError`` classes the errno pair simply lands
+    in ``args``.
+
+    Example:
+        >>> err = system_error(FileNotFoundError, "config.yaml")
+        >>> err.errno == errno.ENOENT and err.filename == "config.yaml"
+        True
+    """
+    errno_value = EXCEPTION_ERRNO_MAPPING.get(exception_class, errno.EINVAL)
+    return exception_class(errno_value, os.strerror(errno_value), *args, **kwargs)

vcti_error_core-1.0.0.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: vcti-error-core
+Version: 1.0.0
+Summary: Exit-code mechanics: validation, composition, and MRO-aware resolution of exception-to-exit-code mappings
+Author: Visual Collaboration Technologies Inc.
+License-Expression: LicenseRef-Proprietary
+Project-URL: Repository, https://github.com/vcollab/vcti-python-error-core
+Project-URL: Changelog, https://github.com/vcollab/vcti-python-error-core/blob/main/CHANGELOG.md
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy; extra == "typecheck"
+Dynamic: license-file
+
+# vcti-error-core
+
+Exit-code mechanics: validation, composition, and MRO-aware resolution of exception-to-exit-code mappings.
+
+## Overview
+
+When a Python script runs as a subprocess of a partner application, the
+process **exit code is the only reliable contract** between caller and
+callee. `vcti-error-core` provides the mechanics for that contract — and
+deliberately none of the vocabulary. A contract is plain data: a
+read-only `Mapping[type[BaseException], int]` owned by whoever defines
+it. This package validates such mappings (ranges, claims), composes them
+collision-safely, and resolves an exception to its code MRO-aware, plus
+an errno-correct constructor for OS exceptions. The actual VCollab code
+vocabularies live in [`vcti-error-contract`](https://pypi.org/project/vcti-error-contract/);
+any team can publish its own contract package on these mechanics.
+
+## Installation
+
+```bash
+pip install vcti-error-core
+```
+
+> Migrating from the retired `vcti-error` 1.x? Uninstall it first — it
+> owns `vcti/error/__init__.py`, which conflicts with this namespace
+> family. Its API lives on in `vcti.error.contract.legacy`.
+
+### In `requirements.txt`
+
+```
+vcti-error-core>=1.0.0
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-error-core>=1.0.0",
+]
+```
+
+---
+
+## Quick Start
+
+A contract is a dict; the mechanics do the rest:
+
+```python
+from vcti.error.core import combine, error_code, validate
+
+class AppError(Exception): ...
+class LicenseExpired(AppError): ...
+
+MY_CODES = {AppError: 32, LicenseExpired: 33}
+validate(MY_CODES, claim=range(32, 64))     # fail fast at startup
+
+CODES = combine({Exception: 1, FileNotFoundError: 2}, MY_CODES)
+
+def main() -> int:
+    try:
+        run()
+        return 0
+    except Exception as err:
+        return error_code(err, CODES, default=1)
+```
+
+Resolution is MRO-aware — a subclass inherits its nearest mapped
+ancestor's code (`class QuotaExceeded(LicenseExpired)` still exits 33).
+Composition is collision-safe — two contracts disagreeing about a class
+raise `CodeCollisionError` at startup, not in production log analysis.
+
+Errno-correct OS errors for programmatic raises:
+
+```python
+from vcti.error.core 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
+```
+
+---
+
+## API surface
+
+| Name | Kind | Purpose |
+|------|------|---------|
+| `ErrorCodes` | type alias | `Mapping[type[BaseException], int]` — a contract |
+| `validate(codes, *, claim)` | function | Range/type checks; `claim` enforces a contract's allocated range |
+| `combine(*sets)` | function | Read-only merge; disagreement → `CodeCollisionError` |
+| `error_code(exc, codes, *, default)` | function | MRO-aware resolution; `default` is caller-supplied |
+| `system_error(cls, *args)` | function | Errno-correct OS-exception construction |
+| `MAX_EXIT_CODE` | constant | 255 (POSIX truncates exit codes modulo 256) |
+| `ErrorCodesError` | exception | Base; `CodeRangeError`, `CodeCollisionError` |
+
+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.
+
+See [docs/design.md](docs/design.md) for the mechanics/contract split
+and [docs/extending.md](docs/extending.md) for writing a contract
+package.
+
+---
+
+## Dependencies
+
+None. Standard library only.

vcti_error_core-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+vcti/error/core/__init__.py,sha256=vkEk6FA-cIaPbzzBns-VF_1l1Zs0v3nCKR6UFZMRCg4,731
+vcti/error/core/codes.py,sha256=pynt7LmIHuF6iJ_iN8fiwqn6UQ567e4tZSxmUcARKqI,4407
+vcti/error/core/errors.py,sha256=UPyWmtpOQNH3vto9B1-B1A58ozGWDJTSCnOWkZ97uvM,1174
+vcti/error/core/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vcti/error/core/system_error.py,sha256=sUvrxCNeSE7dzeWsqLnpj_RvM75Paka581TLvRe555I,1914
+vcti_error_core-1.0.0.dist-info/licenses/LICENSE,sha256=gqRj-E4YRsT7mZ52W76LG6aTTFv6iEOK9QR_fV5EdrI,369
+vcti_error_core-1.0.0.dist-info/METADATA,sha256=6hGu84RVwoXskepEBe5mNiIsNTBm19h3cDUjSj5Ma98,4460
+vcti_error_core-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+vcti_error_core-1.0.0.dist-info/top_level.txt,sha256=Jl6AIAI3Xhru_BFQAhD_13VeXLmZQd9BqBNUaAKNgKs,5
+vcti_error_core-1.0.0.dist-info/RECORD,,

vcti_error_core-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vcti_error_core-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2018-2026 Visual Collaboration Technologies Inc.
+All Rights Reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, or use of this software, via any medium, is strictly
+prohibited. Access is granted only to authorized VCollab developers
+and individuals explicitly authorized by Visual Collaboration
+Technologies Inc.

vcti_error_core-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+vcti