vcti-error 2.0.0__tar.gz → 2.0.2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. vcti_error-2.0.2/PKG-INFO +241 -0
  2. vcti_error-2.0.2/README.md +217 -0
  3. {vcti_error-2.0.0 → vcti_error-2.0.2}/pyproject.toml +2 -2
  4. {vcti_error-2.0.0 → vcti_error-2.0.2}/src/vcti/error/contract/base_draft/__init__.py +1 -1
  5. {vcti_error-2.0.0 → vcti_error-2.0.2}/src/vcti/error/contract/legacy/__init__.py +8 -11
  6. {vcti_error-2.0.0 → vcti_error-2.0.2}/src/vcti/error/errors/__init__.py +2 -4
  7. {vcti_error-2.0.0 → vcti_error-2.0.2}/src/vcti/error/mechanics/codemap.py +10 -0
  8. vcti_error-2.0.2/src/vcti_error.egg-info/PKG-INFO +241 -0
  9. {vcti_error-2.0.0 → vcti_error-2.0.2}/src/vcti_error.egg-info/SOURCES.txt +2 -0
  10. {vcti_error-2.0.0 → vcti_error-2.0.2}/tests/test_base_draft.py +1 -1
  11. {vcti_error-2.0.0 → vcti_error-2.0.2}/tests/test_codemap.py +5 -5
  12. vcti_error-2.0.2/tests/test_docs.py +209 -0
  13. {vcti_error-2.0.0 → vcti_error-2.0.2}/tests/test_errors.py +2 -2
  14. vcti_error-2.0.2/tests/test_examples.py +268 -0
  15. {vcti_error-2.0.0 → vcti_error-2.0.2}/tests/test_legacy.py +2 -2
  16. {vcti_error-2.0.0 → vcti_error-2.0.2}/tests/test_system_error.py +1 -1
  17. {vcti_error-2.0.0 → vcti_error-2.0.2}/tests/test_version.py +3 -2
  18. vcti_error-2.0.0/PKG-INFO +0 -239
  19. vcti_error-2.0.0/README.md +0 -215
  20. vcti_error-2.0.0/src/vcti_error.egg-info/PKG-INFO +0 -239
  21. {vcti_error-2.0.0 → vcti_error-2.0.2}/LICENSE +0 -0
  22. {vcti_error-2.0.0 → vcti_error-2.0.2}/setup.cfg +0 -0
  23. {vcti_error-2.0.0 → vcti_error-2.0.2}/src/vcti/error/contract/base_draft/py.typed +0 -0
  24. {vcti_error-2.0.0 → vcti_error-2.0.2}/src/vcti/error/contract/legacy/py.typed +0 -0
  25. {vcti_error-2.0.0 → vcti_error-2.0.2}/src/vcti/error/errors/py.typed +0 -0
  26. {vcti_error-2.0.0 → vcti_error-2.0.2}/src/vcti/error/mechanics/__init__.py +0 -0
  27. {vcti_error-2.0.0 → vcti_error-2.0.2}/src/vcti/error/mechanics/py.typed +0 -0
  28. {vcti_error-2.0.0 → vcti_error-2.0.2}/src/vcti/error/mechanics/system_error.py +0 -0
  29. {vcti_error-2.0.0 → vcti_error-2.0.2}/src/vcti_error.egg-info/dependency_links.txt +0 -0
  30. {vcti_error-2.0.0 → vcti_error-2.0.2}/src/vcti_error.egg-info/requires.txt +0 -0
  31. {vcti_error-2.0.0 → vcti_error-2.0.2}/src/vcti_error.egg-info/top_level.txt +0 -0
