vcti-error-core 1.0.0__tar.gz

vcti_error_core-1.0.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,108 @@
+# 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/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcti-error-core"
+version = "1.0.0"
+description = "Exit-code mechanics: validation, composition, and MRO-aware resolution of exception-to-exit-code mappings"
+readme = "README.md"
+authors = [
+    {name = "Visual Collaboration Technologies Inc."}
+]
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+classifiers = [
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+requires-python = ">=3.12,<3.15"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/vcollab/vcti-python-error-core"
+Changelog = "https://github.com/vcollab/vcti-python-error-core/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["vcti.error.core", "vcti.error.core.*"]
+
+[tool.setuptools.package-data]
+"vcti.error.core" = ["py.typed"]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+lint = ["ruff"]
+typecheck = ["mypy"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=vcti.error.core --cov-report=term-missing --cov-fail-under=95"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src"]
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = ["src"]
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+exclude_also = [
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+    "@(abc\\.)?abstractmethod",
+    "\\.\\.\\.",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]

vcti_error_core-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vcti_error_core-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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-1.0.0/src/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/src/vcti_error_core.egg-info/PKG-INFO

@@ -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/src/vcti_error_core.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/vcti/error/core/__init__.py
+src/vcti/error/core/codes.py
+src/vcti/error/core/errors.py
+src/vcti/error/core/py.typed
+src/vcti/error/core/system_error.py
+src/vcti_error_core.egg-info/PKG-INFO
+src/vcti_error_core.egg-info/SOURCES.txt
+src/vcti_error_core.egg-info/dependency_links.txt
+src/vcti_error_core.egg-info/requires.txt
+src/vcti_error_core.egg-info/top_level.txt
+tests/test_codes.py
+tests/test_system_error.py
+tests/test_version.py

vcti_error_core-1.0.0/src/vcti_error_core.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vcti_error_core-1.0.0/src/vcti_error_core.egg-info/requires.txt

@@ -0,0 +1,10 @@
+
+[lint]
+ruff
+
+[test]
+pytest
+pytest-cov
+
+[typecheck]
+mypy

vcti_error_core-1.0.0/src/vcti_error_core.egg-info/top_level.txt

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

vcti_error_core-1.0.0/tests/test_codes.py

@@ -0,0 +1,136 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Tests for validate(), combine(), and error_code()."""
+
+import pytest
+
+from vcti.error.core import (
+    CodeCollisionError,
+    CodeRangeError,
+    ErrorCodesError,
+    combine,
+    error_code,
+    validate,
+)
+
+
+class AppError(Exception):
+    pass
+
+
+class LicenseExpired(AppError):
+    pass
+
+
+class TestValidate:
+    def test_valid_contract_passes(self):
+        assert validate({Exception: 1, FileNotFoundError: 2, AppError: 32}) is None
+
+    def test_empty_contract_passes(self):
+        assert validate({}) is None
+
+    def test_claim_containing_all_codes_passes(self):
+        assert validate({AppError: 32, LicenseExpired: 63}, claim=range(32, 64)) is None
+
+    def test_code_zero_raises(self):
+        with pytest.raises(CodeRangeError, match="reserved for success"):
+            validate({AppError: 0})
+
+    def test_code_above_255_raises(self):
+        with pytest.raises(CodeRangeError, match="modulo 256"):
+            validate({AppError: 256})
+
+    def test_negative_code_raises(self):
+        with pytest.raises(CodeRangeError):
+            validate({AppError: -1})
+
+    def test_code_outside_claim_raises(self):
+        with pytest.raises(CodeRangeError, match=r"outside the claimed range 32\.\.63"):
+            validate({AppError: 5}, claim=range(32, 64))
+
+    def test_bool_code_raises_type_error(self):
+        with pytest.raises(TypeError, match="must be an int"):
+            validate({AppError: True})
+
+    def test_non_int_code_raises_type_error(self):
+        with pytest.raises(TypeError, match="must be an int"):
+            validate({AppError: "2"})
+
+    def test_non_class_key_raises_type_error(self):
+        with pytest.raises(TypeError, match="not an exception class"):
+            validate({"AppError": 2})
+
+    def test_non_exception_class_key_raises_type_error(self):
+        with pytest.raises(TypeError, match="not an exception class"):
+            validate({int: 2})
+
+    def test_base_exception_subclass_is_allowed(self):
+        assert validate({KeyboardInterrupt: 130}) is None
+
+    def test_range_error_is_value_error(self):
+        with pytest.raises(ValueError):
+            validate({AppError: 0})
+        with pytest.raises(ErrorCodesError):
+            validate({AppError: 0})
+
+
+class TestCombine:
+    def test_merges_disjoint_contracts(self):
+        merged = combine({Exception: 1}, {AppError: 32})
+        assert merged == {Exception: 1, AppError: 32}
+
+    def test_result_is_read_only(self):
+        merged = combine({Exception: 1})
+        with pytest.raises(TypeError):
+            merged[AppError] = 32  # type: ignore[index]
+
+    def test_agreeing_duplicate_is_allowed(self):
+        merged = combine({Exception: 1, AppError: 32}, {AppError: 32})
+        assert merged[AppError] == 32
+
+    def test_classes_may_share_a_code(self):
+        merged = combine({AppError: 32, LicenseExpired: 32})
+        assert merged[AppError] == merged[LicenseExpired] == 32
+
+    def test_disagreeing_codes_raise(self):
+        with pytest.raises(CodeCollisionError, match="AppError is mapped to both 32 and 33"):
+            combine({AppError: 32}, {AppError: 33})
+
+    def test_no_arguments_gives_empty_contract(self):
+        assert dict(combine()) == {}
+
+    def test_inputs_are_not_mutated(self):
+        first = {Exception: 1}
+        combine(first, {AppError: 32})
+        assert first == {Exception: 1}
+
+
+class TestErrorCode:
+    CODES = {Exception: 1, FileNotFoundError: 2, AppError: 32}
+
+    def test_exact_class_match(self):
+        assert error_code(FileNotFoundError, self.CODES, default=1) == 2
+
+    def test_instance_accepted(self):
+        assert error_code(FileNotFoundError("gone"), self.CODES, default=1) == 2
+
+    def test_subclass_inherits_ancestor_code(self):
+        assert error_code(LicenseExpired, self.CODES, default=1) == 32
+
+    def test_nearest_ancestor_wins(self):
+        codes = {Exception: 1, AppError: 32, LicenseExpired: 33}
+        assert error_code(LicenseExpired, codes, default=1) == 33
+
+    def test_unmapped_falls_to_exception_when_mapped(self):
+        assert error_code(RuntimeError, self.CODES, default=99) == 1
+
+    def test_unmapped_hierarchy_returns_default(self):
+        # KeyboardInterrupt derives from BaseException, not Exception.
+        assert error_code(KeyboardInterrupt, self.CODES, default=99) == 99
+
+    def test_default_is_keyword_only_and_required(self):
+        with pytest.raises(TypeError):
+            error_code(FileNotFoundError, self.CODES)  # type: ignore[call-arg]
+
+    def test_empty_contract_returns_default(self):
+        assert error_code(AppError, {}, default=7) == 7

vcti_error_core-1.0.0/tests/test_system_error.py

@@ -0,0 +1,34 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Tests for errno-correct system error construction."""
+
+import errno
+import os
+
+import pytest
+
+from vcti.error.core import EXCEPTION_ERRNO_MAPPING, system_error
+
+
+class TestSystemError:
+    @pytest.mark.parametrize(("exception_cls", "expected_errno"), EXCEPTION_ERRNO_MAPPING.items())
+    def test_known_classes_get_their_errno(self, exception_cls, expected_errno):
+        err = system_error(exception_cls)
+        assert err.errno == expected_errno
+        assert err.strerror == os.strerror(expected_errno)
+
+    def test_filename_argument_passes_through(self):
+        err = system_error(FileNotFoundError, "/some/path")
+        assert err.errno == errno.ENOENT
+        assert err.filename == "/some/path"
+
+    def test_unknown_class_falls_back_to_einval(self):
+        class Unknown(Exception):
+            pass
+
+        err = system_error(Unknown)
+        assert err.args == (errno.EINVAL, os.strerror(errno.EINVAL))
+
+    def test_mapping_is_read_only(self):
+        with pytest.raises(TypeError):
+            EXCEPTION_ERRNO_MAPPING[OSError] = errno.EIO  # type: ignore[index]

vcti_error_core-1.0.0/tests/test_version.py

@@ -0,0 +1,15 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Version tests for vcti-error-core."""
+
+import re
+
+import vcti.error.core
+
+
+class TestVersion:
+    def test_version_exists(self):
+        assert hasattr(vcti.error.core, "__version__")
+
+    def test_version_is_valid_semver(self):
+        assert re.match(r"^\d+\.\d+\.\d+", vcti.error.core.__version__)