vcti-error 1.0.4__tar.gz

vcti_error-1.0.4/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-1.0.4/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: vcti-error
+Version: 1.0.4
+Summary: Structured exception handling and error classification for Python
+Author: Visual Collaboration Technologies Inc.
+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"
+Dynamic: license-file
+
+# Error Framework
+
+## Purpose
+
+VCollab Python scripts are typically invoked by partner programs or
+external applications. When a script finishes, the invoking application
+needs to know what happened — did it succeed, fail due to a missing
+file, a license issue, or something unexpected?
+
+In standard subprocess semantics, the **exit code is the only reliable
+contract** between caller and callee. The `vcti-error` package
+formalizes this contract by ensuring that every known exception type
+maps to a stable, unique integer exit code — consistent across all
+VCollab applications.
+
+This package has **zero external dependencies**.
+
+### When to use this package
+
+Use `vcti-error` when your Python script is invoked as a **subprocess** by
+a partner application (e.g., VCollab Presenter, an external scheduler, or
+a CI pipeline) and the caller interprets the process exit code to decide
+what happened. If your code runs inside a larger Python process where
+exceptions propagate normally, you likely don't need this package.
+
+---
+
+## Installation
+
+```bash
+# Latest main branch
+pip install git+https://github.com/vcollab/vcti-python-error.git
+
+# Specific version
+pip install git+https://github.com/vcollab/vcti-python-error.git@v1.0.4
+```
+
+### From a GitHub Release
+
+Download the wheel from the
+[Releases](https://github.com/vcollab/vcti-python-error/releases)
+page and install directly:
+
+```bash
+pip install vcti_error-1.0.4-py3-none-any.whl
+```
+
+### In `requirements.txt`
+
+```
+vcti-error @ git+https://github.com/vcollab/vcti-python-error.git@v1.0.4
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-error @ git+https://github.com/vcollab/vcti-python-error.git@v1.0.4",
+]
+```
+
+---
+
+## Quick Start
+
+### The main() pattern
+
+All CLI entry points follow this structure:
+
+```python
+import logging
+import traceback
+from vcti.error import error_code
+
+logger = logging.getLogger(__name__)
+
+def main() -> int:
+    try:
+        cli_app()
+        return 0
+    except Exception as error:
+        logger.error("Error: %s", error)
+        traceback.print_exc()
+        return error_code(type(error))
+```
+
+- `0` — success
+- `!= 0` — failure (category encoded in exit code)
+- `error_code(type(error))` — resolves exception class to exit code
+- Unmapped exceptions fall back to `UNSPECIFIED` (exit code 1)
+
+### Look up exit codes
+
+```python
+from vcti.error import error_code
+
+error_code(FileNotFoundError)   # 2
+error_code(KeyError)            # 4
+error_code(RuntimeError)        # 1 (UNSPECIFIED fallback)
+```
+
+### Resolve exception class by name
+
+```python
+from vcti.error import exception_class
+
+exception_class("file_not_found")       # FileNotFoundError
+exception_class("variable_undefined")   # VariableUndefined
+exception_class("unknown_name")         # Exception (fallback)
+```
+
+### Create system errors with errno
+
+```python
+from vcti.error import system_error
+
+err = system_error(FileNotFoundError, "path/to/file")
+# FileNotFoundError(errno.ENOENT, "No such file or directory", "path/to/file")
+raise err
+```
+
+---
+
+## Registered Exception Types
+
+| Exception type | Exit code | Python class | Description |
+|----------------|-----------|-------------|-------------|
+| `UNSPECIFIED` | 1 | `Exception` | Fallback for unmapped exceptions |
+| `FILE_NOT_FOUND` | 2 | `FileNotFoundError` | Expected file not found |
+| `LICENSE_ERROR` | 3 | `LicenseError` | License validation failed |
+| `KEY_ERROR` | 4 | `KeyError` | Missing key or identifier |
+| `VARIABLE_UNDEFINED` | 5 | `VariableUndefined` | Undefined workflow variable |
+
+**Stability guarantee:** Exit code values are part of the external
+contract with partner applications. Once assigned, a value must never
+be changed or reused.
+
+---
+
+## Public API
+
+| Function | Purpose |
+|----------|---------|
+| `error_code(exception_class)` | Returns exit code for an exception class |
+| `exception_class(name)` | Resolves exception type name to Python class (case-insensitive) |
+| `system_error(exception_class, *args)` | Creates exception with appropriate errno |
+
+---
+
+## Documentation
+
+- [Changelog](CHANGELOG.md) — Release history and versioning policy
+- [Design](docs/design.md) — Architecture decisions and mapping pipeline
+- [Source Guide](docs/source-guide.md) — File descriptions and execution flow traces
+- [Extension Guide](docs/extending.md) — How to add new exception types
+- [API Reference](docs/api.md) — Autodoc for all modules

vcti_error-1.0.4/README.md

@@ -0,0 +1,156 @@
+# Error Framework
+
+## Purpose
+
+VCollab Python scripts are typically invoked by partner programs or
+external applications. When a script finishes, the invoking application
+needs to know what happened — did it succeed, fail due to a missing
+file, a license issue, or something unexpected?
+
+In standard subprocess semantics, the **exit code is the only reliable
+contract** between caller and callee. The `vcti-error` package
+formalizes this contract by ensuring that every known exception type
+maps to a stable, unique integer exit code — consistent across all
+VCollab applications.
+
+This package has **zero external dependencies**.
+
+### When to use this package
+
+Use `vcti-error` when your Python script is invoked as a **subprocess** by
+a partner application (e.g., VCollab Presenter, an external scheduler, or
+a CI pipeline) and the caller interprets the process exit code to decide
+what happened. If your code runs inside a larger Python process where
+exceptions propagate normally, you likely don't need this package.
+
+---
+
+## Installation
+
+```bash
+# Latest main branch
+pip install git+https://github.com/vcollab/vcti-python-error.git
+
+# Specific version
+pip install git+https://github.com/vcollab/vcti-python-error.git@v1.0.4
+```
+
+### From a GitHub Release
+
+Download the wheel from the
+[Releases](https://github.com/vcollab/vcti-python-error/releases)
+page and install directly:
+
+```bash
+pip install vcti_error-1.0.4-py3-none-any.whl
+```
+
+### In `requirements.txt`
+
+```
+vcti-error @ git+https://github.com/vcollab/vcti-python-error.git@v1.0.4
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-error @ git+https://github.com/vcollab/vcti-python-error.git@v1.0.4",
+]
+```
+
+---
+
+## Quick Start
+
+### The main() pattern
+
+All CLI entry points follow this structure:
+
+```python
+import logging
+import traceback
+from vcti.error import error_code
+
+logger = logging.getLogger(__name__)
+
+def main() -> int:
+    try:
+        cli_app()
+        return 0
+    except Exception as error:
+        logger.error("Error: %s", error)
+        traceback.print_exc()
+        return error_code(type(error))
+```
+
+- `0` — success
+- `!= 0` — failure (category encoded in exit code)
+- `error_code(type(error))` — resolves exception class to exit code
+- Unmapped exceptions fall back to `UNSPECIFIED` (exit code 1)
+
+### Look up exit codes
+
+```python
+from vcti.error import error_code
+
+error_code(FileNotFoundError)   # 2
+error_code(KeyError)            # 4
+error_code(RuntimeError)        # 1 (UNSPECIFIED fallback)
+```
+
+### Resolve exception class by name
+
+```python
+from vcti.error import exception_class
+
+exception_class("file_not_found")       # FileNotFoundError
+exception_class("variable_undefined")   # VariableUndefined
+exception_class("unknown_name")         # Exception (fallback)
+```
+
+### Create system errors with errno
+
+```python
+from vcti.error import system_error
+
+err = system_error(FileNotFoundError, "path/to/file")
+# FileNotFoundError(errno.ENOENT, "No such file or directory", "path/to/file")
+raise err
+```
+
+---
+
+## Registered Exception Types
+
+| Exception type | Exit code | Python class | Description |
+|----------------|-----------|-------------|-------------|
+| `UNSPECIFIED` | 1 | `Exception` | Fallback for unmapped exceptions |
+| `FILE_NOT_FOUND` | 2 | `FileNotFoundError` | Expected file not found |
+| `LICENSE_ERROR` | 3 | `LicenseError` | License validation failed |
+| `KEY_ERROR` | 4 | `KeyError` | Missing key or identifier |
+| `VARIABLE_UNDEFINED` | 5 | `VariableUndefined` | Undefined workflow variable |
+
+**Stability guarantee:** Exit code values are part of the external
+contract with partner applications. Once assigned, a value must never
+be changed or reused.
+
+---
+
+## Public API
+
+| Function | Purpose |
+|----------|---------|
+| `error_code(exception_class)` | Returns exit code for an exception class |
+| `exception_class(name)` | Resolves exception type name to Python class (case-insensitive) |
+| `system_error(exception_class, *args)` | Creates exception with appropriate errno |
+
+---
+
+## Documentation
+
+- [Changelog](CHANGELOG.md) — Release history and versioning policy
+- [Design](docs/design.md) — Architecture decisions and mapping pipeline
+- [Source Guide](docs/source-guide.md) — File descriptions and execution flow traces
+- [Extension Guide](docs/extending.md) — How to add new exception types
+- [API Reference](docs/api.md) — Autodoc for all modules

vcti_error-1.0.4/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcti-error"
+version = "1.0.4"
+description = "Structured exception handling and error classification for Python"
+readme = "README.md"
+authors = [
+    {name = "Visual Collaboration Technologies Inc."}
+]
+requires-python = ">=3.12,<3.15"
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+lint = ["ruff"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["vcti.error", "vcti.error.*"]
+
+[tool.setuptools]
+zip-safe = true
+
+[tool.pytest.ini_options]
+addopts = "--cov=vcti.error --cov-report=term-missing --cov-fail-under=95"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]

vcti_error-1.0.4/setup.cfg

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

vcti_error-1.0.4/src/vcti/error/__init__.py

@@ -0,0 +1,24 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Error handling framework for custom and system exceptions.
+
+This package provides a framework for defining custom exceptions, mapping them to error codes,
+and handling system errors with errno integration.
+"""
+
+from importlib.metadata import version
+
+__version__ = version("vcti-error")
+
+from .custom_exceptions import *
+from .system_error import system_error
+from .utils import *
+
+__all__ = [
+    "__version__",
+    "error_code",
+    "exception_class",
+    "system_error",
+    "LicenseError",
+    "VariableUndefined",
+]

vcti_error-1.0.4/src/vcti/error/custom_exceptions.py

@@ -0,0 +1,13 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Custom exception classes for the VCTI error framework."""
+
+__all__ = ["LicenseError", "VariableUndefined"]
+
+
+class LicenseError(Exception):
+    """Raised when license validation fails."""
+
+
+class VariableUndefined(Exception):
+    """Raised when an undefined workflow variable is referenced."""

vcti_error-1.0.4/src/vcti/error/exception_mappings.py

@@ -0,0 +1,41 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Defines mappings between exception types, classes, and system errors."""
+
+import errno
+from types import MappingProxyType
+
+from .custom_exceptions import LicenseError, VariableUndefined
+from .exception_type import ExceptionType
+
+# The single authoritative mapping: enum → Python class.
+# All other mappings are derived from this.
+EXCEPTION_TYPE_TO_CLASS: MappingProxyType = MappingProxyType(
+    {
+        ExceptionType.UNSPECIFIED: Exception,
+        ExceptionType.FILE_NOT_FOUND: FileNotFoundError,
+        ExceptionType.LICENSE_ERROR: LicenseError,
+        ExceptionType.KEY_ERROR: KeyError,
+        ExceptionType.VARIABLE_UNDEFINED: VariableUndefined,
+    }
+)
+
+# Map lowercase exception names to their corresponding exception types
+EXCEPTION_NAME_TO_TYPE: MappingProxyType = MappingProxyType(
+    {et.name.lower(): et for et in EXCEPTION_TYPE_TO_CLASS}
+)
+
+# Map exception classes to their corresponding error codes
+EXCEPTION_CLASS_TO_ERROR_CODE: MappingProxyType = MappingProxyType(
+    {cls: et.value for et, cls in EXCEPTION_TYPE_TO_CLASS.items()}
+)
+
+# Map system exceptions to their corresponding errno values
+EXCEPTION_ERRNO_MAPPING: MappingProxyType = MappingProxyType(
+    {
+        FileNotFoundError: errno.ENOENT,
+        FileExistsError: errno.EEXIST,
+        IsADirectoryError: errno.EISDIR,
+        NotADirectoryError: errno.ENOTDIR,
+    }
+)

vcti_error-1.0.4/src/vcti/error/exception_type.py

@@ -0,0 +1,35 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Defines standard exception types using an enumeration.
+
+WARNING: These integer values are part of the external contract with partner
+applications. They are used as process exit codes and must remain stable
+across releases. Never reuse or reassign an existing value. When adding a
+new entry, assign the next available integer. When removing an entry, leave
+a gap — do not renumber remaining entries.
+"""
+
+from enum import IntEnum
+
+
+class ExceptionType(IntEnum):
+    """
+    Enumeration of exception types.
+
+    Each value is a stable exit code communicated to partner applications.
+    Do not change existing values — they are part of the external contract.
+    To add a new entry, assign the next available integer after the last one.
+
+    Attributes:
+        UNSPECIFIED: Represents an unspecified error.
+        FILE_NOT_FOUND: File not found error.
+        LICENSE_ERROR: License-related error.
+        KEY_ERROR: Key-related error.
+        VARIABLE_UNDEFINED: Undefined variable error.
+    """
+
+    UNSPECIFIED = 1
+    FILE_NOT_FOUND = 2
+    LICENSE_ERROR = 3
+    KEY_ERROR = 4
+    VARIABLE_UNDEFINED = 5

vcti_error-1.0.4/src/vcti/error/system_error.py

@@ -0,0 +1,24 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Provides an interface for handling system errors with errno integration."""
+
+import errno
+import os
+
+from .exception_mappings import EXCEPTION_ERRNO_MAPPING
+
+
+def system_error(exception_class: type[Exception], *args, **kwargs) -> Exception:
+    """
+    Creates an instance of the specified exception class with an appropriate errno value.
+
+    Args:
+        exception_class (type): The exception class to instantiate.
+        *args: Additional positional arguments.
+        **kwargs: Additional keyword arguments.
+
+    Returns:
+        Exception: An instance of the specified exception class.
+    """
+    errno_value = EXCEPTION_ERRNO_MAPPING.get(exception_class, errno.EINVAL)
+    return exception_class(errno_value, os.strerror(errno_value), *args, **kwargs)

vcti_error-1.0.4/src/vcti/error/utils.py

@@ -0,0 +1,41 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Utility functions for retrieving exception details."""
+
+__all__ = ["error_code", "exception_class"]
+
+from .exception_mappings import (
+    EXCEPTION_CLASS_TO_ERROR_CODE,
+    EXCEPTION_NAME_TO_TYPE,
+    EXCEPTION_TYPE_TO_CLASS,
+)
+from .exception_type import ExceptionType
+
+
+def exception_class(exception_type_name: str) -> type:
+    """
+    Retrieves the exception class corresponding to a given exception type name.
+
+    Args:
+        exception_type_name (str): Name of the exception type (case-insensitive).
+
+    Returns:
+        type: Corresponding exception class, or `Exception` if not found.
+    """
+    exception_type = EXCEPTION_NAME_TO_TYPE.get(exception_type_name.lower())
+    if exception_type is None:
+        return Exception
+    return EXCEPTION_TYPE_TO_CLASS.get(exception_type, Exception)
+
+
+def error_code(exception_cls: type) -> int:
+    """
+    Retrieves the error code corresponding to a given exception class.
+
+    Args:
+        exception_cls (type): The exception class.
+
+    Returns:
+        int: Corresponding error code, or `ExceptionType.UNSPECIFIED.value` if not found.
+    """
+    return EXCEPTION_CLASS_TO_ERROR_CODE.get(exception_cls, ExceptionType.UNSPECIFIED.value)

vcti_error-1.0.4/src/vcti_error.egg-info/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: vcti-error
+Version: 1.0.4
+Summary: Structured exception handling and error classification for Python
+Author: Visual Collaboration Technologies Inc.
+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"
+Dynamic: license-file
+
+# Error Framework
+
+## Purpose
+
+VCollab Python scripts are typically invoked by partner programs or
+external applications. When a script finishes, the invoking application
+needs to know what happened — did it succeed, fail due to a missing
+file, a license issue, or something unexpected?
+
+In standard subprocess semantics, the **exit code is the only reliable
+contract** between caller and callee. The `vcti-error` package
+formalizes this contract by ensuring that every known exception type
+maps to a stable, unique integer exit code — consistent across all
+VCollab applications.
+
+This package has **zero external dependencies**.
+
+### When to use this package
+
+Use `vcti-error` when your Python script is invoked as a **subprocess** by
+a partner application (e.g., VCollab Presenter, an external scheduler, or
+a CI pipeline) and the caller interprets the process exit code to decide
+what happened. If your code runs inside a larger Python process where
+exceptions propagate normally, you likely don't need this package.
+
+---
+
+## Installation
+
+```bash
+# Latest main branch
+pip install git+https://github.com/vcollab/vcti-python-error.git
+
+# Specific version
+pip install git+https://github.com/vcollab/vcti-python-error.git@v1.0.4
+```
+
+### From a GitHub Release
+
+Download the wheel from the
+[Releases](https://github.com/vcollab/vcti-python-error/releases)
+page and install directly:
+
+```bash
+pip install vcti_error-1.0.4-py3-none-any.whl
+```
+
+### In `requirements.txt`
+
+```
+vcti-error @ git+https://github.com/vcollab/vcti-python-error.git@v1.0.4
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-error @ git+https://github.com/vcollab/vcti-python-error.git@v1.0.4",
+]
+```
+
+---
+
+## Quick Start
+
+### The main() pattern
+
+All CLI entry points follow this structure:
+
+```python
+import logging
+import traceback
+from vcti.error import error_code
+
+logger = logging.getLogger(__name__)
+
+def main() -> int:
+    try:
+        cli_app()
+        return 0
+    except Exception as error:
+        logger.error("Error: %s", error)
+        traceback.print_exc()
+        return error_code(type(error))
+```
+
+- `0` — success
+- `!= 0` — failure (category encoded in exit code)
+- `error_code(type(error))` — resolves exception class to exit code
+- Unmapped exceptions fall back to `UNSPECIFIED` (exit code 1)
+
+### Look up exit codes
+
+```python
+from vcti.error import error_code
+
+error_code(FileNotFoundError)   # 2
+error_code(KeyError)            # 4
+error_code(RuntimeError)        # 1 (UNSPECIFIED fallback)
+```
+
+### Resolve exception class by name
+
+```python
+from vcti.error import exception_class
+
+exception_class("file_not_found")       # FileNotFoundError
+exception_class("variable_undefined")   # VariableUndefined
+exception_class("unknown_name")         # Exception (fallback)
+```
+
+### Create system errors with errno
+
+```python
+from vcti.error import system_error
+
+err = system_error(FileNotFoundError, "path/to/file")
+# FileNotFoundError(errno.ENOENT, "No such file or directory", "path/to/file")
+raise err
+```
+
+---
+
+## Registered Exception Types
+
+| Exception type | Exit code | Python class | Description |
+|----------------|-----------|-------------|-------------|
+| `UNSPECIFIED` | 1 | `Exception` | Fallback for unmapped exceptions |
+| `FILE_NOT_FOUND` | 2 | `FileNotFoundError` | Expected file not found |
+| `LICENSE_ERROR` | 3 | `LicenseError` | License validation failed |
+| `KEY_ERROR` | 4 | `KeyError` | Missing key or identifier |
+| `VARIABLE_UNDEFINED` | 5 | `VariableUndefined` | Undefined workflow variable |
+
+**Stability guarantee:** Exit code values are part of the external
+contract with partner applications. Once assigned, a value must never
+be changed or reused.
+
+---
+
+## Public API
+
+| Function | Purpose |
+|----------|---------|
+| `error_code(exception_class)` | Returns exit code for an exception class |
+| `exception_class(name)` | Resolves exception type name to Python class (case-insensitive) |
+| `system_error(exception_class, *args)` | Creates exception with appropriate errno |
+
+---
+
+## Documentation
+
+- [Changelog](CHANGELOG.md) — Release history and versioning policy
+- [Design](docs/design.md) — Architecture decisions and mapping pipeline
+- [Source Guide](docs/source-guide.md) — File descriptions and execution flow traces
+- [Extension Guide](docs/extending.md) — How to add new exception types
+- [API Reference](docs/api.md) — Autodoc for all modules

vcti_error-1.0.4/src/vcti_error.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/vcti/error/__init__.py
+src/vcti/error/custom_exceptions.py
+src/vcti/error/exception_mappings.py
+src/vcti/error/exception_type.py
+src/vcti/error/py.typed
+src/vcti/error/system_error.py
+src/vcti/error/utils.py
+src/vcti_error.egg-info/PKG-INFO
+src/vcti_error.egg-info/SOURCES.txt
+src/vcti_error.egg-info/dependency_links.txt
+src/vcti_error.egg-info/requires.txt
+src/vcti_error.egg-info/top_level.txt
+src/vcti_error.egg-info/zip-safe
+tests/test_exceptions.py

vcti_error-1.0.4/src/vcti_error.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vcti_error-1.0.4/src/vcti_error.egg-info/requires.txt

@@ -0,0 +1,7 @@
+
+[lint]
+ruff
+
+[test]
+pytest
+pytest-cov

vcti_error-1.0.4/src/vcti_error.egg-info/top_level.txt

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

vcti_error-1.0.4/src/vcti_error.egg-info/zip-safe

@@ -0,0 +1 @@
+

vcti_error-1.0.4/tests/test_exceptions.py

@@ -0,0 +1,160 @@
+import errno
+import os
+import re
+
+import pytest
+
+import vcti.error
+from vcti.error.exception_mappings import (
+    EXCEPTION_CLASS_TO_ERROR_CODE,
+    EXCEPTION_ERRNO_MAPPING,
+    EXCEPTION_NAME_TO_TYPE,
+    EXCEPTION_TYPE_TO_CLASS,
+)
+from vcti.error.exception_type import ExceptionType
+from vcti.error.system_error import system_error
+from vcti.error.utils import error_code, exception_class
+
+
+class TestPublicAPI:
+    """Tests for package public API surface."""
+
+    def test_version_exists(self):
+        """Ensure __version__ is defined."""
+        assert hasattr(vcti.error, "__version__")
+
+    def test_version_is_valid_semver(self):
+        """Ensure __version__ matches a valid version pattern."""
+        assert re.match(r"^\d+\.\d+\.\d+", vcti.error.__version__)
+
+    def test_all_exports(self):
+        """Ensure __all__ lists exactly the documented public API."""
+        expected = {
+            "__version__",
+            "error_code",
+            "exception_class",
+            "system_error",
+            "LicenseError",
+            "VariableUndefined",
+        }
+        assert set(vcti.error.__all__) == expected
+
+
+class TestMappingImmutability:
+    """Tests that mapping dictionaries are read-only at runtime."""
+
+    @pytest.mark.parametrize(
+        "mapping",
+        [
+            EXCEPTION_TYPE_TO_CLASS,
+            EXCEPTION_NAME_TO_TYPE,
+            EXCEPTION_CLASS_TO_ERROR_CODE,
+            EXCEPTION_ERRNO_MAPPING,
+        ],
+    )
+    def test_mapping_is_immutable(self, mapping):
+        """Ensure mappings raise TypeError on mutation attempts."""
+        with pytest.raises(TypeError):
+            mapping["__test__"] = None
+
+
+class TestCustomExceptions:
+    """Tests for custom exception classes."""
+
+    @pytest.mark.parametrize("exception_cls", EXCEPTION_TYPE_TO_CLASS.values())
+    def test_exception_creation(self, exception_cls):
+        """Ensure custom exceptions exist and inherit from `Exception`."""
+        assert issubclass(exception_cls, Exception)
+        assert isinstance(exception_cls(), exception_cls)
+
+    def test_custom_exceptions_importable_from_package(self):
+        """Ensure custom exceptions are importable from the public package path."""
+        from vcti.error import LicenseError, VariableUndefined
+
+        assert issubclass(LicenseError, Exception)
+        assert issubclass(VariableUndefined, Exception)
+
+    def test_exception_with_custom_message(self):
+        """Ensure custom exceptions accept custom messages."""
+        custom_message = "Custom error message"
+        exception_cls = EXCEPTION_TYPE_TO_CLASS[ExceptionType.LICENSE_ERROR]
+        ex = exception_cls(custom_message)
+        assert str(ex) == custom_message
+
+
+class TestErrorCodeMappings:
+    """Tests for exception-to-error-code mappings."""
+
+    @pytest.mark.parametrize("exception_cls,expected_code", EXCEPTION_CLASS_TO_ERROR_CODE.items())
+    def test_error_code_mapping(self, exception_cls, expected_code):
+        """Ensure correct error codes are assigned to exception classes."""
+        assert error_code(exception_cls) == expected_code
+
+    @pytest.mark.parametrize(
+        "builtin_exception,expected_code",
+        [
+            (FileNotFoundError, ExceptionType.FILE_NOT_FOUND.value),
+            (KeyError, ExceptionType.KEY_ERROR.value),
+        ],
+    )
+    def test_error_code_for_builtin_exceptions(self, builtin_exception, expected_code):
+        """Ensure built-in exceptions map to correct predefined error codes."""
+        assert error_code(builtin_exception) == expected_code
+
+    def test_unmapped_exception_returns_unspecified(self):
+        """Ensure unmapped exceptions fall back to UNSPECIFIED."""
+        assert error_code(RuntimeError) == ExceptionType.UNSPECIFIED.value
+
+
+class TestExceptionRetrieval:
+    """Tests for retrieving exceptions by name."""
+
+    @pytest.mark.parametrize(
+        "exception_name,expected_cls",
+        [
+            ("license_error", EXCEPTION_TYPE_TO_CLASS[ExceptionType.LICENSE_ERROR]),
+            ("variable_undefined", EXCEPTION_TYPE_TO_CLASS[ExceptionType.VARIABLE_UNDEFINED]),
+            ("file_not_found", FileNotFoundError),
+            ("key_error", KeyError),
+        ],
+    )
+    def test_exception_class_retrieval(self, exception_name, expected_cls):
+        """Ensure `exception_class()` correctly retrieves exceptions by name."""
+        assert exception_class(exception_name) == expected_cls
+
+    def test_exception_class_not_found(self):
+        """Check that an invalid exception name returns the default Exception class."""
+        assert exception_class("non_existent_error") == Exception
+
+    def test_exception_class_case_insensitive(self):
+        """Ensure exception name lookup is case-insensitive."""
+        assert exception_class("FILE_NOT_FOUND") == FileNotFoundError
+        assert exception_class("File_Not_Found") == FileNotFoundError
+
+
+class TestSystemErrors:
+    """Tests for system error handling with errno integration."""
+
+    @pytest.mark.parametrize("exception_cls,expected_errno", EXCEPTION_ERRNO_MAPPING.items())
+    def test_system_error_creation(self, exception_cls, expected_errno):
+        """Ensure `system_error()` correctly assigns errno values."""
+        ex = system_error(exception_cls)
+        assert ex.args[0] == expected_errno
+        assert ex.args[1] == os.strerror(expected_errno)
+
+    def test_system_error_with_additional_args(self):
+        """Ensure additional arguments are passed through to the exception."""
+        ex = system_error(FileNotFoundError, "/some/path")
+        assert ex.errno == errno.ENOENT
+        assert ex.strerror == os.strerror(errno.ENOENT)
+        assert ex.filename == "/some/path"
+
+    def test_system_error_default(self):
+        """Ensure unknown exceptions receive `EINVAL` (Invalid argument) as errno."""
+
+        class UnknownException(Exception):
+            pass
+
+        ex = system_error(UnknownException)
+        assert ex.args[0] == errno.EINVAL
+        assert ex.args[1] == os.strerror(errno.EINVAL)