python-custom-exceptions 0.0.2__tar.gz → 1.0.0__tar.gz

{python_custom_exceptions-0.0.2 → python_custom_exceptions-1.0.0}/MANIFEST.in

@@ -1,3 +1,3 @@
-include requirements.txt
+include pyproject.toml
 include README.md
 include LICENSE

python_custom_exceptions-1.0.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: python-custom-exceptions
+Version: 1.0.0
+Summary: A collection of custom exceptions for Python projects.
+Author: Avi Zaguri
+License: MIT
+Project-URL: Homepage, https://github.com/aviz92/python-custom-exceptions
+Project-URL: Repository, https://github.com/aviz92/python-custom-exceptions
+Project-URL: Issues, https://github.com/aviz92/python-custom-exceptions/issues
+Keywords: development,python,exceptions,error-handling
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-base-toolkit>=1.1.3
+Dynamic: license-file
+
+# Python Custom Exceptions
+A collection of structured, ready-to-use exception classes for Python projects. <br>
+Every exception renders as JSON with its type, a human-readable message, and optional diagnostic info,
+so errors are easy to read in logs and easy to parse by tools. <br>
+
+---
+
+### Features
+- ✅ Specific Exception Classes: Ready-made exceptions for common error scenarios.
+- ✅ Structured Output: `str(exception)` is a JSON document with type, message and diagnostic info.
+- ✅ Diagnostic Info: Attach typed context (`TypedDict`, `dict` or dataclass) to any exception.
+- ✅ Single Base Class: Everything inherits from `BaseCustomException`, so one `except` catches them all.
+- ✅ Easy Extension: Subclass `BaseCustomException` to add your own exceptions.
+
+---
+
+### Installation
+```bash
+uv add python-custom-exceptions
+```
+or with pip:
+```bash
+pip install python-custom-exceptions
+```
+Requires Python 3.12+.
+
+---
+
+### Available Exceptions
+| Exception | Arguments | Message |
+|-----------|-----------|---------|
+| `BaseCustomException` | `message_with_marking_dynamic_variables` | `<message>` |
+| `ComparisonException` | `expected_value`, `actual_value`, `subject=None` | `Expected <subject> to be [<expected>], but got [<actual>]` |
+| `ConnectionException` | `host`, `message=None` | `Connection failed: Unable to establish a connection to the remote host ["<host>"]. ...` |
+| `IsExistException` | `subject` | `[<subject>] is exists` |
+| `IsNotExistException` | `subject` | `[<subject>] is not exists` |
+| `IsExistAfterOperationException` | `subject`, `operation` | `<subject> exists after trying to <operation>` |
+| `IsNotExistAfterOperationException` | `subject`, `operation` | `<subject> does not exist after trying to <operation>` |
+| `OperationException` | `operation` | `Operation <operation> failed` |
+| `NotOperationalException` | `subject` | `<subject> is not Operational` |
+| `UnexpectedlySucceededOperationException` | `operation` | `Operation <operation> unexpectedly succeeded` |
+| `TimedExecutionException` | `operation`, `timeout` | `Operation <operation> did not succeed within [<timeout>] seconds` |
+| `UnsupportedExceptions` | `unsupported_subject` | `<unsupported_subject> is unsupported` |
+| `UnsupportedOSExceptions` | `os_name` | `Unsupported OS: ["<os_name>"]` |
+| `WrongUsageException` | `message` | `Wrong usage: <message>` |
+
+All exceptions also accept an optional `diagnostic_info` argument.
+
+---
+
+### Usage Examples
+
+#### Raise an exception with diagnostic info
+```python
+from pathlib import Path
+
+from python_custom_exceptions import DiagnosticInfo, IsNotExistException
+
+
+class PathDiagnosticInfo(DiagnosticInfo):
+    path: str
+
+
+path = Path("/tmp/missing")
+if not path.exists():
+    raise IsNotExistException(
+        subject="Directory",
+        diagnostic_info=PathDiagnosticInfo(path=str(path)),
+    )
+```
+Output:
+```json
+{
+    "exception_type": "IsNotExistException",
+    "message": "[Directory] is not exists",
+    "diagnostic_info": {
+        "path": "/tmp/missing"
+    }
+}
+```
+
+#### Catch any custom exception
+```python
+from python_custom_exceptions import BaseCustomException, ComparisonException
+
+try:
+    raise ComparisonException(expected_value=200, actual_value=500, subject="status code")
+except BaseCustomException as exc:
+    print(exc.exception_type)   # ComparisonException
+    print(exc.message)          # Expected status code to be [200], but got [500]
+    print(exc.diagnostic_info)  # {}
+```
+
+#### Define your own exception
+```python
+from python_custom_exceptions import BaseCustomException, DiagnosticInfo
+
+
+class QuotaExceededException(BaseCustomException):
+    def __init__(self, resource: str, limit: int, diagnostic_info: dict | DiagnosticInfo | None = None) -> None:
+        super().__init__(
+            message_with_marking_dynamic_variables=f"Quota for [{resource}] exceeded the limit of [{limit}]",
+            diagnostic_info=diagnostic_info,
+        )
+```
+
+---
+
+### Development
+```bash
+git clone https://github.com/aviz92/python-custom-exceptions.git
+cd python-custom-exceptions
+uv sync                    # create .venv and install runtime + dev dependencies
+uv run pre-commit install  # enable git hooks
+uv run pytest              # run the tests
+uv build                   # build sdist + wheel into dist/
+```
+
+---
+
+### 🤝 Contributing
+If you have a helpful exception, pattern, or improvement to suggest:
+1. Fork the repo
+2. Create a new branch
+3. Submit a pull request
+
+I welcome additions that promote clean, productive, and maintainable development. <br>
+
+---
+
+### 🙏 Thanks
+Thanks for exploring this repository! <br>
+Happy coding! <br>