@@ -0,0 +1,241 @@
1
+ Metadata-Version: 2.4
2
+ Name: vcti-error
3
+ Version: 2.0.2
4
+ Summary: Shared exception classes for vcti packages, plus exception-to-exit-code contracts: the mechanics and the VCollab vocabularies
5
+ Author: Visual Collaboration Technologies Inc.
6
+ License-Expression: LicenseRef-Proprietary
7
+ Project-URL: Repository, https://github.com/vcollab/vcti-python-error
8
+ Project-URL: Changelog, https://github.com/vcollab/vcti-python-error/blob/main/CHANGELOG.md
9
+ Classifier: Operating System :: OS Independent
10
+ Classifier: Programming Language :: Python :: 3.12
11
+ Classifier: Programming Language :: Python :: 3.13
12
+ Classifier: Programming Language :: Python :: 3.14
13
+ Requires-Python: <3.15,>=3.12
14
+ Description-Content-Type: text/markdown
15
+ License-File: LICENSE
16
+ Provides-Extra: test
17
+ Requires-Dist: pytest; extra == "test"
18
+ Requires-Dist: pytest-cov; extra == "test"
19
+ Provides-Extra: lint
20
+ Requires-Dist: ruff; extra == "lint"
21
+ Provides-Extra: typecheck
22
+ Requires-Dist: mypy; extra == "typecheck"
23
+ Dynamic: license-file
24
+
25
+ # vcti-error
26
+
27
+ Shared exception classes for vcti packages, plus exception-to-exit-code
28
+ contracts: the mechanics and the VCollab vocabularies.
29
+
30
+ ## Overview
31
+
32
+ `vcti-error` provides two features, usable together or separately.
33
+ **Shared exception classes** (`vcti.error.errors`) are a common set of
34
+ exception types, such as `ConfigError` and `LicenseError`, so an error
35
+ raised in one vcti package can be caught by the same class in another.
36
+ **Exit-code contracts** decide which exit code a program returns for
37
+ the exception that ended it, so a caller that runs the program as a
38
+ subprocess can tell from the exit code what went wrong. A contract is a
39
+ mapping from exception classes to exit codes: `vcti.error.contract`
40
+ provides ready-made VCollab contracts, and `vcti.error.mechanics`
41
+ provides the functions that check, combine and apply any contract,
42
+ including your own.
43
+
44
+ ## Installation
45
+
46
+ ```bash
47
+ pip install vcti-error
48
+ ```
49
+
50
+ ### In `requirements.txt`
51
+
52
+ ```
53
+ vcti-error>=2.0.2
54
+ ```
55
+
56
+ ### In `pyproject.toml` dependencies
57
+
58
+ ```toml
59
+ dependencies = [
60
+ "vcti-error>=2.0.2",
61
+ ]
62
+ ```
63
+
64
+ ---
65
+
66
+ ## Quick Start
67
+
68
+ ### Shared exception classes
69
+
70
+ Raise a shared class where the failure happens; catch it by the same
71
+ class anywhere:
72
+
73
+ ```python
74
+ from vcti.error.errors import ConfigError
75
+
76
+
77
+ def load(config: dict[str, str]) -> None:
78
+ if "output_dir" not in config:
79
+ raise ConfigError("missing required key 'output_dir'")
80
+
81
+
82
+ try:
83
+ load({})
84
+ except ConfigError as err:
85
+ print(f"configuration problem: {err}")
86
+ ```
87
+
88
+ ### Exit-code contracts
89
+
90
+ Return the exit code a provided contract assigns to whatever exception
91
+ ended the program:
92
+
93
+ ```python
94
+ import sys
95
+
96
+ from vcti.error.contract.legacy import exit_code
97
+
98
+
99
+ def main() -> int:
100
+ try:
101
+ run()
102
+ return 0
103
+ except Exception as err:
104
+ return exit_code(err) # FileNotFoundError -> 2; anything unmapped -> 1
105
+
106
+
107
+ if __name__ == "__main__":
108
+ sys.exit(main())
109
+ ```
110
+
111
+ Add your program's own codes to a provided contract:
112
+
113
+ ```python
114
+ from vcti.error.contract import legacy
115
+ from vcti.error.mechanics import combine, resolve_code
116
+ from myapp.errors import CODE_MAP as APP_CODES # your own contract
117
+
118
+ CODE_MAP = combine(legacy.CODE_MAP, APP_CODES) # raises if both map one class differently
119
+
120
+
121
+ def main() -> int:
122
+ try:
123
+ run()
124
+ return 0
125
+ except Exception as err:
126
+ return resolve_code(err, CODE_MAP, default=legacy.ExitCode.UNSPECIFIED)
127
+ ```
128
+
129
+ Or define a contract as a plain dictionary:
130
+
131
+ ```python
132
+ import sys
133
+
134
+ from vcti.error.mechanics import resolve_code, validate
135
+
136
+ CODE_MAP = {FileNotFoundError: 2, PermissionError: 3}
137
+ validate(CODE_MAP) # every code an int in 1..255
138
+
139
+ try:
140
+ run()
141
+ except Exception as err:
142
+ sys.exit(resolve_code(err, CODE_MAP, default=1))
143
+ ```
144
+
145
+ ### OS errors with `errno` set
146
+
147
+ `system_error()` builds an OS exception the way the operating system
148
+ would, with `errno`, `strerror` and `filename` filled in:
149
+
150
+ ```python
151
+ from vcti.error.mechanics import system_error
152
+
153
+ err = system_error(FileNotFoundError, "config.yaml")
154
+ # err.errno == errno.ENOENT, err.filename == "config.yaml"
155
+ ```
156
+
157
+ ---
158
+
159
+ ## Shared exception classes (`vcti.error.errors`)
160
+
161
+ | Class | Raise when |
162
+ |-------|------------|
163
+ | `ConfigError` | Configuration is invalid or missing |
164
+ | `DataFormatError` | Input data does not match the expected format |
165
+ | `LicenseError` | License validation fails |
166
+ | `VariableUndefined` | An undefined workflow variable is referenced |
167
+
168
+ Each class derives directly from `Exception`; subclass one to describe
169
+ a more specific failure. A class has no exit code of its own — each
170
+ contract decides which code, if any, it maps the class to.
171
+
172
+ ---
173
+
174
+ ## Exit-code contracts
175
+
176
+ ### How a contract resolves an exception
177
+
178
+ A contract is a read-only mapping from exception classes to exit codes.
179
+ Resolution follows the exception's class hierarchy: the nearest mapped
180
+ base class decides the code, so a `class QuotaExceeded(LicenseError)`
181
+ gets `LicenseError`'s code. An exception with nothing mapped in its
182
+ hierarchy gets the contract's default, its `UNSPECIFIED` code. A
183
+ program uses one contract; the provided contracts number their codes
184
+ independently.
185
+
186
+ ### Provided contracts (`vcti.error.contract`)
187
+
188
+ | Module | Codes | Stability |
189
+ |--------|-------|-----------|
190
+ | `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 |
191
+ | `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 |
192
+
193
+ Every contract module exposes the same four names:
194
+
195
+ | Name | Purpose |
196
+ |------|---------|
197
+ | `ExitCode` | `IntEnum` of the contract's codes |
198
+ | `CODE_MAP` | The read-only class → code mapping |
199
+ | `exit_code(exc)` | Exception (instance or class) → exit code |
200
+ | `exception_class(code)` | Exit code → exception class (`Exception` if unmapped) |
201
+
202
+ To publish a contract of your own, see
203
+ [docs/extending.md](docs/extending.md).
204
+
205
+ ### Mechanics (`vcti.error.mechanics`)
206
+
207
+ | Name | Kind | Purpose |
208
+ |------|------|---------|
209
+ | `CodeMap` | type alias | `Mapping[type[BaseException], int]` — a contract |
210
+ | `validate(code_map, *, claim)` | function | Checks keys and codes; `claim` limits codes to a declared range |
211
+ | `combine(*code_maps)` | function | Read-only merge; one class mapped to two codes → `CodeCollisionError` |
212
+ | `resolve_code(exc, code_map, *, default)` | function | Exception → code, by class hierarchy; `default` when nothing matches |
213
+ | `resolve_class(code, code_map, *, default=Exception)` | function | Code → exception class (one class if several share a code) |
214
+ | `bind(code_map, *, default)` | function | Returns the `(exit_code, exception_class)` pair for a contract |
215
+ | `system_error(cls, *args)` | function | Builds an OS exception with the matching `errno` |
216
+ | `ERRNO_MAP` | constant | Read-only OS-exception → errno table used by `system_error` |
217
+ | `MAX_EXIT_CODE` | constant | 255, the highest exit code a process can report |
218
+ | `CodeMapError` | exception | Base of `CodeRangeError` and `CodeCollisionError` |
219
+
220
+ `validate()` accepts codes 1–255 — 0 means success, and the operating
221
+ system keeps only the low 8 bits, so 256 would arrive as 0 — and
222
+ rejects `bool` codes. Keep codes at or below 125: shells and process
223
+ tools reserve 126 and above.
224
+
225
+ ---
226
+
227
+ ## Dependencies
228
+
229
+ None. Standard library only.
230
+
231
+ ---
232
+
233
+ ## Documentation
234
+
235
+ | If you want to… | Read |
236
+ |---|---|
237
+ | Get started using the package | [Quick Start](#quick-start) above |
238
+ | Understand the architecture and the design decisions | [docs/design.md](docs/design.md) |
239
+ | Navigate and understand the source | [docs/source-guide.md](docs/source-guide.md) |
240
+ | See practical, real-world usage | [docs/patterns.md](docs/patterns.md) |
241
+ | Extend the library (add a shared class or a contract) | [docs/extending.md](docs/extending.md) |
@@ -0,0 +1,217 @@
1
+ # vcti-error
2
+
3
+ Shared exception classes for vcti packages, plus exception-to-exit-code
4
+ contracts: the mechanics and the VCollab vocabularies.
5
+
6
+ ## Overview
7
+
8
+ `vcti-error` provides two features, usable together or separately.
9
+ **Shared exception classes** (`vcti.error.errors`) are a common set of
10
+ exception types, such as `ConfigError` and `LicenseError`, so an error
11
+ raised in one vcti package can be caught by the same class in another.
12
+ **Exit-code contracts** decide which exit code a program returns for
13
+ the exception that ended it, so a caller that runs the program as a
14
+ subprocess can tell from the exit code what went wrong. A contract is a
15
+ mapping from exception classes to exit codes: `vcti.error.contract`
16
+ provides ready-made VCollab contracts, and `vcti.error.mechanics`
17
+ provides the functions that check, combine and apply any contract,
18
+ including your own.
19
+
20
+ ## Installation
21
+
22
+ ```bash
23
+ pip install vcti-error
24
+ ```
25
+
26
+ ### In `requirements.txt`
27
+
28
+ ```
29
+ vcti-error>=2.0.2
30
+ ```
31
+
32
+ ### In `pyproject.toml` dependencies
33
+
34
+ ```toml
35
+ dependencies = [
36
+ "vcti-error>=2.0.2",
37
+ ]
38
+ ```
39
+
40
+ ---
41
+
42
+ ## Quick Start
43
+
44
+ ### Shared exception classes
45
+
46
+ Raise a shared class where the failure happens; catch it by the same
47
+ class anywhere:
48
+
49
+ ```python
50
+ from vcti.error.errors import ConfigError
51
+
52
+
53
+ def load(config: dict[str, str]) -> None:
54
+ if "output_dir" not in config:
55
+ raise ConfigError("missing required key 'output_dir'")
56
+
57
+
58
+ try:
59
+ load({})
60
+ except ConfigError as err:
61
+ print(f"configuration problem: {err}")
62
+ ```
63
+
64
+ ### Exit-code contracts
65
+
66
+ Return the exit code a provided contract assigns to whatever exception
67
+ ended the program:
68
+
69
+ ```python
70
+ import sys
71
+
72
+ from vcti.error.contract.legacy import exit_code
73
+
74
+
75
+ def main() -> int:
76
+ try:
77
+ run()
78
+ return 0
79
+ except Exception as err:
80
+ return exit_code(err) # FileNotFoundError -> 2; anything unmapped -> 1
81
+
82
+
83
+ if __name__ == "__main__":
84
+ sys.exit(main())
85
+ ```
86
+
87
+ Add your program's own codes to a provided contract:
88
+
89
+ ```python
90
+ from vcti.error.contract import legacy
91
+ from vcti.error.mechanics import combine, resolve_code
92
+ from myapp.errors import CODE_MAP as APP_CODES # your own contract
93
+
94
+ CODE_MAP = combine(legacy.CODE_MAP, APP_CODES) # raises if both map one class differently
95
+
96
+
97
+ def main() -> int:
98
+ try:
99
+ run()
100
+ return 0
101
+ except Exception as err:
102
+ return resolve_code(err, CODE_MAP, default=legacy.ExitCode.UNSPECIFIED)
103
+ ```
104
+
105
+ Or define a contract as a plain dictionary:
106
+
107
+ ```python
108
+ import sys
109
+
110
+ from vcti.error.mechanics import resolve_code, validate
111
+
112
+ CODE_MAP = {FileNotFoundError: 2, PermissionError: 3}
113
+ validate(CODE_MAP) # every code an int in 1..255
114
+
115
+ try:
116
+ run()
117
+ except Exception as err:
118
+ sys.exit(resolve_code(err, CODE_MAP, default=1))
119
+ ```
120
+
121
+ ### OS errors with `errno` set
122
+
123
+ `system_error()` builds an OS exception the way the operating system
124
+ would, with `errno`, `strerror` and `filename` filled in:
125
+
126
+ ```python
127
+ from vcti.error.mechanics import system_error
128
+
129
+ err = system_error(FileNotFoundError, "config.yaml")
130
+ # err.errno == errno.ENOENT, err.filename == "config.yaml"
131
+ ```
132
+
133
+ ---
134
+
135
+ ## Shared exception classes (`vcti.error.errors`)
136
+
137
+ | Class | Raise when |
138
+ |-------|------------|
139
+ | `ConfigError` | Configuration is invalid or missing |
140
+ | `DataFormatError` | Input data does not match the expected format |
141
+ | `LicenseError` | License validation fails |
142
+ | `VariableUndefined` | An undefined workflow variable is referenced |
143
+
144
+ Each class derives directly from `Exception`; subclass one to describe
145
+ a more specific failure. A class has no exit code of its own — each
146
+ contract decides which code, if any, it maps the class to.
147
+
148
+ ---
149
+
150
+ ## Exit-code contracts
151
+
152
+ ### How a contract resolves an exception
153
+
154
+ A contract is a read-only mapping from exception classes to exit codes.
155
+ Resolution follows the exception's class hierarchy: the nearest mapped
156
+ base class decides the code, so a `class QuotaExceeded(LicenseError)`
157
+ gets `LicenseError`'s code. An exception with nothing mapped in its
158
+ hierarchy gets the contract's default, its `UNSPECIFIED` code. A
159
+ program uses one contract; the provided contracts number their codes
160
+ independently.
161
+
162
+ ### Provided contracts (`vcti.error.contract`)
163
+
164
+ | Module | Codes | Stability |
165
+ |--------|-------|-----------|
166
+ | `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 |
167
+ | `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 |
168
+
169
+ Every contract module exposes the same four names:
170
+
171
+ | Name | Purpose |
172
+ |------|---------|
173
+ | `ExitCode` | `IntEnum` of the contract's codes |
174
+ | `CODE_MAP` | The read-only class → code mapping |
175
+ | `exit_code(exc)` | Exception (instance or class) → exit code |
176
+ | `exception_class(code)` | Exit code → exception class (`Exception` if unmapped) |
177
+
178
+ To publish a contract of your own, see
179
+ [docs/extending.md](docs/extending.md).
180
+
181
+ ### Mechanics (`vcti.error.mechanics`)
182
+
183
+ | Name | Kind | Purpose |
184
+ |------|------|---------|
185
+ | `CodeMap` | type alias | `Mapping[type[BaseException], int]` — a contract |
186
+ | `validate(code_map, *, claim)` | function | Checks keys and codes; `claim` limits codes to a declared range |
187
+ | `combine(*code_maps)` | function | Read-only merge; one class mapped to two codes → `CodeCollisionError` |
188
+ | `resolve_code(exc, code_map, *, default)` | function | Exception → code, by class hierarchy; `default` when nothing matches |
189
+ | `resolve_class(code, code_map, *, default=Exception)` | function | Code → exception class (one class if several share a code) |
190
+ | `bind(code_map, *, default)` | function | Returns the `(exit_code, exception_class)` pair for a contract |
191
+ | `system_error(cls, *args)` | function | Builds an OS exception with the matching `errno` |
192
+ | `ERRNO_MAP` | constant | Read-only OS-exception → errno table used by `system_error` |
193
+ | `MAX_EXIT_CODE` | constant | 255, the highest exit code a process can report |
194
+ | `CodeMapError` | exception | Base of `CodeRangeError` and `CodeCollisionError` |
195
+
196
+ `validate()` accepts codes 1–255 — 0 means success, and the operating
197
+ system keeps only the low 8 bits, so 256 would arrive as 0 — and
198
+ rejects `bool` codes. Keep codes at or below 125: shells and process
199
+ tools reserve 126 and above.
200
+
201
+ ---
202
+
203
+ ## Dependencies
204
+
205
+ None. Standard library only.
206
+
207
+ ---
208
+
209
+ ## Documentation
210
+
211
+ | If you want to… | Read |
212
+ |---|---|
213
+ | Get started using the package | [Quick Start](#quick-start) above |
214
+ | Understand the architecture and the design decisions | [docs/design.md](docs/design.md) |
215
+ | Navigate and understand the source | [docs/source-guide.md](docs/source-guide.md) |
216
+ | See practical, real-world usage | [docs/patterns.md](docs/patterns.md) |
217
+ | Extend the library (add a shared class or a contract) | [docs/extending.md](docs/extending.md) |
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "vcti-error"
7
- version = "2.0.0"
7
+ version = "2.0.2"
8
8
  description = "Shared exception classes for vcti packages, plus exception-to-exit-code contracts: the mechanics and the VCollab vocabularies"
9
9
  readme = "README.md"
10
10
  authors = [
@@ -69,7 +69,7 @@ exclude_also = [
69
69
  "if TYPE_CHECKING:",
70
70
  "if __name__ == .__main__.:",
71
71
  "@(abc\\.)?abstractmethod",
72
- "\\.\\.\\.",
72
+ "^\\s*\\.\\.\\.\\s*$",
73
73
  ]
74
74
 
75
75
  [tool.ruff]
@@ -9,7 +9,7 @@ import line is the reviewable warning.
9
9
 
10
10
  The vocabulary is fully independent of
11
11
  :mod:`vcti.error.contract.legacy`: nothing ties its code values to the
12
- ones existing applications emit. Claim: **1–63**. The exception classes
12
+ ones ``legacy`` uses. Claim: **1–63**. The exception classes
13
13
  it maps live in :mod:`vcti.error.errors`; this leaf is nothing but the
14
14
  mapping.
15
15
 
@@ -1,16 +1,14 @@
1
1
  # Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
2
2
  # See LICENSE for details.
3
- """vcti.error.contract.legacy — the exit codes of existing applications.
3
+ """vcti.error.contract.legacy — the established VCollab exit codes.
4
4
 
5
- This leaf reproduces the exit-code mapping hardcoded into existing
6
- applications (codes 1–5) so those deployments keep working unchanged.
7
- Like every stable contract leaf it is **append-only**: a released code
8
- is never reassigned or removed. It is **not frozen** — the name marks
9
- *whose* codes these are (the existing, "legacy", applications), not a
10
- promise that the set never grows; new codes may be added within the
11
- claim as those applications evolve. Claim: **1–5**.
5
+ Five codes (1–5): unspecified, file not found, license error, key error
6
+ and undefined workflow variable. Like every stable contract leaf it is
7
+ **append-only**: a released code is never reassigned or removed. It is
8
+ **not frozen** — new codes may be added within the claim.
9
+ Claim: **1–5**.
12
10
 
13
- It is fully independent of the vocabulary incubating in
11
+ It is fully independent of the vocabulary in
14
12
  :mod:`vcti.error.contract.base_draft` — neither constrains the other.
15
13
  The exception classes it maps live in :mod:`vcti.error.errors`; this
16
14
  leaf is nothing but the mapping.
@@ -49,8 +47,7 @@ class ExitCode(IntEnum):
49
47
 
50
48
  # The map lists only specific classifications. UNSPECIFIED is the
51
49
  # fallback, supplied via bind(default=...) below; an unmapped exception
52
- # resolves to it exactly as it did in the applications this leaf
53
- # reproduces — so it is not mapped to Exception here.
50
+ # resolves to it, so it is not mapped to Exception here.
54
51
  CODE_MAP: CodeMap = MappingProxyType(
55
52
  {
56
53
  FileNotFoundError: ExitCode.FILE_NOT_FOUND,
@@ -28,10 +28,8 @@ class LicenseError(Exception):
28
28
  """Raised when license validation fails."""
29
29
 
30
30
 
31
- # Named without the `Error` suffix the other classes carry: this is the
32
- # name existing applications already raise and catch, preserved for
33
- # source compatibility with the code `vcti.error.contract.legacy`
34
- # reproduces. Do not rename.
31
+ # Named without the `Error` suffix the other classes carry. The name is
32
+ # public API: do not rename.
35
33
  class VariableUndefined(Exception):
36
34
  """Raised when an undefined workflow variable is referenced."""
37
35
 
@@ -239,9 +239,19 @@ def bind(
239
239
  """
240
240
 
241
241
  def exit_code(exc: BaseException | type[BaseException]) -> int:
242
+ """Resolve an exception (instance or class) to its exit code in this contract.
243
+
244
+ The nearest mapped ancestor in the exception's MRO decides the code;
245
+ an exception with no mapped ancestor gets the contract's default.
246
+ """
242
247
  return resolve_code(exc, code_map, default=default)
243
248
 
244
249
  def exception_class(code: int) -> type[BaseException]:
250
+ """Resolve an exit code back to an exception class in this contract.
251
+
252
+ Returns the first class mapped to ``code``, or ``Exception`` when no
253
+ class is. Lossy when several classes share a code.
254
+ """
245
255
  return resolve_class(code, code_map, default=Exception)
246
256
 
247
257
  return exit_code, exception_class