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.
@@ -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.