python_custom_exceptions-1.0.0/README.md

@@ -0,0 +1,133 @@
+# Python Custom Exceptions
+A collection of structured, ready-to-use exception classes for Python projects. <br>
+Every exception renders as JSON with its type, a human-readable message, and optional diagnostic info,
+so errors are easy to read in logs and easy to parse by tools. <br>
+
+---
+
+### Features
+- ✅ Specific Exception Classes: Ready-made exceptions for common error scenarios.
+- ✅ Structured Output: `str(exception)` is a JSON document with type, message and diagnostic info.
+- ✅ Diagnostic Info: Attach typed context (`TypedDict`, `dict` or dataclass) to any exception.
+- ✅ Single Base Class: Everything inherits from `BaseCustomException`, so one `except` catches them all.
+- ✅ Easy Extension: Subclass `BaseCustomException` to add your own exceptions.
+
+---
+
+### Installation
+```bash
+uv add python-custom-exceptions
+```
+or with pip:
+```bash
+pip install python-custom-exceptions
+```
+Requires Python 3.12+.
+
+---
+
+### Available Exceptions
+| Exception | Arguments | Message |
+|-----------|-----------|---------|
+| `BaseCustomException` | `message_with_marking_dynamic_variables` | `<message>` |
+| `ComparisonException` | `expected_value`, `actual_value`, `subject=None` | `Expected <subject> to be [<expected>], but got [<actual>]` |
+| `ConnectionException` | `host`, `message=None` | `Connection failed: Unable to establish a connection to the remote host ["<host>"]. ...` |
+| `IsExistException` | `subject` | `[<subject>] is exists` |
+| `IsNotExistException` | `subject` | `[<subject>] is not exists` |
+| `IsExistAfterOperationException` | `subject`, `operation` | `<subject> exists after trying to <operation>` |
+| `IsNotExistAfterOperationException` | `subject`, `operation` | `<subject> does not exist after trying to <operation>` |
+| `OperationException` | `operation` | `Operation <operation> failed` |
+| `NotOperationalException` | `subject` | `<subject> is not Operational` |
+| `UnexpectedlySucceededOperationException` | `operation` | `Operation <operation> unexpectedly succeeded` |
+| `TimedExecutionException` | `operation`, `timeout` | `Operation <operation> did not succeed within [<timeout>] seconds` |
+| `UnsupportedExceptions` | `unsupported_subject` | `<unsupported_subject> is unsupported` |
+| `UnsupportedOSExceptions` | `os_name` | `Unsupported OS: ["<os_name>"]` |
+| `WrongUsageException` | `message` | `Wrong usage: <message>` |
+
+All exceptions also accept an optional `diagnostic_info` argument.
+
+---
+
+### Usage Examples
+
+#### Raise an exception with diagnostic info
+```python
+from pathlib import Path
+
+from python_custom_exceptions import DiagnosticInfo, IsNotExistException
+
+
+class PathDiagnosticInfo(DiagnosticInfo):
+    path: str
+
+
+path = Path("/tmp/missing")
+if not path.exists():
+    raise IsNotExistException(
+        subject="Directory",
+        diagnostic_info=PathDiagnosticInfo(path=str(path)),
+    )
+```
+Output:
+```json
+{
+    "exception_type": "IsNotExistException",
+    "message": "[Directory] is not exists",
+    "diagnostic_info": {
+        "path": "/tmp/missing"
+    }
+}
+```
+
+#### Catch any custom exception
+```python
+from python_custom_exceptions import BaseCustomException, ComparisonException
+
+try:
+    raise ComparisonException(expected_value=200, actual_value=500, subject="status code")
+except BaseCustomException as exc:
+    print(exc.exception_type)   # ComparisonException
+    print(exc.message)          # Expected status code to be [200], but got [500]
+    print(exc.diagnostic_info)  # {}
+```
+
+#### Define your own exception
+```python
+from python_custom_exceptions import BaseCustomException, DiagnosticInfo
+
+
+class QuotaExceededException(BaseCustomException):
+    def __init__(self, resource: str, limit: int, diagnostic_info: dict | DiagnosticInfo | None = None) -> None:
+        super().__init__(
+            message_with_marking_dynamic_variables=f"Quota for [{resource}] exceeded the limit of [{limit}]",
+            diagnostic_info=diagnostic_info,
+        )
+```
+
+---
+
+### Development
+```bash
+git clone https://github.com/aviz92/python-custom-exceptions.git
+cd python-custom-exceptions
+uv sync                    # create .venv and install runtime + dev dependencies
+uv run pre-commit install  # enable git hooks
+uv run pytest              # run the tests
+uv build                   # build sdist + wheel into dist/
+```
+
+---
+
+### 🤝 Contributing
+If you have a helpful exception, pattern, or improvement to suggest:
+1. Fork the repo
+2. Create a new branch
+3. Submit a pull request
+
+I welcome additions that promote clean, productive, and maintainable development. <br>
+
+---
+
+### 🙏 Thanks
+Thanks for exploring this repository! <br>
+Happy coding! <br>

