# Introducing Gaffe: Streamlined Exception Handling for Python
Are you tired of managing messy, unstructured exceptions in your Python projects? Gaffe is here to save the day! This elegant library offers a metaclass-based approach for highly extensible and easy-to-integrate custom exceptions, leading to better error handling and improved code readability.
## 🔥 Key Features
- 🎯 Simple, concise syntax for defining custom errors with optional subtypes
- 🧩 Clean integration through metaclass-based approach
- 🌳 Supports inheritance and composition of custom errors
- 🏗️ Automatic generation of error classes with custom attributes
- 🧮 Easy error comparison with the __eq__ method, supporting both class and instance comparisons
- 🕵️♂️ raises decorator to inspect and validate exceptions raised by functions or methods
- 🚀 Quick Installation
For pip enthusiasts:
```bash
pip install gaffe
```
For poetry aficionados:
```bash
poetry add gaffe
```
# 💡 Getting Started
To employ Gaffe's custom error system, import the Error class and create custom errors by inheriting from it:
```python
from gaffe import Error
class NotFoundError(Exception):
...
class MyError(Error):
not_found: NotFoundError
invalid_input: ...
authentication_error = "authentication_error"
```
With this example, you'll get three custom errors under the MyError class, ready to be used just like any other Python exceptions.
## 🎩 Raises Decorator
Harness the power of the raises decorator to define and validate the types of exceptions a function or method can raise:
```python
from gaffe import raises
@raises(TypeError, ValueError)
def my_function(x: int, y: int) -> float:
if x <= 0 or y <= 0:
raise ValueError("x and y must be positive")
return x / y
```
The raises decorator ensures that my_function can only raise TypeError and ValueError. If it tries to raise an unlisted exception, an AssertionError will be raised with a suitable error message.
## 🤖 Mypy Integration
To keep mypy happy, use the gaffe.mypy:plugin in your config file, and ensure that error properties are annotated with `Exception` type instead of `...`
```toml
[tool.mypy]
plugins = "gaffe.mypy:plugin"
```
Ready to revolutionize your Python exception handling? Get started with Gaffe today and check out the test scenarios for more examples!
Raw data
{
"_id": null,
"home_page": "https://github.com/kodemore/gaffe",
"name": "gaffe",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "error,exception,structured,simple,gaffe",
"author": "Dawid Kraczkowski",
"author_email": "dawid.kraczkowski@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/df/63/f6903f5c1bd0472e1fa842ae89514cbd527cf8e11d8f60b5eff70c29637e/gaffe-0.3.0.tar.gz",
"platform": null,
"description": "# Introducing Gaffe: Streamlined Exception Handling for Python\n\nAre you tired of managing messy, unstructured exceptions in your Python projects? Gaffe is here to save the day! This elegant library offers a metaclass-based approach for highly extensible and easy-to-integrate custom exceptions, leading to better error handling and improved code readability.\n\n## \ud83d\udd25 Key Features\n\n- \ud83c\udfaf Simple, concise syntax for defining custom errors with optional subtypes\n- \ud83e\udde9 Clean integration through metaclass-based approach\n- \ud83c\udf33 Supports inheritance and composition of custom errors\n- \ud83c\udfd7\ufe0f Automatic generation of error classes with custom attributes\n- \ud83e\uddee Easy error comparison with the __eq__ method, supporting both class and instance comparisons\n- \ud83d\udd75\ufe0f\u200d\u2642\ufe0f raises decorator to inspect and validate exceptions raised by functions or methods\n- \ud83d\ude80 Quick Installation\n\nFor pip enthusiasts:\n\n```bash\npip install gaffe\n```\n\nFor poetry aficionados:\n\n```bash\npoetry add gaffe\n```\n\n# \ud83d\udca1 Getting Started\n\nTo employ Gaffe's custom error system, import the Error class and create custom errors by inheriting from it:\n\n```python\nfrom gaffe import Error\n\nclass NotFoundError(Exception):\n ...\n\nclass MyError(Error):\n not_found: NotFoundError\n invalid_input: ...\n authentication_error = \"authentication_error\"\n```\n \nWith this example, you'll get three custom errors under the MyError class, ready to be used just like any other Python exceptions.\n\n## \ud83c\udfa9 Raises Decorator\n\nHarness the power of the raises decorator to define and validate the types of exceptions a function or method can raise:\n\n```python\nfrom gaffe import raises\n\n@raises(TypeError, ValueError)\ndef my_function(x: int, y: int) -> float:\n if x <= 0 or y <= 0:\n raise ValueError(\"x and y must be positive\")\n return x / y\n```\n\nThe raises decorator ensures that my_function can only raise TypeError and ValueError. If it tries to raise an unlisted exception, an AssertionError will be raised with a suitable error message.\n\n## \ud83e\udd16 Mypy Integration\n\nTo keep mypy happy, use the gaffe.mypy:plugin in your config file, and ensure that error properties are annotated with `Exception` type instead of `...`\n\n```toml\n[tool.mypy]\nplugins = \"gaffe.mypy:plugin\"\n```\n\n\nReady to revolutionize your Python exception handling? Get started with Gaffe today and check out the test scenarios for more examples!\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple structured exceptions for python.",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://github.com/kodemore/gaffe",
"Homepage": "https://github.com/kodemore/gaffe",
"Repository": "https://github.com/kodemore/gaffe"
},
"split_keywords": [
"error",
"exception",
"structured",
"simple",
"gaffe"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "642559fb4e2b53f5755d8123e703500e2705865adb6713694fefd6014d7becb2",
"md5": "0f4bf7ea401f5ea9a43eda8b502ce53b",
"sha256": "fce5ad7cc5b2b6596775220db88ad54767cb32e5d589dfe1ca356ae7dc5c15e9"
},
"downloads": -1,
"filename": "gaffe-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0f4bf7ea401f5ea9a43eda8b502ce53b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 5838,
"upload_time": "2023-11-08T05:09:42",
"upload_time_iso_8601": "2023-11-08T05:09:42.141329Z",
"url": "https://files.pythonhosted.org/packages/64/25/59fb4e2b53f5755d8123e703500e2705865adb6713694fefd6014d7becb2/gaffe-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "df63f6903f5c1bd0472e1fa842ae89514cbd527cf8e11d8f60b5eff70c29637e",
"md5": "db951de26a38638c802ef975104f9467",
"sha256": "1c09015fc8ff0343e8c94e37cfc4d24b92dd6c2e0e7cba87bea210eeab68ee3f"
},
"downloads": -1,
"filename": "gaffe-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "db951de26a38638c802ef975104f9467",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 5110,
"upload_time": "2023-11-08T05:09:43",
"upload_time_iso_8601": "2023-11-08T05:09:43.688178Z",
"url": "https://files.pythonhosted.org/packages/df/63/f6903f5c1bd0472e1fa842ae89514cbd527cf8e11d8f60b5eff70c29637e/gaffe-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-08 05:09:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "kodemore",
"github_project": "gaffe",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "gaffe"
}
JSON
