xeption 1.0.0.0__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.
- xeption-1.0.0.0/LICENSE.txt +102 -0
- xeption-1.0.0.0/PKG-INFO +133 -0
- xeption-1.0.0.0/README.md +110 -0
- xeption-1.0.0.0/pyproject.toml +40 -0
- xeption-1.0.0.0/setup.cfg +4 -0
- xeption-1.0.0.0/src/xeption/__init__.py +8 -0
- xeption-1.0.0.0/src/xeption/py.typed +0 -0
- xeption-1.0.0.0/src/xeption/xeption.py +59 -0
- xeption-1.0.0.0/src/xeption.egg-info/PKG-INFO +133 -0
- xeption-1.0.0.0/src/xeption.egg-info/SOURCES.txt +12 -0
- xeption-1.0.0.0/src/xeption.egg-info/dependency_links.txt +1 -0
- xeption-1.0.0.0/src/xeption.egg-info/requires.txt +3 -0
- xeption-1.0.0.0/src/xeption.egg-info/top_level.txt +1 -0
- xeption-1.0.0.0/tests/test_xeption.py +115 -0
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# The Standard Software License (TSSL)
|
|
2
|
+
Version 1.1
|
|
3
|
+
© [2025] [HASSAN HABIB]
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 0. Ethical Use Condition
|
|
8
|
+
|
|
9
|
+
Software under this license may be used for **personal** or **commercial** purposes.
|
|
10
|
+
We **encourage** its use for **humanitarian** efforts and projects that serve the survival, evolution, and fulfillment of mankind.
|
|
11
|
+
|
|
12
|
+
**However, this software may not be used, directly or indirectly, in any project that contributes to or facilitates:**
|
|
13
|
+
|
|
14
|
+
- The threatening of human survival,
|
|
15
|
+
- The hindrance of human evolution,
|
|
16
|
+
- The diminishment of human fulfillment.
|
|
17
|
+
|
|
18
|
+
This ethical condition is **non-negotiable** and applies to all users, distributors, and modifiers.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 1. Freedom and Sharing
|
|
23
|
+
|
|
24
|
+
Software under this license is free as in **free tea** *and* **free speech**.
|
|
25
|
+
|
|
26
|
+
It is encouraged to be:
|
|
27
|
+
|
|
28
|
+
- **Used** freely, as long as the Ethical Use Condition is upheld.
|
|
29
|
+
- **Modified** to improve and adapt it to new use cases.
|
|
30
|
+
- **Distributed** in original or modified form.
|
|
31
|
+
- **Studied and learned from** as a tool for innovation and education.
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## 2. License and Attribution
|
|
36
|
+
|
|
37
|
+
- This license **must remain attached** to all original and modified versions of the software.
|
|
38
|
+
- If you modify this software, you must **clearly state your changes**.
|
|
39
|
+
- You may not **misrepresent** the origin of the software or claim original authorship of unmodified parts.
|
|
40
|
+
|
|
41
|
+
---
|
|
42
|
+
|
|
43
|
+
## 3. AI and Automation
|
|
44
|
+
|
|
45
|
+
If this software is used in **artificial intelligence systems**, **automated decision-making**, or **data-driven platforms**, the implementers must:
|
|
46
|
+
|
|
47
|
+
- **Evaluate** the application’s compliance with the Ethical Use Condition (section 0),
|
|
48
|
+
- **Mitigate** any foreseeable risks that may violate that condition,
|
|
49
|
+
- **Document** how the use aligns with the license’s ethical principles.
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## 4. Irrevocability and Permanence of Freedom
|
|
54
|
+
|
|
55
|
+
- This license is **perpetual and irrevocable**.
|
|
56
|
+
- Once software is released under this license, the author **cannot revoke**, **re-license**, or **retroactively restrict** its freedoms.
|
|
57
|
+
- Future versions of *The Standard Software License* may be released to clarify or extend its terms, but **existing licensed software remains bound to its original version**.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## 5. Commercial Use and Non-Monetization of the Licensed Software
|
|
62
|
+
|
|
63
|
+
- You may use this software in **commercial projects**, businesses, and for-profit environments.
|
|
64
|
+
- You may **charge for services** (e.g. support, consulting, hosting, integrations) built **around** this software.
|
|
65
|
+
- However, you **may not sell, license, or charge for** access, usage, distribution, or copies of the software itself.
|
|
66
|
+
|
|
67
|
+
> You can profit **with it**, but not **from it directly**.
|
|
68
|
+
|
|
69
|
+
This ensures that once made free, the software remains free forever—regardless of popularity or success.
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## 5.1 Third Party License Compliance
|
|
74
|
+
|
|
75
|
+
- Any use of this Software, including Commercial Use, that incorporates or depends on third-party software must fully comply with the license terms of those third-party components.
|
|
76
|
+
- This license does not grant permission to use any third-party software in a way that violates its own license terms.
|
|
77
|
+
- The inclusion of third-party software in any distribution of this Software does not constitute an authorization or waiver of those third-party license restrictions.
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## 6. Derivative and Combined Works
|
|
82
|
+
|
|
83
|
+
- If this software is combined with other software, the portions under this license must **continue to follow these terms**, including the Ethical Use Condition and Non-Monetization rule.
|
|
84
|
+
- Derivative works must clearly separate code under this license if the resulting project uses different licensing for other components.
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## 7. No Warranty
|
|
89
|
+
|
|
90
|
+
This software is provided **"as-is"**, without warranty of any kind.
|
|
91
|
+
The authors are **not liable** for any damages or misuse, except where such liability arises from **intentional violation** of the Ethical Use Condition.
|
|
92
|
+
|
|
93
|
+
---
|
|
94
|
+
|
|
95
|
+
## TL;DR
|
|
96
|
+
|
|
97
|
+
✅ Use it personally or commercially
|
|
98
|
+
✅ Learn, teach, modify, share
|
|
99
|
+
✅ Use it to help humanity
|
|
100
|
+
❌ Don’t charge for the software itself
|
|
101
|
+
❌ Don’t use it for harm
|
|
102
|
+
🚫 You can’t take the freedom back later
|
xeption-1.0.0.0/PKG-INFO
ADDED
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: xeption
|
|
3
|
+
Version: 1.0.0.0
|
|
4
|
+
Summary: Exceptions that carry their validation data and compare by value: the Python port of The Standard's Xeption library.
|
|
5
|
+
Author-email: Hassan Habib <hassanhabib@live.com>
|
|
6
|
+
License-Expression: LicenseRef-TSSL-1.1
|
|
7
|
+
Project-URL: Homepage, https://github.com/hassanhabib/Xeption-Python
|
|
8
|
+
Project-URL: C# Library, https://github.com/The-Standard-Organization/Xeption
|
|
9
|
+
Keywords: exceptions,validation,the-standard,xeption
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Typing :: Typed
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE.txt
|
|
20
|
+
Provides-Extra: test
|
|
21
|
+
Requires-Dist: pytest>=8; extra == "test"
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
# Xeption for Python
|
|
25
|
+
|
|
26
|
+
An exception that carries its data. The Python port of [Xeption](https://github.com/The-Standard-Organization/Xeption),
|
|
27
|
+
the library [The Standard](https://github.com/hassanhabib/The-Standard) uses to collect validation
|
|
28
|
+
errors before breaking the circuit, and to compare exceptions by value in tests.
|
|
29
|
+
|
|
30
|
+
The C# library decides the behaviour; this package decides how it reads in Python. It has no
|
|
31
|
+
runtime dependencies.
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
python -m pip install xeption
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Collecting validation errors
|
|
38
|
+
|
|
39
|
+
A validation routine upserts every failure it finds into one exception, then raises it once:
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
from xeption import Xeption
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class InvalidStudentException(Xeption):
|
|
46
|
+
def __init__(self) -> None:
|
|
47
|
+
super().__init__(message="Invalid student. Please correct the errors and try again.")
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def validate_student(student: dict) -> None:
|
|
51
|
+
invalid_student_exception = InvalidStudentException()
|
|
52
|
+
|
|
53
|
+
if not student.get("name"):
|
|
54
|
+
invalid_student_exception.upsert_data_list("name", "Text is required")
|
|
55
|
+
|
|
56
|
+
if not student.get("email"):
|
|
57
|
+
invalid_student_exception.upsert_data_list("email", "Text is required")
|
|
58
|
+
|
|
59
|
+
invalid_student_exception.throw_if_contains_errors()
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
`data` maps each key to the list of messages collected for it, so the caller sees every error at
|
|
63
|
+
once rather than the first.
|
|
64
|
+
|
|
65
|
+
## Wrapping an exception
|
|
66
|
+
|
|
67
|
+
A foundation localizes a native exception by wrapping it. The inner exception is kept as
|
|
68
|
+
`inner_exception` and is also the `__cause__`, so tracebacks show the chain:
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
class FailedStudentStorageException(Xeption):
|
|
72
|
+
def __init__(self, inner_exception: BaseException) -> None:
|
|
73
|
+
super().__init__(
|
|
74
|
+
message="Failed student storage error occurred, contact support.",
|
|
75
|
+
inner_exception=inner_exception)
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`add_data` copies another exception's data in, which is how a dependency's validation details
|
|
79
|
+
travel up with the local exception.
|
|
80
|
+
|
|
81
|
+
## Comparing exceptions in tests
|
|
82
|
+
|
|
83
|
+
`same_exception_as` is equivalence, not identity: the same type, message and data, all the way down
|
|
84
|
+
the chain of inner exceptions. A native inner exception carries no data, so its type and arguments
|
|
85
|
+
are what make it the same.
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
assert actual_exception.same_exception_as(expected_exception)
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## API
|
|
92
|
+
|
|
93
|
+
| Python | C# |
|
|
94
|
+
|---|---|
|
|
95
|
+
| `Xeption(message="", inner_exception=None)` | `Xeption()`, `Xeption(message)`, `Xeption(message, innerException)` |
|
|
96
|
+
| `upsert_data_list(key, value)` | `UpsertDataList(key, value)` |
|
|
97
|
+
| `add_data(data)` | `AddData(IDictionary)` |
|
|
98
|
+
| `throw_if_contains_errors()` | `ThrowIfContainsErrors()` |
|
|
99
|
+
| `same_exception_as(other)` | `SameExceptionAs(otherException)` |
|
|
100
|
+
|
|
101
|
+
### Not ported yet
|
|
102
|
+
|
|
103
|
+
These parts of the C# library have no Python counterpart in this version:
|
|
104
|
+
|
|
105
|
+
- the constructors that take a data dictionary, and `AddData(key, params values)`;
|
|
106
|
+
- `DataEquals` and `DataEqualsWithDetail`, and the `out message` overload of `SameExceptionAs`
|
|
107
|
+
that explains a mismatch;
|
|
108
|
+
- `AggregateException` comparison (Python's `ExceptionGroup`);
|
|
109
|
+
- `IsFrom` and `IsNotFrom`;
|
|
110
|
+
- the FluentAssertions extensions.
|
|
111
|
+
|
|
112
|
+
## The Standard
|
|
113
|
+
|
|
114
|
+
This library is part of [The Standard](https://github.com/hassanhabib/The-Standard)
|
|
115
|
+
family and is built to its rules for naming, layering and testing.
|
|
116
|
+
|
|
117
|
+
Questions, ideas and contributions are welcome in
|
|
118
|
+
[The Standard Community](https://discord.gg/vdPZ7hS52X) on Discord.
|
|
119
|
+
|
|
120
|
+
## In other languages
|
|
121
|
+
|
|
122
|
+
| Language | Repository | Package |
|
|
123
|
+
|---|---|---|
|
|
124
|
+
| C# | [Xeption](https://github.com/The-Standard-Organization/Xeption) | [Xeption on NuGet](https://www.nuget.org/packages/Xeption) |
|
|
125
|
+
| Python | [Xeption-Python](https://github.com/hassanhabib/Xeption-Python) | [xeption on PyPI](https://pypi.org/project/xeption/) |
|
|
126
|
+
|
|
127
|
+
## Contributing
|
|
128
|
+
|
|
129
|
+
See [CONTRIBUTING.md](https://github.com/hassanhabib/Xeption-Python/blob/main/CONTRIBUTING.md).
|
|
130
|
+
|
|
131
|
+
## License
|
|
132
|
+
|
|
133
|
+
[The Standard Software License (TSSL) v1.1](https://github.com/hassanhabib/Xeption-Python/blob/main/LICENSE.txt).
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Xeption for Python
|
|
2
|
+
|
|
3
|
+
An exception that carries its data. The Python port of [Xeption](https://github.com/The-Standard-Organization/Xeption),
|
|
4
|
+
the library [The Standard](https://github.com/hassanhabib/The-Standard) uses to collect validation
|
|
5
|
+
errors before breaking the circuit, and to compare exceptions by value in tests.
|
|
6
|
+
|
|
7
|
+
The C# library decides the behaviour; this package decides how it reads in Python. It has no
|
|
8
|
+
runtime dependencies.
|
|
9
|
+
|
|
10
|
+
```bash
|
|
11
|
+
python -m pip install xeption
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Collecting validation errors
|
|
15
|
+
|
|
16
|
+
A validation routine upserts every failure it finds into one exception, then raises it once:
|
|
17
|
+
|
|
18
|
+
```python
|
|
19
|
+
from xeption import Xeption
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class InvalidStudentException(Xeption):
|
|
23
|
+
def __init__(self) -> None:
|
|
24
|
+
super().__init__(message="Invalid student. Please correct the errors and try again.")
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def validate_student(student: dict) -> None:
|
|
28
|
+
invalid_student_exception = InvalidStudentException()
|
|
29
|
+
|
|
30
|
+
if not student.get("name"):
|
|
31
|
+
invalid_student_exception.upsert_data_list("name", "Text is required")
|
|
32
|
+
|
|
33
|
+
if not student.get("email"):
|
|
34
|
+
invalid_student_exception.upsert_data_list("email", "Text is required")
|
|
35
|
+
|
|
36
|
+
invalid_student_exception.throw_if_contains_errors()
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
`data` maps each key to the list of messages collected for it, so the caller sees every error at
|
|
40
|
+
once rather than the first.
|
|
41
|
+
|
|
42
|
+
## Wrapping an exception
|
|
43
|
+
|
|
44
|
+
A foundation localizes a native exception by wrapping it. The inner exception is kept as
|
|
45
|
+
`inner_exception` and is also the `__cause__`, so tracebacks show the chain:
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
class FailedStudentStorageException(Xeption):
|
|
49
|
+
def __init__(self, inner_exception: BaseException) -> None:
|
|
50
|
+
super().__init__(
|
|
51
|
+
message="Failed student storage error occurred, contact support.",
|
|
52
|
+
inner_exception=inner_exception)
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
`add_data` copies another exception's data in, which is how a dependency's validation details
|
|
56
|
+
travel up with the local exception.
|
|
57
|
+
|
|
58
|
+
## Comparing exceptions in tests
|
|
59
|
+
|
|
60
|
+
`same_exception_as` is equivalence, not identity: the same type, message and data, all the way down
|
|
61
|
+
the chain of inner exceptions. A native inner exception carries no data, so its type and arguments
|
|
62
|
+
are what make it the same.
|
|
63
|
+
|
|
64
|
+
```python
|
|
65
|
+
assert actual_exception.same_exception_as(expected_exception)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## API
|
|
69
|
+
|
|
70
|
+
| Python | C# |
|
|
71
|
+
|---|---|
|
|
72
|
+
| `Xeption(message="", inner_exception=None)` | `Xeption()`, `Xeption(message)`, `Xeption(message, innerException)` |
|
|
73
|
+
| `upsert_data_list(key, value)` | `UpsertDataList(key, value)` |
|
|
74
|
+
| `add_data(data)` | `AddData(IDictionary)` |
|
|
75
|
+
| `throw_if_contains_errors()` | `ThrowIfContainsErrors()` |
|
|
76
|
+
| `same_exception_as(other)` | `SameExceptionAs(otherException)` |
|
|
77
|
+
|
|
78
|
+
### Not ported yet
|
|
79
|
+
|
|
80
|
+
These parts of the C# library have no Python counterpart in this version:
|
|
81
|
+
|
|
82
|
+
- the constructors that take a data dictionary, and `AddData(key, params values)`;
|
|
83
|
+
- `DataEquals` and `DataEqualsWithDetail`, and the `out message` overload of `SameExceptionAs`
|
|
84
|
+
that explains a mismatch;
|
|
85
|
+
- `AggregateException` comparison (Python's `ExceptionGroup`);
|
|
86
|
+
- `IsFrom` and `IsNotFrom`;
|
|
87
|
+
- the FluentAssertions extensions.
|
|
88
|
+
|
|
89
|
+
## The Standard
|
|
90
|
+
|
|
91
|
+
This library is part of [The Standard](https://github.com/hassanhabib/The-Standard)
|
|
92
|
+
family and is built to its rules for naming, layering and testing.
|
|
93
|
+
|
|
94
|
+
Questions, ideas and contributions are welcome in
|
|
95
|
+
[The Standard Community](https://discord.gg/vdPZ7hS52X) on Discord.
|
|
96
|
+
|
|
97
|
+
## In other languages
|
|
98
|
+
|
|
99
|
+
| Language | Repository | Package |
|
|
100
|
+
|---|---|---|
|
|
101
|
+
| C# | [Xeption](https://github.com/The-Standard-Organization/Xeption) | [Xeption on NuGet](https://www.nuget.org/packages/Xeption) |
|
|
102
|
+
| Python | [Xeption-Python](https://github.com/hassanhabib/Xeption-Python) | [xeption on PyPI](https://pypi.org/project/xeption/) |
|
|
103
|
+
|
|
104
|
+
## Contributing
|
|
105
|
+
|
|
106
|
+
See [CONTRIBUTING.md](https://github.com/hassanhabib/Xeption-Python/blob/main/CONTRIBUTING.md).
|
|
107
|
+
|
|
108
|
+
## License
|
|
109
|
+
|
|
110
|
+
[The Standard Software License (TSSL) v1.1](https://github.com/hassanhabib/Xeption-Python/blob/main/LICENSE.txt).
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "xeption"
|
|
7
|
+
version = "1.0.0.0"
|
|
8
|
+
description = "Exceptions that carry their validation data and compare by value: the Python port of The Standard's Xeption library."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "LicenseRef-TSSL-1.1"
|
|
12
|
+
license-files = ["LICENSE.txt"]
|
|
13
|
+
authors = [{ name = "Hassan Habib", email = "hassanhabib@live.com" }]
|
|
14
|
+
keywords = ["exceptions", "validation", "the-standard", "xeption"]
|
|
15
|
+
classifiers = [
|
|
16
|
+
"Development Status :: 3 - Alpha",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Programming Language :: Python :: 3.10",
|
|
20
|
+
"Programming Language :: Python :: 3.11",
|
|
21
|
+
"Programming Language :: Python :: 3.12",
|
|
22
|
+
"Typing :: Typed",
|
|
23
|
+
]
|
|
24
|
+
dependencies = []
|
|
25
|
+
|
|
26
|
+
[project.optional-dependencies]
|
|
27
|
+
test = ["pytest>=8"]
|
|
28
|
+
|
|
29
|
+
[project.urls]
|
|
30
|
+
Homepage = "https://github.com/hassanhabib/Xeption-Python"
|
|
31
|
+
"C# Library" = "https://github.com/The-Standard-Organization/Xeption"
|
|
32
|
+
|
|
33
|
+
[tool.setuptools.packages.find]
|
|
34
|
+
where = ["src"]
|
|
35
|
+
|
|
36
|
+
[tool.setuptools.package-data]
|
|
37
|
+
xeption = ["py.typed"]
|
|
38
|
+
|
|
39
|
+
[tool.pytest.ini_options]
|
|
40
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
# ---------------------------------------------------------------
|
|
2
|
+
# Copyright (c) Hassan Habib All rights reserved.
|
|
3
|
+
# Licensed under the The Standard Software License (TSSL)
|
|
4
|
+
# ---------------------------------------------------------------
|
|
5
|
+
|
|
6
|
+
from xeption.xeption import Xeption
|
|
7
|
+
|
|
8
|
+
__all__ = ["Xeption"]
|
|
File without changes
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
# ---------------------------------------------------------------
|
|
2
|
+
# Copyright (c) Hassan Habib All rights reserved.
|
|
3
|
+
# Licensed under the The Standard Software License (TSSL)
|
|
4
|
+
# ---------------------------------------------------------------
|
|
5
|
+
|
|
6
|
+
# The Python port of the Xeption library: an exception that carries a message, the exception it
|
|
7
|
+
# localizes, and a data dictionary that validations accumulate into before they break the
|
|
8
|
+
# circuit.
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class Xeption(Exception):
|
|
12
|
+
def __init__(
|
|
13
|
+
self,
|
|
14
|
+
message: str = "",
|
|
15
|
+
inner_exception: BaseException | None = None) -> None:
|
|
16
|
+
|
|
17
|
+
super().__init__(message)
|
|
18
|
+
self.message = message
|
|
19
|
+
self.inner_exception = inner_exception
|
|
20
|
+
self.data: dict[str, list[str]] = {}
|
|
21
|
+
self.__cause__ = inner_exception
|
|
22
|
+
|
|
23
|
+
def upsert_data_list(self, key: str, value: str) -> None:
|
|
24
|
+
self.data.setdefault(key, []).append(value)
|
|
25
|
+
|
|
26
|
+
def add_data(self, data: dict[str, list[str]]) -> None:
|
|
27
|
+
for key, values in data.items():
|
|
28
|
+
for value in values:
|
|
29
|
+
self.upsert_data_list(key, value)
|
|
30
|
+
|
|
31
|
+
def throw_if_contains_errors(self) -> None:
|
|
32
|
+
if self.data:
|
|
33
|
+
raise self
|
|
34
|
+
|
|
35
|
+
# Equivalence, not identity: the same type, message and data, all the way down the chain of
|
|
36
|
+
# inner exceptions. A native inner exception carries no data, so its type and arguments are
|
|
37
|
+
# what make it the same.
|
|
38
|
+
def same_exception_as(self, other: BaseException | None) -> bool:
|
|
39
|
+
if type(other) is not type(self):
|
|
40
|
+
return False
|
|
41
|
+
|
|
42
|
+
if other.message != self.message or other.data != self.data:
|
|
43
|
+
return False
|
|
44
|
+
|
|
45
|
+
return same_inner_exception(self.inner_exception, other.inner_exception)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def same_inner_exception(
|
|
49
|
+
expected_exception: BaseException | None,
|
|
50
|
+
actual_exception: BaseException | None) -> bool:
|
|
51
|
+
|
|
52
|
+
if isinstance(expected_exception, Xeption):
|
|
53
|
+
return expected_exception.same_exception_as(actual_exception)
|
|
54
|
+
|
|
55
|
+
if expected_exception is None or actual_exception is None:
|
|
56
|
+
return expected_exception is actual_exception
|
|
57
|
+
|
|
58
|
+
return (type(expected_exception) is type(actual_exception)
|
|
59
|
+
and expected_exception.args == actual_exception.args)
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: xeption
|
|
3
|
+
Version: 1.0.0.0
|
|
4
|
+
Summary: Exceptions that carry their validation data and compare by value: the Python port of The Standard's Xeption library.
|
|
5
|
+
Author-email: Hassan Habib <hassanhabib@live.com>
|
|
6
|
+
License-Expression: LicenseRef-TSSL-1.1
|
|
7
|
+
Project-URL: Homepage, https://github.com/hassanhabib/Xeption-Python
|
|
8
|
+
Project-URL: C# Library, https://github.com/The-Standard-Organization/Xeption
|
|
9
|
+
Keywords: exceptions,validation,the-standard,xeption
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Typing :: Typed
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE.txt
|
|
20
|
+
Provides-Extra: test
|
|
21
|
+
Requires-Dist: pytest>=8; extra == "test"
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
# Xeption for Python
|
|
25
|
+
|
|
26
|
+
An exception that carries its data. The Python port of [Xeption](https://github.com/The-Standard-Organization/Xeption),
|
|
27
|
+
the library [The Standard](https://github.com/hassanhabib/The-Standard) uses to collect validation
|
|
28
|
+
errors before breaking the circuit, and to compare exceptions by value in tests.
|
|
29
|
+
|
|
30
|
+
The C# library decides the behaviour; this package decides how it reads in Python. It has no
|
|
31
|
+
runtime dependencies.
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
python -m pip install xeption
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Collecting validation errors
|
|
38
|
+
|
|
39
|
+
A validation routine upserts every failure it finds into one exception, then raises it once:
|
|
40
|
+
|
|
41
|
+
```python
|
|
42
|
+
from xeption import Xeption
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class InvalidStudentException(Xeption):
|
|
46
|
+
def __init__(self) -> None:
|
|
47
|
+
super().__init__(message="Invalid student. Please correct the errors and try again.")
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def validate_student(student: dict) -> None:
|
|
51
|
+
invalid_student_exception = InvalidStudentException()
|
|
52
|
+
|
|
53
|
+
if not student.get("name"):
|
|
54
|
+
invalid_student_exception.upsert_data_list("name", "Text is required")
|
|
55
|
+
|
|
56
|
+
if not student.get("email"):
|
|
57
|
+
invalid_student_exception.upsert_data_list("email", "Text is required")
|
|
58
|
+
|
|
59
|
+
invalid_student_exception.throw_if_contains_errors()
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
`data` maps each key to the list of messages collected for it, so the caller sees every error at
|
|
63
|
+
once rather than the first.
|
|
64
|
+
|
|
65
|
+
## Wrapping an exception
|
|
66
|
+
|
|
67
|
+
A foundation localizes a native exception by wrapping it. The inner exception is kept as
|
|
68
|
+
`inner_exception` and is also the `__cause__`, so tracebacks show the chain:
|
|
69
|
+
|
|
70
|
+
```python
|
|
71
|
+
class FailedStudentStorageException(Xeption):
|
|
72
|
+
def __init__(self, inner_exception: BaseException) -> None:
|
|
73
|
+
super().__init__(
|
|
74
|
+
message="Failed student storage error occurred, contact support.",
|
|
75
|
+
inner_exception=inner_exception)
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`add_data` copies another exception's data in, which is how a dependency's validation details
|
|
79
|
+
travel up with the local exception.
|
|
80
|
+
|
|
81
|
+
## Comparing exceptions in tests
|
|
82
|
+
|
|
83
|
+
`same_exception_as` is equivalence, not identity: the same type, message and data, all the way down
|
|
84
|
+
the chain of inner exceptions. A native inner exception carries no data, so its type and arguments
|
|
85
|
+
are what make it the same.
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
assert actual_exception.same_exception_as(expected_exception)
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## API
|
|
92
|
+
|
|
93
|
+
| Python | C# |
|
|
94
|
+
|---|---|
|
|
95
|
+
| `Xeption(message="", inner_exception=None)` | `Xeption()`, `Xeption(message)`, `Xeption(message, innerException)` |
|
|
96
|
+
| `upsert_data_list(key, value)` | `UpsertDataList(key, value)` |
|
|
97
|
+
| `add_data(data)` | `AddData(IDictionary)` |
|
|
98
|
+
| `throw_if_contains_errors()` | `ThrowIfContainsErrors()` |
|
|
99
|
+
| `same_exception_as(other)` | `SameExceptionAs(otherException)` |
|
|
100
|
+
|
|
101
|
+
### Not ported yet
|
|
102
|
+
|
|
103
|
+
These parts of the C# library have no Python counterpart in this version:
|
|
104
|
+
|
|
105
|
+
- the constructors that take a data dictionary, and `AddData(key, params values)`;
|
|
106
|
+
- `DataEquals` and `DataEqualsWithDetail`, and the `out message` overload of `SameExceptionAs`
|
|
107
|
+
that explains a mismatch;
|
|
108
|
+
- `AggregateException` comparison (Python's `ExceptionGroup`);
|
|
109
|
+
- `IsFrom` and `IsNotFrom`;
|
|
110
|
+
- the FluentAssertions extensions.
|
|
111
|
+
|
|
112
|
+
## The Standard
|
|
113
|
+
|
|
114
|
+
This library is part of [The Standard](https://github.com/hassanhabib/The-Standard)
|
|
115
|
+
family and is built to its rules for naming, layering and testing.
|
|
116
|
+
|
|
117
|
+
Questions, ideas and contributions are welcome in
|
|
118
|
+
[The Standard Community](https://discord.gg/vdPZ7hS52X) on Discord.
|
|
119
|
+
|
|
120
|
+
## In other languages
|
|
121
|
+
|
|
122
|
+
| Language | Repository | Package |
|
|
123
|
+
|---|---|---|
|
|
124
|
+
| C# | [Xeption](https://github.com/The-Standard-Organization/Xeption) | [Xeption on NuGet](https://www.nuget.org/packages/Xeption) |
|
|
125
|
+
| Python | [Xeption-Python](https://github.com/hassanhabib/Xeption-Python) | [xeption on PyPI](https://pypi.org/project/xeption/) |
|
|
126
|
+
|
|
127
|
+
## Contributing
|
|
128
|
+
|
|
129
|
+
See [CONTRIBUTING.md](https://github.com/hassanhabib/Xeption-Python/blob/main/CONTRIBUTING.md).
|
|
130
|
+
|
|
131
|
+
## License
|
|
132
|
+
|
|
133
|
+
[The Standard Software License (TSSL) v1.1](https://github.com/hassanhabib/Xeption-Python/blob/main/LICENSE.txt).
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
LICENSE.txt
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
src/xeption/__init__.py
|
|
5
|
+
src/xeption/py.typed
|
|
6
|
+
src/xeption/xeption.py
|
|
7
|
+
src/xeption.egg-info/PKG-INFO
|
|
8
|
+
src/xeption.egg-info/SOURCES.txt
|
|
9
|
+
src/xeption.egg-info/dependency_links.txt
|
|
10
|
+
src/xeption.egg-info/requires.txt
|
|
11
|
+
src/xeption.egg-info/top_level.txt
|
|
12
|
+
tests/test_xeption.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
xeption
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# ---------------------------------------------------------------
|
|
2
|
+
# Copyright (c) Hassan Habib All rights reserved.
|
|
3
|
+
# Licensed under the The Standard Software License (TSSL)
|
|
4
|
+
# ---------------------------------------------------------------
|
|
5
|
+
|
|
6
|
+
import uuid
|
|
7
|
+
|
|
8
|
+
from xeption import Xeption
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def create_random_string() -> str:
|
|
12
|
+
return uuid.uuid4().hex
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
class TestXeption:
|
|
16
|
+
def test_should_upsert_data_list(self) -> None:
|
|
17
|
+
# given
|
|
18
|
+
random_key = create_random_string()
|
|
19
|
+
random_first_value = create_random_string()
|
|
20
|
+
random_second_value = create_random_string()
|
|
21
|
+
xeption = Xeption(message=create_random_string())
|
|
22
|
+
|
|
23
|
+
expected_data = {
|
|
24
|
+
random_key: [random_first_value, random_second_value]
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
# when
|
|
28
|
+
xeption.upsert_data_list(random_key, random_first_value)
|
|
29
|
+
xeption.upsert_data_list(random_key, random_second_value)
|
|
30
|
+
|
|
31
|
+
# then
|
|
32
|
+
assert xeption.data == expected_data
|
|
33
|
+
|
|
34
|
+
def test_should_throw_if_contains_errors(self) -> None:
|
|
35
|
+
# given
|
|
36
|
+
xeption = Xeption(message=create_random_string())
|
|
37
|
+
xeption.upsert_data_list(create_random_string(), create_random_string())
|
|
38
|
+
actual_xeption = None
|
|
39
|
+
|
|
40
|
+
# when
|
|
41
|
+
try:
|
|
42
|
+
xeption.throw_if_contains_errors()
|
|
43
|
+
except Xeption as raised_xeption:
|
|
44
|
+
actual_xeption = raised_xeption
|
|
45
|
+
|
|
46
|
+
# then
|
|
47
|
+
assert actual_xeption is xeption
|
|
48
|
+
|
|
49
|
+
def test_should_not_throw_if_contains_no_errors(self) -> None:
|
|
50
|
+
# given
|
|
51
|
+
xeption = Xeption(message=create_random_string())
|
|
52
|
+
|
|
53
|
+
# when
|
|
54
|
+
xeption.throw_if_contains_errors()
|
|
55
|
+
|
|
56
|
+
# then
|
|
57
|
+
assert xeption.data == {}
|
|
58
|
+
|
|
59
|
+
def test_should_add_data(self) -> None:
|
|
60
|
+
# given
|
|
61
|
+
random_key = create_random_string()
|
|
62
|
+
random_existing_value = create_random_string()
|
|
63
|
+
random_added_value = create_random_string()
|
|
64
|
+
xeption = Xeption(message=create_random_string())
|
|
65
|
+
xeption.upsert_data_list(random_key, random_existing_value)
|
|
66
|
+
input_data = {random_key: [random_added_value]}
|
|
67
|
+
|
|
68
|
+
expected_data = {
|
|
69
|
+
random_key: [random_existing_value, random_added_value]
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
# when
|
|
73
|
+
xeption.add_data(input_data)
|
|
74
|
+
|
|
75
|
+
# then
|
|
76
|
+
assert xeption.data == expected_data
|
|
77
|
+
|
|
78
|
+
def test_should_tell_whether_exceptions_are_the_same(self) -> None:
|
|
79
|
+
# given
|
|
80
|
+
random_message = create_random_string()
|
|
81
|
+
random_key = create_random_string()
|
|
82
|
+
random_value = create_random_string()
|
|
83
|
+
native_exception = RuntimeError(random_message)
|
|
84
|
+
|
|
85
|
+
def create_xeption() -> Xeption:
|
|
86
|
+
inner_xeption = Xeption(
|
|
87
|
+
message=random_message,
|
|
88
|
+
inner_exception=native_exception)
|
|
89
|
+
|
|
90
|
+
inner_xeption.upsert_data_list(random_key, random_value)
|
|
91
|
+
|
|
92
|
+
return Xeption(message=random_message, inner_exception=inner_xeption)
|
|
93
|
+
|
|
94
|
+
expected_xeption = create_xeption()
|
|
95
|
+
same_xeption = create_xeption()
|
|
96
|
+
other_message_xeption = Xeption(message=create_random_string())
|
|
97
|
+
|
|
98
|
+
other_inner_xeption = Xeption(
|
|
99
|
+
message=random_message,
|
|
100
|
+
inner_exception=Xeption(message=create_random_string()))
|
|
101
|
+
|
|
102
|
+
other_data_xeption = create_xeption()
|
|
103
|
+
other_data_xeption.inner_exception.upsert_data_list(random_key, random_value)
|
|
104
|
+
|
|
105
|
+
# when
|
|
106
|
+
actual_results = [
|
|
107
|
+
expected_xeption.same_exception_as(same_xeption),
|
|
108
|
+
expected_xeption.same_exception_as(other_message_xeption),
|
|
109
|
+
expected_xeption.same_exception_as(other_inner_xeption),
|
|
110
|
+
expected_xeption.same_exception_as(other_data_xeption),
|
|
111
|
+
expected_xeption.same_exception_as(None)
|
|
112
|
+
]
|
|
113
|
+
|
|
114
|
+
# then
|
|
115
|
+
assert actual_results == [True, False, False, False, False]
|