vcti-error 2.0.1__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.
- vcti_error-2.0.2/PKG-INFO +241 -0
- vcti_error-2.0.2/README.md +217 -0
- {vcti_error-2.0.1 → vcti_error-2.0.2}/pyproject.toml +2 -2
- {vcti_error-2.0.1 → vcti_error-2.0.2}/src/vcti/error/contract/base_draft/__init__.py +1 -1
- {vcti_error-2.0.1 → vcti_error-2.0.2}/src/vcti/error/contract/legacy/__init__.py +8 -11
- {vcti_error-2.0.1 → vcti_error-2.0.2}/src/vcti/error/errors/__init__.py +2 -4
- {vcti_error-2.0.1 → vcti_error-2.0.2}/src/vcti/error/mechanics/codemap.py +10 -0
- vcti_error-2.0.2/src/vcti_error.egg-info/PKG-INFO +241 -0
- {vcti_error-2.0.1 → vcti_error-2.0.2}/src/vcti_error.egg-info/SOURCES.txt +2 -0
- {vcti_error-2.0.1 → vcti_error-2.0.2}/tests/test_base_draft.py +1 -1
- {vcti_error-2.0.1 → vcti_error-2.0.2}/tests/test_codemap.py +5 -5
- vcti_error-2.0.2/tests/test_docs.py +209 -0
- {vcti_error-2.0.1 → vcti_error-2.0.2}/tests/test_errors.py +2 -2
- vcti_error-2.0.2/tests/test_examples.py +268 -0
- {vcti_error-2.0.1 → vcti_error-2.0.2}/tests/test_legacy.py +2 -2
- {vcti_error-2.0.1 → vcti_error-2.0.2}/tests/test_system_error.py +1 -1
- {vcti_error-2.0.1 → vcti_error-2.0.2}/tests/test_version.py +3 -2
- vcti_error-2.0.1/PKG-INFO +0 -239
- vcti_error-2.0.1/README.md +0 -215
- vcti_error-2.0.1/src/vcti_error.egg-info/PKG-INFO +0 -239
- {vcti_error-2.0.1 → vcti_error-2.0.2}/LICENSE +0 -0
- {vcti_error-2.0.1 → vcti_error-2.0.2}/setup.cfg +0 -0
- {vcti_error-2.0.1 → vcti_error-2.0.2}/src/vcti/error/contract/base_draft/py.typed +0 -0
- {vcti_error-2.0.1 → vcti_error-2.0.2}/src/vcti/error/contract/legacy/py.typed +0 -0
- {vcti_error-2.0.1 → vcti_error-2.0.2}/src/vcti/error/errors/py.typed +0 -0
- {vcti_error-2.0.1 → vcti_error-2.0.2}/src/vcti/error/mechanics/__init__.py +0 -0
- {vcti_error-2.0.1 → vcti_error-2.0.2}/src/vcti/error/mechanics/py.typed +0 -0
- {vcti_error-2.0.1 → vcti_error-2.0.2}/src/vcti/error/mechanics/system_error.py +0 -0
- {vcti_error-2.0.1 → vcti_error-2.0.2}/src/vcti_error.egg-info/dependency_links.txt +0 -0
- {vcti_error-2.0.1 → vcti_error-2.0.2}/src/vcti_error.egg-info/requires.txt +0 -0
- {vcti_error-2.0.1 → 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.
|
|
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
|
|
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
|
|
3
|
+
"""vcti.error.contract.legacy — the established VCollab exit codes.
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
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
|
|
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
|
|
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
|
|
32
|
-
#
|
|
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
|