python_custom_exceptions-1.0.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "python-custom-exceptions"
+version = "1.0.0"
+description = "A collection of custom exceptions for Python projects."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Avi Zaguri" },]
+keywords = ["development", "python", "exceptions", "error-handling"]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+dependencies = [
+    "python-base-toolkit>=1.1.3",
+]
+
+[dependency-groups]
+dev = [
+    "pytest-better-report>=1.0.2",
+    "custom-python-logger>=4.1.0",
+    "pre-commit>=4.7.0",
+    "pytest>=9.2.0",
+    "python-dotenv>=1.2.4",
+    "setuptools>=84.2.1",
+    "wheel>=0.48.0",
+    "python-base-command>=0.1.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/aviz92/python-custom-exceptions"
+Repository = "https://github.com/aviz92/python-custom-exceptions"
+Issues = "https://github.com/aviz92/python-custom-exceptions/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["python_custom_exceptions*"]
+namespaces = false

python_custom_exceptions-1.0.0/python_custom_exceptions/__init__.py

@@ -0,0 +1,37 @@
+from python_custom_exceptions.base_custom_exception import BaseCustomException, DiagnosticInfo, serialize_data
+from python_custom_exceptions.comparison_exception import ComparisonException
+from python_custom_exceptions.connection_exceptions import ConnectionException
+from python_custom_exceptions.execution_exception import TimedExecutionException
+from python_custom_exceptions.is_exist_exception import (
+    IsExistAfterOperationException,
+    IsExistException,
+    IsNotExistAfterOperationException,
+    IsNotExistException,
+)
+from python_custom_exceptions.operation_exception import (
+    NotOperationalException,
+    OperationException,
+    UnexpectedlySucceededOperationException,
+)
+from python_custom_exceptions.os_exceptions import UnsupportedOSExceptions
+from python_custom_exceptions.unsupported_exception import UnsupportedExceptions
+from python_custom_exceptions.wrong_exception import WrongUsageException
+
+__all__ = [
+    "BaseCustomException",
+    "DiagnosticInfo",
+    "serialize_data",
+    "ConnectionException",
+    "ComparisonException",
+    "IsExistAfterOperationException",
+    "IsExistException",
+    "IsNotExistException",
+    "IsNotExistAfterOperationException",
+    "NotOperationalException",
+    "OperationException",
+    "TimedExecutionException",
+    "UnexpectedlySucceededOperationException",
+    "UnsupportedExceptions",
+    "WrongUsageException",
+    "UnsupportedOSExceptions",
+]

python_custom_exceptions-1.0.0/python_custom_exceptions/comparison_exception.py

@@ -0,0 +1,20 @@
+from python_custom_exceptions.base_custom_exception import BaseCustomException, DiagnosticInfo
+
+
+class ComparisonException(BaseCustomException):
+    def __init__(
+        self,
+        expected_value: int,
+        actual_value: int,
+        subject: str | None = None,
+        diagnostic_info: dict | DiagnosticInfo | None = None,
+    ) -> None:
+        message = (
+            f"Expected {subject} to be [{expected_value}], but got [{actual_value}]"
+            if subject
+            else f"Expected [{expected_value}], but got [{actual_value}]"
+        )
+        super().__init__(
+            message_with_marking_dynamic_variables=message,
+            diagnostic_info=diagnostic_info,
+        )

python_custom_exceptions-1.0.0/python_custom_exceptions/execution_exception.py

@@ -0,0 +1,15 @@
+from python_custom_exceptions.base_custom_exception import BaseCustomException, DiagnosticInfo
+
+
+class TimedExecutionException(BaseCustomException):
+    def __init__(
+        self,
+        operation: str,
+        timeout: str | int,
+        diagnostic_info: dict | DiagnosticInfo | None = None,
+    ) -> None:
+        message = f"Operation {operation} did not succeed within [{timeout}] seconds"
+        super().__init__(
+            message_with_marking_dynamic_variables=message,
+            diagnostic_info=diagnostic_info,
+        )

python_custom_exceptions-1.0.0/python_custom_exceptions/is_exist_exception.py

@@ -0,0 +1,55 @@
+from python_custom_exceptions.base_custom_exception import BaseCustomException, DiagnosticInfo
+
+
+class IsExistException(BaseCustomException):
+    def __init__(
+        self,
+        subject: str,
+        diagnostic_info: dict | DiagnosticInfo | None = None,
+    ) -> None:
+        message = f"[{subject}] is exists"
+        super().__init__(
+            message_with_marking_dynamic_variables=message,
+            diagnostic_info=diagnostic_info,
+        )
+
+
+class IsNotExistException(BaseCustomException):
+    def __init__(
+        self,
+        subject: str,
+        diagnostic_info: dict | DiagnosticInfo | None = None,
+    ) -> None:
+        message = f"[{subject}] is not exists"
+        super().__init__(
+            message_with_marking_dynamic_variables=message,
+            diagnostic_info=diagnostic_info,
+        )
+
+
+class IsExistAfterOperationException(BaseCustomException):
+    def __init__(
+        self,
+        subject: str,
+        operation: str,
+        diagnostic_info: dict | DiagnosticInfo | None = None,
+    ) -> None:
+        message = f"{subject} exists after trying to {operation}"
+        super().__init__(
+            message_with_marking_dynamic_variables=message,
+            diagnostic_info=diagnostic_info,
+        )
+
+
+class IsNotExistAfterOperationException(BaseCustomException):
+    def __init__(
+        self,
+        subject: str,
+        operation: str,
+        diagnostic_info: dict | DiagnosticInfo | None = None,
+    ) -> None:
+        message = f"{subject} does not exist after trying to {operation}"
+        super().__init__(
+            message_with_marking_dynamic_variables=message,
+            diagnostic_info=diagnostic_info,
+        )

python_custom_exceptions-1.0.0/python_custom_exceptions/operation_exception.py

@@ -0,0 +1,40 @@
+from python_custom_exceptions.base_custom_exception import BaseCustomException, DiagnosticInfo
+
+
+class OperationException(BaseCustomException):
+    def __init__(
+        self,
+        operation: str,
+        diagnostic_info: dict | DiagnosticInfo | None = None,
+    ) -> None:
+        message = f"Operation {operation} failed"
+        super().__init__(
+            message_with_marking_dynamic_variables=message,
+            diagnostic_info=diagnostic_info,
+        )
+
+
+class NotOperationalException(BaseCustomException):
+    def __init__(
+        self,
+        subject: str,
+        diagnostic_info: dict | DiagnosticInfo | None = None,
+    ) -> None:
+        message = f"{subject} is not Operational"
+        super().__init__(
+            message_with_marking_dynamic_variables=message,
+            diagnostic_info=diagnostic_info,
+        )
+
+
+class UnexpectedlySucceededOperationException(BaseCustomException):
+    def __init__(
+        self,
+        operation: str,
+        diagnostic_info: dict | DiagnosticInfo | None = None,
+    ) -> None:
+        message = f"Operation {operation} unexpectedly succeeded"
+        super().__init__(
+            message_with_marking_dynamic_variables=message,
+            diagnostic_info=diagnostic_info,
+        )

python_custom_exceptions-1.0.0/python_custom_exceptions/os_exceptions.py

@@ -0,0 +1,14 @@
+from python_custom_exceptions.base_custom_exception import BaseCustomException, DiagnosticInfo
+
+
+class UnsupportedOSExceptions(BaseCustomException):
+    def __init__(
+        self,
+        os_name: str,
+        diagnostic_info: dict | DiagnosticInfo | None = None,
+    ) -> None:
+        message = f'Unsupported OS: ["{os_name}"]'
+        super().__init__(
+            message_with_marking_dynamic_variables=message,
+            diagnostic_info=diagnostic_info,
+        )

python_custom_exceptions-1.0.0/python_custom_exceptions/unsupported_exception.py

@@ -0,0 +1,14 @@
+from python_custom_exceptions.base_custom_exception import BaseCustomException, DiagnosticInfo
+
+
+class UnsupportedExceptions(BaseCustomException):
+    def __init__(
+        self,
+        unsupported_subject: str,
+        diagnostic_info: dict | DiagnosticInfo | None = None,
+    ) -> None:
+        message = f"{unsupported_subject} is unsupported"
+        super().__init__(
+            message_with_marking_dynamic_variables=message,
+            diagnostic_info=diagnostic_info,
+        )

python_custom_exceptions-1.0.0/python_custom_exceptions/wrong_exception.py

@@ -0,0 +1,14 @@
+from python_custom_exceptions.base_custom_exception import BaseCustomException, DiagnosticInfo
+
+
+class WrongUsageException(BaseCustomException):
+    def __init__(
+        self,
+        message: str,
+        diagnostic_info: dict | DiagnosticInfo | None = None,
+    ) -> None:
+        message = f"Wrong usage: {message}"
+        super().__init__(
+            message_with_marking_dynamic_variables=message,
+            diagnostic_info=diagnostic_info,
+        )