# Splurge Exceptions
[](https://pypi.org/project/splurge-exceptions/)
[](https://pypi.org/project/splurge-exceptions/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/jim-schilling/splurge-exceptions/actions/workflows/ci-quick-test.yml)
[](https://github.com/jim-schilling/splurge-exceptions)
[](https://github.com/astral-sh/ruff)
[](https://mypy-lang.org/)
A comprehensive Python exception management library that provides structured error handling, semantic error codes, and intelligent error organization for Splurge projects.
## Quick Start
### Installation
```bash
pip install splurge-exceptions
```
### Basic Usage
#### 1. Create Structured Exceptions
```python
from splurge_exceptions import SplurgeValueError
# Create a semantic exception with context
error = SplurgeValueError(
"Email address format is invalid",
error_code="invalid-email",
details={"provided": "user@", "expected": "user@domain.com"}
)
# Attach context and suggestions
error.attach_context("user_id", 12345)
error.add_suggestion("Use format: username@domain.com")
error.add_suggestion("Verify domain is included")
# Full error code: "splurge.value.invalid-email"
print(error.full_code)
```
#### 2. Convert Exceptions with Chaining
```python
from splurge_exceptions import SplurgeValueError
try:
# Some operation that might fail
int("invalid")
except ValueError as e:
# Wrap the exception with structured error
wrapped = SplurgeValueError(
"Could not parse input as integer",
error_code="invalid-integer",
details={"input": "invalid"}
)
raise wrapped from e
```
#### 3. Format Errors for Users
```python
from splurge_exceptions import ErrorMessageFormatter
formatter = ErrorMessageFormatter()
formatted = formatter.format_error(
error,
include_context=True,
include_suggestions=True,
)
print(formatted)
```
#### 4. Integration Support for Splurge Family Libraries
```python
from splurge_exceptions import SplurgeFrameworkError
class SplurgeSafeIoError(SplurgeFrameworkError):
_domain = "splurge-safe-io"
class SplurgeSafeIoRuntimeError(SplurgeSafeIoError):
_domain = "splurge-safe-io.runtime"
raise SplurgeSafeIoRuntimeError(
"Unexpected error occurred",
error_code="unexpected",
)
# Resulting full error code: "splurge-safe-io.runtime.unexpected"
```
## Key Features
🎯 **Semantic Error Codes** - Hierarchical error codes with domain organization
� **Exception Chaining** - Preserve exception chains with `raise ... from`
📋 **Context Attachment** - Add operation context and recovery suggestions
� **Message Formatting** - Beautiful, structured error message output
� **Type Safe** - Full type annotations with MyPy strict mode support
🎠**Framework Extensions** - Clean extension points for domain-specific exceptions
## Exception Types
Splurge Exceptions provides 9 exception types for different error scenarios:
- `SplurgeError` - Base exception class
- `SplurgeValueError` - Input validation errors
- `SplurgeOSError` - Operating system errors
- `SplurgeRuntimeError` - Runtime execution errors
- `SplurgeTypeError` - Type errors
- `SplurgeAttributeError` - Missing object attributes/methods
- `SplurgeImportError` - Module import failures
- `SplurgeLookupError` - Lookup errors
- `SplurgeFrameworkError` - Framework-level errors
- `SplurgeSubclassError` - Framework misconfiguration errors (used internally)
## Documentation
- **[README-DETAILS.md](docs/README-DETAILS.md)** - Comprehensive feature documentation and examples
- **[API-REFERENCE.md](docs/api/API-REFERENCE.md)** - Complete API reference
- **[CLI-REFERENCE.md](docs/cli/CLI-REFERENCE.md)** - CLI tools reference
- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes
## Project Structure
```
splurge-exceptions/
├── splurge_exceptions/ # Main package
│ ├── core/ # Core exceptions and error codes
│ ├── formatting/ # Message formatting utilities
│ ├── context/ # Context utilities
│ └── cli.py # CLI interface
├── tests/ # Test suite (130+ tests)
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
└── docs/ # Documentation
```
## Testing
The library includes comprehensive test coverage:
- **130 tests** - Unit tests (100% passing)
- **94% code coverage** - All public APIs tested
- **MyPy strict mode** - Full type safety validation
- **Ruff linting** - Code quality enforcement
Run tests:
```bash
pytest tests/
pytest tests/ --cov=splurge_exceptions --cov-report=html
```
## License
MIT License - See [LICENSE](LICENSE) file for details
## Author
Jim Schilling
Raw data
{
"_id": null,
"home_page": null,
"name": "splurge-exceptions",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "exceptions, error-handling, python, splurge",
"author": "Jim Schilling",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/0b/d4/e0abffc0c5fdc2b90e4c9b9c96e17692a6a4783c9857fe3d8ec3f0139985/splurge_exceptions-2025.3.0.tar.gz",
"platform": null,
"description": "# Splurge Exceptions\r\n\r\n[](https://pypi.org/project/splurge-exceptions/)\r\n[](https://pypi.org/project/splurge-exceptions/)\r\n[](https://opensource.org/licenses/MIT)\r\n\r\n[](https://github.com/jim-schilling/splurge-exceptions/actions/workflows/ci-quick-test.yml)\r\n[](https://github.com/jim-schilling/splurge-exceptions)\r\n[](https://github.com/astral-sh/ruff)\r\n[](https://mypy-lang.org/)\r\n\r\n\r\n\r\nA comprehensive Python exception management library that provides structured error handling, semantic error codes, and intelligent error organization for Splurge projects.\r\n\r\n## Quick Start\r\n\r\n### Installation\r\n\r\n```bash\r\npip install splurge-exceptions\r\n```\r\n\r\n### Basic Usage\r\n\r\n#### 1. Create Structured Exceptions\r\n\r\n```python\r\nfrom splurge_exceptions import SplurgeValueError\r\n\r\n# Create a semantic exception with context\r\nerror = SplurgeValueError(\r\n \"Email address format is invalid\",\r\n error_code=\"invalid-email\",\r\n details={\"provided\": \"user@\", \"expected\": \"user@domain.com\"}\r\n)\r\n\r\n# Attach context and suggestions\r\nerror.attach_context(\"user_id\", 12345)\r\nerror.add_suggestion(\"Use format: username@domain.com\")\r\nerror.add_suggestion(\"Verify domain is included\")\r\n\r\n# Full error code: \"splurge.value.invalid-email\"\r\nprint(error.full_code)\r\n```\r\n\r\n#### 2. Convert Exceptions with Chaining\r\n\r\n```python\r\nfrom splurge_exceptions import SplurgeValueError\r\n\r\ntry:\r\n # Some operation that might fail\r\n int(\"invalid\")\r\nexcept ValueError as e:\r\n # Wrap the exception with structured error\r\n wrapped = SplurgeValueError(\r\n \"Could not parse input as integer\",\r\n error_code=\"invalid-integer\",\r\n details={\"input\": \"invalid\"}\r\n )\r\n raise wrapped from e\r\n```\r\n\r\n#### 3. Format Errors for Users\r\n\r\n```python\r\nfrom splurge_exceptions import ErrorMessageFormatter\r\n\r\nformatter = ErrorMessageFormatter()\r\nformatted = formatter.format_error(\r\n error,\r\n include_context=True,\r\n include_suggestions=True,\r\n)\r\nprint(formatted)\r\n```\r\n\r\n#### 4. Integration Support for Splurge Family Libraries\r\n```python\r\nfrom splurge_exceptions import SplurgeFrameworkError\r\n\r\nclass SplurgeSafeIoError(SplurgeFrameworkError):\r\n _domain = \"splurge-safe-io\"\r\n\r\nclass SplurgeSafeIoRuntimeError(SplurgeSafeIoError):\r\n _domain = \"splurge-safe-io.runtime\"\r\n\r\nraise SplurgeSafeIoRuntimeError(\r\n \"Unexpected error occurred\",\r\n error_code=\"unexpected\",\r\n)\r\n# Resulting full error code: \"splurge-safe-io.runtime.unexpected\"\r\n```\r\n\r\n## Key Features\r\n\r\n\ud83c\udfaf **Semantic Error Codes** - Hierarchical error codes with domain organization \r\n\ufffd **Exception Chaining** - Preserve exception chains with `raise ... from` \r\n\ud83d\udccb **Context Attachment** - Add operation context and recovery suggestions \r\n\ufffd **Message Formatting** - Beautiful, structured error message output \r\n\ufffd **Type Safe** - Full type annotations with MyPy strict mode support \r\n\ud83c\udfad **Framework Extensions** - Clean extension points for domain-specific exceptions\r\n\r\n## Exception Types\r\n\r\nSplurge Exceptions provides 9 exception types for different error scenarios:\r\n\r\n- `SplurgeError` - Base exception class\r\n- `SplurgeValueError` - Input validation errors\r\n- `SplurgeOSError` - Operating system errors\r\n- `SplurgeRuntimeError` - Runtime execution errors\r\n- `SplurgeTypeError` - Type errors\r\n- `SplurgeAttributeError` - Missing object attributes/methods\r\n- `SplurgeImportError` - Module import failures\r\n- `SplurgeLookupError` - Lookup errors\r\n- `SplurgeFrameworkError` - Framework-level errors\r\n- `SplurgeSubclassError` - Framework misconfiguration errors (used internally)\r\n\r\n## Documentation\r\n\r\n- **[README-DETAILS.md](docs/README-DETAILS.md)** - Comprehensive feature documentation and examples\r\n- **[API-REFERENCE.md](docs/api/API-REFERENCE.md)** - Complete API reference\r\n- **[CLI-REFERENCE.md](docs/cli/CLI-REFERENCE.md)** - CLI tools reference\r\n- **[CHANGELOG.md](CHANGELOG.md)** - Version history and changes\r\n\r\n## Project Structure\r\n\r\n```\r\nsplurge-exceptions/\r\n\u251c\u2500\u2500 splurge_exceptions/ # Main package\r\n\u2502 \u251c\u2500\u2500 core/ # Core exceptions and error codes\r\n\u2502 \u251c\u2500\u2500 formatting/ # Message formatting utilities\r\n\u2502 \u251c\u2500\u2500 context/ # Context utilities\r\n\u2502 \u2514\u2500\u2500 cli.py # CLI interface\r\n\u251c\u2500\u2500 tests/ # Test suite (130+ tests)\r\n\u2502 \u251c\u2500\u2500 unit/ # Unit tests\r\n\u2502 \u2514\u2500\u2500 integration/ # Integration tests\r\n\u2514\u2500\u2500 docs/ # Documentation\r\n```\r\n\r\n## Testing\r\n\r\nThe library includes comprehensive test coverage:\r\n\r\n- **130 tests** - Unit tests (100% passing)\r\n- **94% code coverage** - All public APIs tested\r\n- **MyPy strict mode** - Full type safety validation\r\n- **Ruff linting** - Code quality enforcement\r\n\r\nRun tests:\r\n```bash\r\npytest tests/\r\npytest tests/ --cov=splurge_exceptions --cov-report=html\r\n```\r\n\r\n## License\r\n\r\nMIT License - See [LICENSE](LICENSE) file for details\r\n\r\n## Author\r\n\r\nJim Schilling\r\n",
"bugtrack_url": null,
"license": null,
"summary": "The standardized exception framework for Splurge projects.",
"version": "2025.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/jim-schilling/splurge-exceptions/issues",
"Documentation": "https://github.com/jim-schilling/splurge-exceptions#readme",
"Homepage": "https://github.com/jim-schilling/splurge-exceptions",
"Repository": "https://github.com/jim-schilling/splurge-exceptions"
},
"split_keywords": [
"exceptions",
" error-handling",
" python",
" splurge"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7db5c8dc3373196aba284a1a06412723ae07770be525d3969706f5351cb453dc",
"md5": "ae6b34024bc701e1652bf8d0d4be1abc",
"sha256": "4af468911024883d8343ff256fc65bf84d65a5534f59d03a464837e6d7a134af"
},
"downloads": -1,
"filename": "splurge_exceptions-2025.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ae6b34024bc701e1652bf8d0d4be1abc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 14679,
"upload_time": "2025-10-29T15:33:36",
"upload_time_iso_8601": "2025-10-29T15:33:36.620132Z",
"url": "https://files.pythonhosted.org/packages/7d/b5/c8dc3373196aba284a1a06412723ae07770be525d3969706f5351cb453dc/splurge_exceptions-2025.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0bd4e0abffc0c5fdc2b90e4c9b9c96e17692a6a4783c9857fe3d8ec3f0139985",
"md5": "174107f4c051b82a91ed04d8d2876362",
"sha256": "9e4837e517af113ceb7fb09a7b2414f94ab7f2cbd755753637ad246c7c00359d"
},
"downloads": -1,
"filename": "splurge_exceptions-2025.3.0.tar.gz",
"has_sig": false,
"md5_digest": "174107f4c051b82a91ed04d8d2876362",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 15106,
"upload_time": "2025-10-29T15:33:37",
"upload_time_iso_8601": "2025-10-29T15:33:37.668336Z",
"url": "https://files.pythonhosted.org/packages/0b/d4/e0abffc0c5fdc2b90e4c9b9c96e17692a6a4783c9857fe3d8ec3f0139985/splurge_exceptions-2025.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-29 15:33:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jim-schilling",
"github_project": "splurge-exceptions",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "splurge-exceptions"
}
JSON
