team-hermes.core 1.0.1__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.
- team_hermes_core-1.0.1/.gitignore +221 -0
- team_hermes_core-1.0.1/LICENSE.md +21 -0
- team_hermes_core-1.0.1/PKG-INFO +137 -0
- team_hermes_core-1.0.1/README.md +119 -0
- team_hermes_core-1.0.1/pyproject.toml +40 -0
- team_hermes_core-1.0.1/src/team_hermes/core/__init__.py +27 -0
- team_hermes_core-1.0.1/src/team_hermes/core/exceptions.py +160 -0
- team_hermes_core-1.0.1/src/team_hermes/core/py.typed +1 -0
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
# Byte-compiled / optimized / DLL files
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[codz]
|
|
4
|
+
*$py.class
|
|
5
|
+
|
|
6
|
+
# C extensions
|
|
7
|
+
*.so
|
|
8
|
+
|
|
9
|
+
# Distribution / packaging
|
|
10
|
+
.Python
|
|
11
|
+
build/
|
|
12
|
+
develop-eggs/
|
|
13
|
+
dist/
|
|
14
|
+
downloads/
|
|
15
|
+
eggs/
|
|
16
|
+
.eggs/
|
|
17
|
+
lib/
|
|
18
|
+
lib64/
|
|
19
|
+
parts/
|
|
20
|
+
sdist/
|
|
21
|
+
var/
|
|
22
|
+
wheels/
|
|
23
|
+
share/python-wheels/
|
|
24
|
+
*.egg-info/
|
|
25
|
+
.installed.cfg
|
|
26
|
+
*.egg
|
|
27
|
+
MANIFEST
|
|
28
|
+
|
|
29
|
+
# PyInstaller
|
|
30
|
+
# Usually these files are written by a python script from a template
|
|
31
|
+
# before PyInstaller builds the exe, so as to inject date/other infos into it.
|
|
32
|
+
*.manifest
|
|
33
|
+
*.spec
|
|
34
|
+
|
|
35
|
+
# Installer logs
|
|
36
|
+
pip-log.txt
|
|
37
|
+
pip-delete-this-directory.txt
|
|
38
|
+
|
|
39
|
+
# Unit test / coverage reports
|
|
40
|
+
htmlcov/
|
|
41
|
+
.tox/
|
|
42
|
+
.nox/
|
|
43
|
+
.coverage
|
|
44
|
+
.coverage.*
|
|
45
|
+
.cache
|
|
46
|
+
nosetests.xml
|
|
47
|
+
coverage.xml
|
|
48
|
+
*.cover
|
|
49
|
+
*.py.cover
|
|
50
|
+
*.lcov
|
|
51
|
+
.hypothesis/
|
|
52
|
+
.pytest_cache/
|
|
53
|
+
cover/
|
|
54
|
+
|
|
55
|
+
# Translations
|
|
56
|
+
*.mo
|
|
57
|
+
*.pot
|
|
58
|
+
|
|
59
|
+
# Django stuff:
|
|
60
|
+
*.log
|
|
61
|
+
local_settings.py
|
|
62
|
+
db.sqlite3
|
|
63
|
+
db.sqlite3-journal
|
|
64
|
+
|
|
65
|
+
# Flask stuff:
|
|
66
|
+
instance/
|
|
67
|
+
.webassets-cache
|
|
68
|
+
|
|
69
|
+
# Scrapy stuff:
|
|
70
|
+
.scrapy
|
|
71
|
+
|
|
72
|
+
# Sphinx documentation
|
|
73
|
+
docs/_build/
|
|
74
|
+
|
|
75
|
+
# PyBuilder
|
|
76
|
+
.pybuilder/
|
|
77
|
+
target/
|
|
78
|
+
|
|
79
|
+
# Jupyter Notebook
|
|
80
|
+
.ipynb_checkpoints
|
|
81
|
+
|
|
82
|
+
# IPython
|
|
83
|
+
profile_default/
|
|
84
|
+
ipython_config.py
|
|
85
|
+
|
|
86
|
+
# pyenv
|
|
87
|
+
# For a library or package, you might want to ignore these files since the code is
|
|
88
|
+
# intended to run in multiple environments; otherwise, check them in:
|
|
89
|
+
# .python-version
|
|
90
|
+
|
|
91
|
+
# pipenv
|
|
92
|
+
# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
|
|
93
|
+
# However, in case of collaboration, if having platform-specific dependencies or dependencies
|
|
94
|
+
# having no cross-platform support, pipenv may install dependencies that don't work, or not
|
|
95
|
+
# install all needed dependencies.
|
|
96
|
+
# Pipfile.lock
|
|
97
|
+
|
|
98
|
+
# uv
|
|
99
|
+
# Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
|
|
100
|
+
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
|
101
|
+
# commonly ignored for libraries.
|
|
102
|
+
# uv.lock
|
|
103
|
+
|
|
104
|
+
# poetry
|
|
105
|
+
# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
|
|
106
|
+
# This is especially recommended for binary packages to ensure reproducibility, and is more
|
|
107
|
+
# commonly ignored for libraries.
|
|
108
|
+
# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
|
|
109
|
+
# poetry.lock
|
|
110
|
+
# poetry.toml
|
|
111
|
+
|
|
112
|
+
# pdm
|
|
113
|
+
# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
|
|
114
|
+
# pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
|
|
115
|
+
# https://pdm-project.org/en/latest/usage/project/#working-with-version-control
|
|
116
|
+
# pdm.lock
|
|
117
|
+
# pdm.toml
|
|
118
|
+
.pdm-python
|
|
119
|
+
.pdm-build/
|
|
120
|
+
|
|
121
|
+
# pixi
|
|
122
|
+
# Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
|
|
123
|
+
# pixi.lock
|
|
124
|
+
# Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
|
|
125
|
+
# in the .venv directory. It is recommended not to include this directory in version control.
|
|
126
|
+
.pixi/*
|
|
127
|
+
!.pixi/config.toml
|
|
128
|
+
|
|
129
|
+
# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
|
|
130
|
+
__pypackages__/
|
|
131
|
+
|
|
132
|
+
# Celery stuff
|
|
133
|
+
celerybeat-schedule*
|
|
134
|
+
celerybeat.pid
|
|
135
|
+
|
|
136
|
+
# Redis
|
|
137
|
+
*.rdb
|
|
138
|
+
*.aof
|
|
139
|
+
*.pid
|
|
140
|
+
|
|
141
|
+
# RabbitMQ
|
|
142
|
+
mnesia/
|
|
143
|
+
rabbitmq/
|
|
144
|
+
rabbitmq-data/
|
|
145
|
+
|
|
146
|
+
# ActiveMQ
|
|
147
|
+
activemq-data/
|
|
148
|
+
|
|
149
|
+
# SageMath parsed files
|
|
150
|
+
*.sage.py
|
|
151
|
+
|
|
152
|
+
# Environments
|
|
153
|
+
.env
|
|
154
|
+
.envrc
|
|
155
|
+
.venv
|
|
156
|
+
.artifact-tests/
|
|
157
|
+
env/
|
|
158
|
+
venv/
|
|
159
|
+
ENV/
|
|
160
|
+
env.bak/
|
|
161
|
+
venv.bak/
|
|
162
|
+
|
|
163
|
+
# Spyder project settings
|
|
164
|
+
.spyderproject
|
|
165
|
+
.spyproject
|
|
166
|
+
|
|
167
|
+
# Rope project settings
|
|
168
|
+
.ropeproject
|
|
169
|
+
|
|
170
|
+
# mkdocs/Zensical documentation
|
|
171
|
+
/site
|
|
172
|
+
|
|
173
|
+
# mypy
|
|
174
|
+
.mypy_cache/
|
|
175
|
+
.dmypy.json
|
|
176
|
+
dmypy.json
|
|
177
|
+
|
|
178
|
+
# Pyre type checker
|
|
179
|
+
.pyre/
|
|
180
|
+
|
|
181
|
+
# pytype static type analyzer
|
|
182
|
+
.pytype/
|
|
183
|
+
|
|
184
|
+
# Cython debug symbols
|
|
185
|
+
cython_debug/
|
|
186
|
+
|
|
187
|
+
# PyCharm
|
|
188
|
+
# JetBrains specific template is maintained in a separate JetBrains.gitignore that can
|
|
189
|
+
# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
|
|
190
|
+
# and can be added to the global gitignore or merged into this file. For a more nuclear
|
|
191
|
+
# option (not recommended) you can uncomment the following to ignore the entire idea folder.
|
|
192
|
+
# .idea/
|
|
193
|
+
|
|
194
|
+
# Abstra
|
|
195
|
+
# Abstra is an AI-powered process automation framework.
|
|
196
|
+
# Ignore directories containing user credentials, local state, and settings.
|
|
197
|
+
# Learn more at https://abstra.io/docs
|
|
198
|
+
.abstra/
|
|
199
|
+
|
|
200
|
+
# Visual Studio Code
|
|
201
|
+
# Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
|
|
202
|
+
# can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
|
|
203
|
+
# and can be added to the global gitignore or merged into this file. However, if you prefer, you
|
|
204
|
+
# could uncomment the following to ignore the entire vscode folder
|
|
205
|
+
# .vscode/
|
|
206
|
+
# Temporary file for partial code execution
|
|
207
|
+
tempCodeRunnerFile.py
|
|
208
|
+
|
|
209
|
+
# Ruff stuff:
|
|
210
|
+
.ruff_cache/
|
|
211
|
+
|
|
212
|
+
# PyPI configuration file
|
|
213
|
+
.pypirc
|
|
214
|
+
|
|
215
|
+
# Marimo
|
|
216
|
+
marimo/_static/
|
|
217
|
+
marimo/_lsp/
|
|
218
|
+
__marimo__/
|
|
219
|
+
|
|
220
|
+
# Streamlit
|
|
221
|
+
.streamlit/secrets.toml
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2022 Equinor
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: team-hermes.core
|
|
3
|
+
Version: 1.0.1
|
|
4
|
+
Summary: Shared application exceptions for Team Hermes projects
|
|
5
|
+
Project-URL: Repository, https://github.com/equinor/team-hermes-packages
|
|
6
|
+
Project-URL: Issues, https://github.com/equinor/team-hermes-packages/issues
|
|
7
|
+
License-File: LICENSE.md
|
|
8
|
+
Classifier: Intended Audience :: Developers
|
|
9
|
+
Classifier: Programming Language :: Python :: 3
|
|
10
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
15
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
16
|
+
Requires-Python: >=3.12
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
|
|
19
|
+
# 🧩 Team Hermes Core
|
|
20
|
+
|
|
21
|
+
Shared, framework- and transport-agnostic Python exceptions for application failures.
|
|
22
|
+
They describe what went wrong without knowing about HTTP APIs, status codes, or
|
|
23
|
+
response formats. Your application or integration decides how to handle them,
|
|
24
|
+
whether in an API, command-line tool, or background worker.
|
|
25
|
+
|
|
26
|
+
**Requires:** Python 3.12+. Git is required for installation from source.
|
|
27
|
+
Core has no runtime dependencies outside the standard library.
|
|
28
|
+
|
|
29
|
+
## ⬇️ Installation
|
|
30
|
+
|
|
31
|
+
Install into a virtual environment:
|
|
32
|
+
|
|
33
|
+
```shell
|
|
34
|
+
python -m pip install \
|
|
35
|
+
"team-hermes-core @ git+https://github.com/equinor/team-hermes-packages.git@main#subdirectory=team-hermes-packages-python/core"
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
For reproducible installs, replace `main` with a release tag or full commit SHA.
|
|
39
|
+
|
|
40
|
+
## Quick Start
|
|
41
|
+
|
|
42
|
+
Import from `team_hermes.core`, raise a specific exception, and catch it where you
|
|
43
|
+
can handle the failure. `ApplicationException` catches any of the built-in categories:
|
|
44
|
+
|
|
45
|
+
```pycon
|
|
46
|
+
>>> from team_hermes.core import ApplicationException, NotFoundException
|
|
47
|
+
>>> orders = {"order-1": "pending"}
|
|
48
|
+
>>> def get_order_status(order_id: str) -> str:
|
|
49
|
+
... if order_id not in orders:
|
|
50
|
+
... raise NotFoundException("Order not found", extensions={"order_id": order_id})
|
|
51
|
+
... return orders[order_id]
|
|
52
|
+
...
|
|
53
|
+
>>> try:
|
|
54
|
+
... status = get_order_status("order-404")
|
|
55
|
+
... print(status)
|
|
56
|
+
... except ApplicationException as error:
|
|
57
|
+
... print(str(error))
|
|
58
|
+
...
|
|
59
|
+
Order not found
|
|
60
|
+
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
The caller decides how to present the error; the lookup function has no logging
|
|
64
|
+
or HTTP dependency.
|
|
65
|
+
|
|
66
|
+
## Handling Errors
|
|
67
|
+
|
|
68
|
+
Catch a specific exception when you can recover from that failure. Catch
|
|
69
|
+
`ApplicationException` at an application boundary that handles all application
|
|
70
|
+
errors: a CLI might display a message and choose an exit code; a worker might
|
|
71
|
+
record a failed job or apply its own retry policy.
|
|
72
|
+
|
|
73
|
+
Core does not send responses, emit logs, retry operations, or manage database
|
|
74
|
+
transactions. Titles, type identifiers, and severity are metadata, not HTTP status
|
|
75
|
+
mappings. For APIs, the [FastAPI integration](../fastapi-error-handling/README.md#problem-details)
|
|
76
|
+
provides response conversion and logging; applications own disclosure policies.
|
|
77
|
+
|
|
78
|
+
## Choosing an Exception
|
|
79
|
+
|
|
80
|
+
| Exception | Use when |
|
|
81
|
+
| -------------------------------- | -------------------------------------------------------------------- |
|
|
82
|
+
| `NotFoundException` | A required resource does not exist. |
|
|
83
|
+
| `ValidationException` | Application input is invalid, such as a reversed date range. |
|
|
84
|
+
| `BusinessRuleViolationException` | Valid input violates a policy, such as a purchasing limit. |
|
|
85
|
+
| `ConflictException` | Current resource state prevents an action, such as a stale revision. |
|
|
86
|
+
| `DuplicateException` | Creation would violate uniqueness. |
|
|
87
|
+
| `UnauthorizedException` | Authentication is missing or invalid. |
|
|
88
|
+
| `MissingPrivilegeException` | The caller lacks permission. |
|
|
89
|
+
| `UpstreamApiException` | An upstream API returns an unexpected or malformed response. |
|
|
90
|
+
|
|
91
|
+
All eight inherit directly from `ApplicationException`; `DuplicateException` is
|
|
92
|
+
not a `ConflictException`. Translate only known failures with an application
|
|
93
|
+
meaning, preserving their cause with `raise ... from error`. Do not reclassify
|
|
94
|
+
every unexpected programming error as an application exception.
|
|
95
|
+
|
|
96
|
+
Choose categories consistently so callers can react appropriately. An empty search
|
|
97
|
+
result need not be an exception; use `NotFoundException` when a particular resource
|
|
98
|
+
is required to exist.
|
|
99
|
+
|
|
100
|
+
## Exception Details
|
|
101
|
+
|
|
102
|
+
- Built-in categories accept `detail`, `title`, and `extensions`. Keep messages
|
|
103
|
+
useful and context safe to disclose: integrations may return them to clients.
|
|
104
|
+
- `MissingPrivilegeException` defaults to `ExceptionSeverity.WARNING`; the others
|
|
105
|
+
default to `ERROR`. The enum also provides `CRITICAL`. Severity is metadata;
|
|
106
|
+
core does not emit logs.
|
|
107
|
+
- The base `ApplicationException` additionally accepts `type`, `instance`, and
|
|
108
|
+
`severity`. Its defaults are `about:blank`, `ERROR`, and `None` for optional fields.
|
|
109
|
+
- `ApplicationException` and `ValidationException` accept keyword-only `errors`,
|
|
110
|
+
a list of dictionaries for safe, structured error details. For example,
|
|
111
|
+
`ValidationException("Invalid order", errors=[{"detail": "Total must be positive", "pointer": "#/total"}])`.
|
|
112
|
+
Core stores these details without interpreting them; the FastAPI integration
|
|
113
|
+
exposes supported fields in the response's top-level `errors` array.
|
|
114
|
+
- `to_dict()` retains `None` for existing fields and shares the original
|
|
115
|
+
extensions dictionary. It includes `errors` only when supplied, including an
|
|
116
|
+
empty list. It is not an HTTP response.
|
|
117
|
+
|
|
118
|
+
## 🛠️ Development
|
|
119
|
+
|
|
120
|
+
Follow the [workspace setup](../README.md), then run from the repository root:
|
|
121
|
+
|
|
122
|
+
```shell
|
|
123
|
+
mise run python:test -- core/tests
|
|
124
|
+
mise run python:lint
|
|
125
|
+
mise run python:typecheck
|
|
126
|
+
mise run python:build
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
The README example is executed and checked by pytest. To test the installed wheel independently:
|
|
130
|
+
|
|
131
|
+
```shell
|
|
132
|
+
UV_PYTHON=3.12 mise run python:test:core
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## ⚖️ License
|
|
136
|
+
|
|
137
|
+
See [LICENSE.md](LICENSE.md).
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# 🧩 Team Hermes Core
|
|
2
|
+
|
|
3
|
+
Shared, framework- and transport-agnostic Python exceptions for application failures.
|
|
4
|
+
They describe what went wrong without knowing about HTTP APIs, status codes, or
|
|
5
|
+
response formats. Your application or integration decides how to handle them,
|
|
6
|
+
whether in an API, command-line tool, or background worker.
|
|
7
|
+
|
|
8
|
+
**Requires:** Python 3.12+. Git is required for installation from source.
|
|
9
|
+
Core has no runtime dependencies outside the standard library.
|
|
10
|
+
|
|
11
|
+
## ⬇️ Installation
|
|
12
|
+
|
|
13
|
+
Install into a virtual environment:
|
|
14
|
+
|
|
15
|
+
```shell
|
|
16
|
+
python -m pip install \
|
|
17
|
+
"team-hermes-core @ git+https://github.com/equinor/team-hermes-packages.git@main#subdirectory=team-hermes-packages-python/core"
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
For reproducible installs, replace `main` with a release tag or full commit SHA.
|
|
21
|
+
|
|
22
|
+
## Quick Start
|
|
23
|
+
|
|
24
|
+
Import from `team_hermes.core`, raise a specific exception, and catch it where you
|
|
25
|
+
can handle the failure. `ApplicationException` catches any of the built-in categories:
|
|
26
|
+
|
|
27
|
+
```pycon
|
|
28
|
+
>>> from team_hermes.core import ApplicationException, NotFoundException
|
|
29
|
+
>>> orders = {"order-1": "pending"}
|
|
30
|
+
>>> def get_order_status(order_id: str) -> str:
|
|
31
|
+
... if order_id not in orders:
|
|
32
|
+
... raise NotFoundException("Order not found", extensions={"order_id": order_id})
|
|
33
|
+
... return orders[order_id]
|
|
34
|
+
...
|
|
35
|
+
>>> try:
|
|
36
|
+
... status = get_order_status("order-404")
|
|
37
|
+
... print(status)
|
|
38
|
+
... except ApplicationException as error:
|
|
39
|
+
... print(str(error))
|
|
40
|
+
...
|
|
41
|
+
Order not found
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
The caller decides how to present the error; the lookup function has no logging
|
|
46
|
+
or HTTP dependency.
|
|
47
|
+
|
|
48
|
+
## Handling Errors
|
|
49
|
+
|
|
50
|
+
Catch a specific exception when you can recover from that failure. Catch
|
|
51
|
+
`ApplicationException` at an application boundary that handles all application
|
|
52
|
+
errors: a CLI might display a message and choose an exit code; a worker might
|
|
53
|
+
record a failed job or apply its own retry policy.
|
|
54
|
+
|
|
55
|
+
Core does not send responses, emit logs, retry operations, or manage database
|
|
56
|
+
transactions. Titles, type identifiers, and severity are metadata, not HTTP status
|
|
57
|
+
mappings. For APIs, the [FastAPI integration](../fastapi-error-handling/README.md#problem-details)
|
|
58
|
+
provides response conversion and logging; applications own disclosure policies.
|
|
59
|
+
|
|
60
|
+
## Choosing an Exception
|
|
61
|
+
|
|
62
|
+
| Exception | Use when |
|
|
63
|
+
| -------------------------------- | -------------------------------------------------------------------- |
|
|
64
|
+
| `NotFoundException` | A required resource does not exist. |
|
|
65
|
+
| `ValidationException` | Application input is invalid, such as a reversed date range. |
|
|
66
|
+
| `BusinessRuleViolationException` | Valid input violates a policy, such as a purchasing limit. |
|
|
67
|
+
| `ConflictException` | Current resource state prevents an action, such as a stale revision. |
|
|
68
|
+
| `DuplicateException` | Creation would violate uniqueness. |
|
|
69
|
+
| `UnauthorizedException` | Authentication is missing or invalid. |
|
|
70
|
+
| `MissingPrivilegeException` | The caller lacks permission. |
|
|
71
|
+
| `UpstreamApiException` | An upstream API returns an unexpected or malformed response. |
|
|
72
|
+
|
|
73
|
+
All eight inherit directly from `ApplicationException`; `DuplicateException` is
|
|
74
|
+
not a `ConflictException`. Translate only known failures with an application
|
|
75
|
+
meaning, preserving their cause with `raise ... from error`. Do not reclassify
|
|
76
|
+
every unexpected programming error as an application exception.
|
|
77
|
+
|
|
78
|
+
Choose categories consistently so callers can react appropriately. An empty search
|
|
79
|
+
result need not be an exception; use `NotFoundException` when a particular resource
|
|
80
|
+
is required to exist.
|
|
81
|
+
|
|
82
|
+
## Exception Details
|
|
83
|
+
|
|
84
|
+
- Built-in categories accept `detail`, `title`, and `extensions`. Keep messages
|
|
85
|
+
useful and context safe to disclose: integrations may return them to clients.
|
|
86
|
+
- `MissingPrivilegeException` defaults to `ExceptionSeverity.WARNING`; the others
|
|
87
|
+
default to `ERROR`. The enum also provides `CRITICAL`. Severity is metadata;
|
|
88
|
+
core does not emit logs.
|
|
89
|
+
- The base `ApplicationException` additionally accepts `type`, `instance`, and
|
|
90
|
+
`severity`. Its defaults are `about:blank`, `ERROR`, and `None` for optional fields.
|
|
91
|
+
- `ApplicationException` and `ValidationException` accept keyword-only `errors`,
|
|
92
|
+
a list of dictionaries for safe, structured error details. For example,
|
|
93
|
+
`ValidationException("Invalid order", errors=[{"detail": "Total must be positive", "pointer": "#/total"}])`.
|
|
94
|
+
Core stores these details without interpreting them; the FastAPI integration
|
|
95
|
+
exposes supported fields in the response's top-level `errors` array.
|
|
96
|
+
- `to_dict()` retains `None` for existing fields and shares the original
|
|
97
|
+
extensions dictionary. It includes `errors` only when supplied, including an
|
|
98
|
+
empty list. It is not an HTTP response.
|
|
99
|
+
|
|
100
|
+
## 🛠️ Development
|
|
101
|
+
|
|
102
|
+
Follow the [workspace setup](../README.md), then run from the repository root:
|
|
103
|
+
|
|
104
|
+
```shell
|
|
105
|
+
mise run python:test -- core/tests
|
|
106
|
+
mise run python:lint
|
|
107
|
+
mise run python:typecheck
|
|
108
|
+
mise run python:build
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
The README example is executed and checked by pytest. To test the installed wheel independently:
|
|
112
|
+
|
|
113
|
+
```shell
|
|
114
|
+
UV_PYTHON=3.12 mise run python:test:core
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## ⚖️ License
|
|
118
|
+
|
|
119
|
+
See [LICENSE.md](LICENSE.md).
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27,<2"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "team-hermes.core"
|
|
7
|
+
version = "1.0.1"
|
|
8
|
+
description = "Shared application exceptions for Team Hermes projects"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license-files = ["LICENSE.md"]
|
|
11
|
+
requires-python = ">=3.12"
|
|
12
|
+
dependencies = []
|
|
13
|
+
classifiers = [
|
|
14
|
+
"Intended Audience :: Developers",
|
|
15
|
+
"Programming Language :: Python :: 3",
|
|
16
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
17
|
+
"Programming Language :: Python :: 3.12",
|
|
18
|
+
"Programming Language :: Python :: 3.13",
|
|
19
|
+
"Programming Language :: Python :: 3.14",
|
|
20
|
+
"Programming Language :: Python :: 3.15",
|
|
21
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
22
|
+
]
|
|
23
|
+
|
|
24
|
+
[project.urls]
|
|
25
|
+
Repository = "https://github.com/equinor/team-hermes-packages"
|
|
26
|
+
Issues = "https://github.com/equinor/team-hermes-packages/issues"
|
|
27
|
+
|
|
28
|
+
[tool.hatch.build.targets.wheel]
|
|
29
|
+
packages = ["src/team_hermes"]
|
|
30
|
+
|
|
31
|
+
[tool.hatch.build.targets.sdist]
|
|
32
|
+
include = ["src", "pyproject.toml", "README.md", "LICENSE.md"]
|
|
33
|
+
|
|
34
|
+
[tool.ruff]
|
|
35
|
+
extend = "../pyproject.toml"
|
|
36
|
+
src = [".", "src"]
|
|
37
|
+
namespace-packages = ["src/team_hermes"]
|
|
38
|
+
|
|
39
|
+
[tool.ruff.lint.per-file-ignores]
|
|
40
|
+
"tests/**" = ["S101"]
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"""Shared application exceptions."""
|
|
2
|
+
|
|
3
|
+
from .exceptions import (
|
|
4
|
+
ApplicationException,
|
|
5
|
+
BusinessRuleViolationException,
|
|
6
|
+
ConflictException,
|
|
7
|
+
DuplicateException,
|
|
8
|
+
ExceptionSeverity,
|
|
9
|
+
MissingPrivilegeException,
|
|
10
|
+
NotFoundException,
|
|
11
|
+
UnauthorizedException,
|
|
12
|
+
UpstreamApiException,
|
|
13
|
+
ValidationException,
|
|
14
|
+
)
|
|
15
|
+
|
|
16
|
+
__all__ = [
|
|
17
|
+
"ApplicationException",
|
|
18
|
+
"BusinessRuleViolationException",
|
|
19
|
+
"ConflictException",
|
|
20
|
+
"DuplicateException",
|
|
21
|
+
"ExceptionSeverity",
|
|
22
|
+
"MissingPrivilegeException",
|
|
23
|
+
"NotFoundException",
|
|
24
|
+
"UnauthorizedException",
|
|
25
|
+
"UpstreamApiException",
|
|
26
|
+
"ValidationException",
|
|
27
|
+
]
|
|
@@ -0,0 +1,160 @@
|
|
|
1
|
+
"""Application exceptions independent of transport and persistence frameworks."""
|
|
2
|
+
|
|
3
|
+
from enum import Enum, unique
|
|
4
|
+
from typing import Any
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
@unique
|
|
8
|
+
class ExceptionSeverity(Enum):
|
|
9
|
+
WARNING = 1
|
|
10
|
+
ERROR = 2
|
|
11
|
+
CRITICAL = 3
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class ApplicationException(Exception):
|
|
15
|
+
"""Base class for application-specific exceptions."""
|
|
16
|
+
|
|
17
|
+
def __init__(
|
|
18
|
+
self,
|
|
19
|
+
type: str = "about:blank",
|
|
20
|
+
title: str | None = None,
|
|
21
|
+
detail: str | None = None,
|
|
22
|
+
instance: str | None = None,
|
|
23
|
+
extensions: dict[str, Any] | None = None,
|
|
24
|
+
severity: ExceptionSeverity = ExceptionSeverity.ERROR,
|
|
25
|
+
*,
|
|
26
|
+
errors: list[dict[str, Any]] | None = None,
|
|
27
|
+
) -> None:
|
|
28
|
+
super().__init__(detail)
|
|
29
|
+
self.type = type
|
|
30
|
+
self.title = title
|
|
31
|
+
self.detail = detail
|
|
32
|
+
self.instance = instance
|
|
33
|
+
self.extensions = extensions
|
|
34
|
+
self.severity = severity
|
|
35
|
+
self.errors = errors
|
|
36
|
+
|
|
37
|
+
def to_dict(self) -> dict[str, Any]:
|
|
38
|
+
return {
|
|
39
|
+
"type": self.type,
|
|
40
|
+
"title": self.title,
|
|
41
|
+
"detail": self.detail,
|
|
42
|
+
"instance": self.instance,
|
|
43
|
+
"extensions": self.extensions,
|
|
44
|
+
"severity": self.severity.name if self.severity else None,
|
|
45
|
+
**({"errors": self.errors} if self.errors is not None else {}),
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
class MissingPrivilegeException(ApplicationException):
|
|
50
|
+
"""Raised when a user lacks necessary privileges."""
|
|
51
|
+
|
|
52
|
+
def __init__(
|
|
53
|
+
self,
|
|
54
|
+
detail: str = "You do not have the required permissions.",
|
|
55
|
+
title: str = "Forbidden",
|
|
56
|
+
extensions: dict[str, Any] | None = None,
|
|
57
|
+
) -> None:
|
|
58
|
+
super().__init__(
|
|
59
|
+
type="/docs/problems/forbidden",
|
|
60
|
+
title=title,
|
|
61
|
+
detail=detail,
|
|
62
|
+
extensions=extensions,
|
|
63
|
+
severity=ExceptionSeverity.WARNING,
|
|
64
|
+
)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
class NotFoundException(ApplicationException):
|
|
68
|
+
"""Raised when a requested resource is not found."""
|
|
69
|
+
|
|
70
|
+
def __init__(
|
|
71
|
+
self,
|
|
72
|
+
detail: str = "The requested resource could not be found.",
|
|
73
|
+
title: str = "Not Found",
|
|
74
|
+
extensions: dict[str, Any] | None = None,
|
|
75
|
+
) -> None:
|
|
76
|
+
super().__init__(type="/docs/problems/not-found", title=title, detail=detail, extensions=extensions)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
class ValidationException(ApplicationException):
|
|
80
|
+
"""Raised when input data fails validation."""
|
|
81
|
+
|
|
82
|
+
def __init__(
|
|
83
|
+
self,
|
|
84
|
+
detail: str = "The received data is invalid.",
|
|
85
|
+
title: str = "Unprocessable Entity",
|
|
86
|
+
extensions: dict[str, Any] | None = None,
|
|
87
|
+
*,
|
|
88
|
+
errors: list[dict[str, Any]] | None = None,
|
|
89
|
+
) -> None:
|
|
90
|
+
super().__init__(
|
|
91
|
+
type="/docs/problems/validation-error", title=title, detail=detail, extensions=extensions, errors=errors
|
|
92
|
+
)
|
|
93
|
+
|
|
94
|
+
|
|
95
|
+
class UnauthorizedException(ApplicationException):
|
|
96
|
+
"""Raised when authentication fails."""
|
|
97
|
+
|
|
98
|
+
def __init__(
|
|
99
|
+
self,
|
|
100
|
+
detail: str = "Token validation failed.",
|
|
101
|
+
title: str = "Unauthorized",
|
|
102
|
+
extensions: dict[str, Any] | None = None,
|
|
103
|
+
) -> None:
|
|
104
|
+
super().__init__(type="/docs/problems/unauthorized", title=title, detail=detail, extensions=extensions)
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
class BusinessRuleViolationException(ApplicationException):
|
|
108
|
+
"""Raised when an operation violates a business rule."""
|
|
109
|
+
|
|
110
|
+
def __init__(
|
|
111
|
+
self,
|
|
112
|
+
detail: str = "The requested operation violates a business rule.",
|
|
113
|
+
title: str = "Business Rule Violation",
|
|
114
|
+
extensions: dict[str, Any] | None = None,
|
|
115
|
+
) -> None:
|
|
116
|
+
super().__init__(
|
|
117
|
+
type="/docs/problems/business-rule-violation", title=title, detail=detail, extensions=extensions
|
|
118
|
+
)
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
class DuplicateException(ApplicationException):
|
|
122
|
+
"""Raised when attempting to create a duplicate resource."""
|
|
123
|
+
|
|
124
|
+
def __init__(
|
|
125
|
+
self,
|
|
126
|
+
detail: str = "A resource with the same identifier already exists.",
|
|
127
|
+
title: str = "Duplicate",
|
|
128
|
+
extensions: dict[str, Any] | None = None,
|
|
129
|
+
) -> None:
|
|
130
|
+
super().__init__(type="/docs/problems/duplicate", title=title, detail=detail, extensions=extensions)
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
class ConflictException(ApplicationException):
|
|
134
|
+
"""Raised when an operation conflicts with the current resource state."""
|
|
135
|
+
|
|
136
|
+
def __init__(
|
|
137
|
+
self,
|
|
138
|
+
detail: str = "The request could not be completed due to a conflict with the current state of the resource.",
|
|
139
|
+
title: str = "Conflict",
|
|
140
|
+
extensions: dict[str, Any] | None = None,
|
|
141
|
+
) -> None:
|
|
142
|
+
super().__init__(type="/docs/problems/conflict", title=title, detail=detail, extensions=extensions)
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
class UpstreamApiException(ApplicationException):
|
|
146
|
+
"""Raised when an upstream API returns an unexpected or malformed response."""
|
|
147
|
+
|
|
148
|
+
def __init__(
|
|
149
|
+
self,
|
|
150
|
+
detail: str = "An upstream API returned an unexpected response.",
|
|
151
|
+
title: str = "Upstream API Error",
|
|
152
|
+
extensions: dict[str, Any] | None = None,
|
|
153
|
+
) -> None:
|
|
154
|
+
super().__init__(
|
|
155
|
+
type="/docs/problems/upstream-api-error",
|
|
156
|
+
title=title,
|
|
157
|
+
detail=detail,
|
|
158
|
+
extensions=extensions,
|
|
159
|
+
severity=ExceptionSeverity.ERROR,
|
|
160
|
+
)
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
# PEP 561 marker for inline type information.
|