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

{python_custom_exceptions-0.0.1 → 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/base_custom_exception.py

@@ -0,0 +1,46 @@
+import json
+from dataclasses import is_dataclass
+from json import dumps
+from typing import TypedDict
+
+from python_base_toolkit.utils.data_serialization import default_serialize
+
+
+class DiagnosticInfo(TypedDict): ...
+
+
+def serialize_data(obj: object) -> dict:
+    return json.loads(json.dumps(obj, default=default_serialize))
+
+
+def get_full_exception_message(content: dict) -> str:
+    return (
+        f'{content["message"]}\n\nCustom Exception Raised!\n'
+        f"{dumps(content, indent=4, sort_keys=False, default=str)}"
+    )
+
+
+class BaseCustomException(Exception):
+    def __init__(
+        self,
+        message_with_marking_dynamic_variables: str,
+        diagnostic_info: dict | DiagnosticInfo | None = None,
+    ) -> None:
+        if is_dataclass(diagnostic_info):
+            diagnostic_info = diagnostic_info.__dict__
+
+        self.exception_type = type(self).__name__
+        self.message = message_with_marking_dynamic_variables
+        self.diagnostic_info = diagnostic_info or {}
+
+    def __str__(self) -> str:
+        exception_content = {
+            "exception_type": self.exception_type,
+            "message": self.message,
+            "diagnostic_info": self.diagnostic_info,
+        }
+        # return get_full_exception_message(exception_content)
+        return dumps(exception_content, indent=4, sort_keys=False, default=str)
+
+    def __repr__(self) -> str:
+        return self.__str__()

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/connection_exceptions.py

@@ -0,0 +1,23 @@
+from python_custom_exceptions.base_custom_exception import BaseCustomException, DiagnosticInfo
+
+
+class ConnectionException(BaseCustomException):
+    def __init__(
+        self,
+        host: str | None,
+        message: str | None = None,
+        diagnostic_info: dict | DiagnosticInfo | None = None,
+    ) -> None:
+        message = (
+            (
+                f'Connection failed: Unable to establish a connection to the remote host ["{host}"]. '
+                f"Please check your credentials, network status, and host availability."
+            )
+            if not message
+            else message
+        )
+
+        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,
+        )

python_custom_exceptions-1.0.0/python_custom_exceptions.egg-info/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/python_custom_exceptions.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+MANIFEST.in
+README.md
+pyproject.toml
+python_custom_exceptions/__init__.py
+python_custom_exceptions/base_custom_exception.py
+python_custom_exceptions/comparison_exception.py
+python_custom_exceptions/connection_exceptions.py
+python_custom_exceptions/execution_exception.py
+python_custom_exceptions/is_exist_exception.py
+python_custom_exceptions/operation_exception.py
+python_custom_exceptions/os_exceptions.py
+python_custom_exceptions/unsupported_exception.py
+python_custom_exceptions/wrong_exception.py
+python_custom_exceptions.egg-info/PKG-INFO
+python_custom_exceptions.egg-info/SOURCES.txt
+python_custom_exceptions.egg-info/dependency_links.txt
+python_custom_exceptions.egg-info/requires.txt
+python_custom_exceptions.egg-info/top_level.txt
+tests/test_diagnostic_info.py
+tests/test_exception.py

python_custom_exceptions-1.0.0/python_custom_exceptions.egg-info/requires.txt

@@ -0,0 +1 @@
+python-base-toolkit>=1.1.3

python_custom_exceptions-1.0.0/python_custom_exceptions.egg-info/top_level.txt

@@ -0,0 +1 @@
+python_custom_exceptions

python_custom_exceptions-1.0.0/tests/test_diagnostic_info.py

@@ -0,0 +1,206 @@
+# test_diagnostic_info.py
+
+from dataclasses import dataclass
+
+import pytest
+from custom_python_logger import build_logger
+
+from python_custom_exceptions import (
+    BaseCustomException,
+    DiagnosticInfo,
+    UnsupportedExceptions,
+    WrongUsageException,
+)
+
+logger = build_logger(project_name="custom_exceptions_test")
+
+
+class DiagnosticInfoTest(DiagnosticInfo):
+    error_code: int
+    message: str
+    timestamp: str
+
+
+class DiagnosticInfoNested(DiagnosticInfo):
+    error: dict
+    context: dict
+
+
+def test_diagnostic_info_basic_usage():
+    """Test basic usage of DiagnosticInfo as a dictionary"""
+    diagnostic_info = DiagnosticInfoTest(error_code=404, message="Not found", timestamp="2023-10-01T12:00:00Z")
+
+    exception = BaseCustomException(
+        message_with_marking_dynamic_variables="Test message",
+        diagnostic_info=diagnostic_info,
+    )
+
+    assert exception.diagnostic_info == diagnostic_info
+    assert exception.diagnostic_info["error_code"] == 404
+    assert exception.diagnostic_info["message"] == "Not found"
+
+
+def test_diagnostic_info_empty_dict():
+    """Test DiagnosticInfo with empty dictionary"""
+    exception = BaseCustomException(message_with_marking_dynamic_variables="Test message", diagnostic_info={})
+
+    assert exception.diagnostic_info == {}
+
+
+def test_diagnostic_info_none():
+    """Test DiagnosticInfo with None value"""
+    exception = BaseCustomException(message_with_marking_dynamic_variables="Test message", diagnostic_info=None)
+
+    assert exception.diagnostic_info == {}
+
+
+def test_diagnostic_info_nested_structure():
+    """Test DiagnosticInfo with nested dictionary structure"""
+    diagnostic_info = DiagnosticInfoNested(
+        error={
+            "code": 500,
+            "type": "Internal Server Error",
+            "details": {"component": "database", "operation": "query"},
+        },
+        context={"user_id": 12345, "session_id": "abc123"},
+    )
+
+    exception = BaseCustomException(
+        message_with_marking_dynamic_variables="Complex error",
+        diagnostic_info=diagnostic_info,
+    )
+
+    assert exception.diagnostic_info["error"]["code"] == 500
+    assert exception.diagnostic_info["context"]["user_id"] == 12345
+
+
+def test_diagnostic_info_with_dataclass():
+    """Test DiagnosticInfo with dataclass object"""
+
+    @dataclass
+    class ErrorDetails:
+        code: int
+        message: str
+        component: str
+
+    error_details = ErrorDetails(code=400, message="Bad Request", component="api")
+
+    exception = BaseCustomException(
+        message_with_marking_dynamic_variables="Dataclass test",
+        diagnostic_info=error_details.__dict__,
+    )
+
+    # The dataclass should be converted to dict
+    assert exception.diagnostic_info == {
+        "code": 400,
+        "message": "Bad Request",
+        "component": "api",
+    }
+
+
+def test_diagnostic_info_with_mixed_types():
+    """Test DiagnosticInfo with various data types"""
+    diagnostic_info = {
+        "string": "test",
+        "integer": 42,
+        "float": 3.14,
+        "boolean": True,
+        "list": [1, 2, 3],
+        "tuple": (1, 2, 3),
+        "set": {1, 2, 3},
+        "none": None,
+    }
+
+    exception = BaseCustomException(
+        message_with_marking_dynamic_variables="Mixed types test",
+        diagnostic_info=diagnostic_info,
+    )
+
+    assert exception.diagnostic_info["string"] == "test"
+    assert exception.diagnostic_info["integer"] == 42
+    assert exception.diagnostic_info["float"] == 3.14
+    assert exception.diagnostic_info["boolean"] is True
+    assert exception.diagnostic_info["list"] == [1, 2, 3]
+    assert exception.diagnostic_info["tuple"] == (1, 2, 3)
+    assert exception.diagnostic_info["set"] == {1, 2, 3}
+    assert exception.diagnostic_info["none"] is None
+
+
+def test_diagnostic_info_serialization_in_str():
+    """Test that DiagnosticInfo is properly serialized in exception string representation"""
+    diagnostic_info = {"error_code": 500, "component": "database"}
+
+    exception = BaseCustomException(
+        message_with_marking_dynamic_variables="Serialization test",
+        diagnostic_info=diagnostic_info,
+    )
+
+    str_repr = str(exception)
+    assert "error_code" in str_repr
+    assert "500" in str_repr
+    assert "component" in str_repr
+    assert "database" in str_repr
+
+
+def test_diagnostic_info_in_existing_exceptions():
+    """Test DiagnosticInfo usage in existing exception classes"""
+    # Test with UnsupportedExceptions
+    with pytest.raises(UnsupportedExceptions) as exc_info:
+        raise UnsupportedExceptions(
+            unsupported_subject="FeatureX",
+            diagnostic_info={"feature_id": "X123", "version": "2.0"},
+        )
+
+    assert exc_info.value.diagnostic_info["feature_id"] == "X123"
+    assert exc_info.value.diagnostic_info["version"] == "2.0"
+
+    # Test with WrongUsageException
+    with pytest.raises(WrongUsageException) as exc_info:
+        raise WrongUsageException(
+            message="Invalid parameter",
+            diagnostic_info={"param_name": "user_id", "expected_type": "int"},
+        )
+
+    assert exc_info.value.diagnostic_info["param_name"] == "user_id"
+    assert exc_info.value.diagnostic_info["expected_type"] == "int"
+
+
+def test_diagnostic_info_type_annotation():
+    """Test that DiagnosticInfo can be properly typed"""
+
+    def create_diagnostic_info() -> dict:
+        return {"timestamp": "2023-01-01T00:00:00Z", "request_id": "req-123"}
+
+    diagnostic_info = create_diagnostic_info()
+    exception = BaseCustomException(
+        message_with_marking_dynamic_variables="Type annotation test",
+        diagnostic_info=diagnostic_info,
+    )
+
+    assert exception.diagnostic_info["timestamp"] == "2023-01-01T00:00:00Z"
+    assert exception.diagnostic_info["request_id"] == "req-123"
+
+
+def test_diagnostic_info_edge_cases():
+    """Test DiagnosticInfo with edge cases"""
+    # Empty string keys
+    diagnostic_info = {"": "empty key", "normal_key": "normal value"}
+
+    exception = BaseCustomException(
+        message_with_marking_dynamic_variables="Edge case test",
+        diagnostic_info=diagnostic_info,
+    )
+
+    assert exception.diagnostic_info[""] == "empty key"
+    assert exception.diagnostic_info["normal_key"] == "normal value"
+
+    # Very long values
+    long_string = "x" * 1000
+    diagnostic_info_long = {"long_value": long_string}
+
+    exception_long = BaseCustomException(
+        message_with_marking_dynamic_variables="Long value test",
+        diagnostic_info=diagnostic_info_long,
+    )
+
+    assert exception_long.diagnostic_info["long_value"] == long_string

python_custom_exceptions-1.0.0/tests/test_exception.py

@@ -0,0 +1,103 @@
+import pytest
+from custom_python_logger import build_logger
+
+from python_custom_exceptions import (
+    ComparisonException,
+    ConnectionException,
+    IsExistAfterOperationException,
+    IsNotExistAfterOperationException,
+    NotOperationalException,
+    OperationException,
+    TimedExecutionException,
+    UnexpectedlySucceededOperationException,
+    UnsupportedExceptions,
+    UnsupportedOSExceptions,
+    WrongUsageException,
+)
+
+logger = build_logger(project_name="custom_exceptions_test")
+
+
+def test_unsupported_exceptions():
+    with pytest.raises(UnsupportedExceptions) as exc_info:
+        raise UnsupportedExceptions(unsupported_subject="FeatureX", diagnostic_info={"code": 123})
+    logger.info(f"\n{exc_info.value}")  # noqa
+
+
+def test_wrong_usage_exception():
+    with pytest.raises(WrongUsageException) as exc_info:
+        raise WrongUsageException(message="bad call", diagnostic_info={"hint": "use method X"})
+    logger.info(f"\n{exc_info.value}")  # noqa
+
+
+def test_comparison_exception():
+    with pytest.raises(ComparisonException) as exc_info:
+        raise ComparisonException(
+            subject="value",
+            expected_value=42,
+            actual_value=43,
+            diagnostic_info={"context": "comparison test"},
+        )
+    logger.info(f"\n{exc_info.value}")  # noqa
+
+
+def test_timed_execution_exception():
+    with pytest.raises(TimedExecutionException) as exc_info:
+        raise TimedExecutionException(operation="fetch_data", timeout=30, diagnostic_info={"timeout_code": "T30"})
+    logger.info(f"\n{exc_info.value}")  # noqa
+
+
+def test_operation_exception():
+    with pytest.raises(OperationException) as exc_info:
+        raise OperationException(operation="save file", diagnostic_info={"reason": "disk full"})
+    logger.info(f"\n{exc_info.value}")  # noqa
+
+
+def test_not_operational_exception():
+    with pytest.raises(NotOperationalException) as exc_info:
+        raise NotOperationalException(subject="ServiceX", diagnostic_info={"uptime": "0s"})
+    logger.info(f"\n{exc_info.value}")  # noqa
+
+
+def test_exist_after_operation_exception():
+    with pytest.raises(IsExistAfterOperationException) as exc_info:
+        raise IsExistAfterOperationException(subject="file.txt", operation="delete", diagnostic_info={"path": "/tmp"})
+    logger.info(f"\n{exc_info.value}")  # noqa
+
+
+def test_not_exist_after_operation_exception():
+    with pytest.raises(IsNotExistAfterOperationException) as exc_info:
+        raise IsNotExistAfterOperationException(
+            subject="folder",
+            operation="create",
+            diagnostic_info={"path": "/tmp/folder"},
+        )
+    logger.info(f"\n{exc_info.value}")  # noqa
+
+
+def test_unexpectedly_succeeded_operation_exception():
+    with pytest.raises(UnexpectedlySucceededOperationException) as exc_info:
+        raise UnexpectedlySucceededOperationException(operation="fail_test", diagnostic_info={"status": "success"})
+    logger.info(f"\n{exc_info.value}")  # noqa
+
+
+def test_unsupported_os_exceptions():
+    with pytest.raises(UnsupportedOSExceptions) as exc_info:
+        raise UnsupportedOSExceptions(os_name="Solaris", diagnostic_info={"os_version": "11.4"})
+    logger.info(f"\n{exc_info.value}")  # noqa
+
+
+def test_connection_exception():
+    with pytest.raises(ConnectionException) as exc_info:
+        raise ConnectionException(
+            host="Database",
+            message="Connection failed",
+            diagnostic_info={"host": "db.example.com"},
+        )
+    logger.info(f"\n{exc_info.value}")  # noqa
+
+
+def test_connection_exception_without_message():
+    with pytest.raises(ConnectionException) as exc_info:
+        raise ConnectionException(host="Database", diagnostic_info={"host": "db.example.com"})
+    logger.info(f"\n{exc_info.value}")  # noqa

python_custom_exceptions-0.0.1/PKG-INFO

@@ -1,43 +0,0 @@
-Metadata-Version: 2.4
-Name: python-custom-exceptions
-Version: 0.0.1
-Summary: A collection of custom exceptions for Python projects.
-Home-page: https://github.com/aviz92/python-custom-exceptions
-Author: Avi Zaguri
-Author-email: 
-Project-URL: Repository, https://github.com/aviz92/python-custom-exceptions
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: setuptools
-Requires-Dist: wheel
-Requires-Dist: colorlog
-Requires-Dist: pytest
-Requires-Dist: pathlib
-Requires-Dist: custom-python-logger
-Dynamic: author
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: project-url
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
-# Python Custom Exceptions
-
----
-
-## 🤝 Contributing
-If you have a helpful tool, pattern, or improvement to suggest:
-Fork the repo <br>
-Create a new branch <br>
-Submit a pull request <br>
-I welcome additions that promote clean, productive, and maintainable development. <br>
-
----
-
-## 🙏 Thanks
-Thanks for exploring this repository! <br>
-Happy coding! <br>

python_custom_exceptions-0.0.1/README.md

@@ -1,16 +0,0 @@
-# Python Custom Exceptions
-
----
-
-## 🤝 Contributing
-If you have a helpful tool, pattern, or improvement to suggest:
-Fork the repo <br>
-Create a new branch <br>
-Submit a pull request <br>
-I welcome additions that promote clean, productive, and maintainable development. <br>
-
----
-
-## 🙏 Thanks
-Thanks for exploring this repository! <br>
-Happy coding! <br>

python_custom_exceptions-0.0.1/pyproject.toml

@@ -1,3 +0,0 @@
-[build-system]
-requires = ["setuptools", "wheel"]
-build-backend = "setuptools.build_meta"

python_custom_exceptions-0.0.1/python_custom_exceptions.egg-info/PKG-INFO

@@ -1,43 +0,0 @@
-Metadata-Version: 2.4
-Name: python-custom-exceptions
-Version: 0.0.1
-Summary: A collection of custom exceptions for Python projects.
-Home-page: https://github.com/aviz92/python-custom-exceptions
-Author: Avi Zaguri
-Author-email: 
-Project-URL: Repository, https://github.com/aviz92/python-custom-exceptions
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: setuptools
-Requires-Dist: wheel
-Requires-Dist: colorlog
-Requires-Dist: pytest
-Requires-Dist: pathlib
-Requires-Dist: custom-python-logger
-Dynamic: author
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: project-url
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
-
-# Python Custom Exceptions
-
----
-
-## 🤝 Contributing
-If you have a helpful tool, pattern, or improvement to suggest:
-Fork the repo <br>
-Create a new branch <br>
-Submit a pull request <br>
-I welcome additions that promote clean, productive, and maintainable development. <br>
-
----
-
-## 🙏 Thanks
-Thanks for exploring this repository! <br>
-Happy coding! <br>

python_custom_exceptions-0.0.1/python_custom_exceptions.egg-info/SOURCES.txt

@@ -1,11 +0,0 @@
-LICENSE
-MANIFEST.in
-README.md
-pyproject.toml
-requirements.txt
-setup.py
-python_custom_exceptions.egg-info/PKG-INFO
-python_custom_exceptions.egg-info/SOURCES.txt
-python_custom_exceptions.egg-info/dependency_links.txt
-python_custom_exceptions.egg-info/requires.txt
-python_custom_exceptions.egg-info/top_level.txt

python_custom_exceptions-0.0.1/python_custom_exceptions.egg-info/requires.txt

@@ -1,6 +0,0 @@
-setuptools
-wheel
-colorlog
-pytest
-pathlib
-custom-python-logger

python_custom_exceptions-0.0.1/python_custom_exceptions.egg-info/top_level.txt

@@ -1 +0,0 @@
-

python_custom_exceptions-0.0.1/requirements.txt

@@ -1,7 +0,0 @@
-setuptools
-wheel
-colorlog
-pytest
-pathlib
-
-custom-python-logger

python_custom_exceptions-0.0.1/setup.py

@@ -1,37 +0,0 @@
-from setuptools import setup, find_packages
-
-package_version = '0.0.1'
-
-package_name = 'python-custom-exceptions'
-package_description = 'A collection of custom exceptions for Python projects.'
-
-package_name_ = package_name.replace('-', '_')
-package_long_description_content_type = 'text/markdown'
-package_url = f'https://github.com/aviz92/{package_name}'
-package_python_requires = '>=3.11'
-package_author = 'Avi Zaguri'
-
-with open('requirements.txt', 'r') as file:
-    package_install_requires = [
-        line.strip() for line in file.readlines() if line.strip() and not line.startswith('#')
-    ]
-
-with open('README.md', 'r') as file:
-    package_long_description = file.read()
-
-setup(
-    name=package_name,
-    version=package_version,
-    packages=find_packages(include=[package_name_, f'{package_name_}.*']),
-    install_requires=package_install_requires,
-    author=package_author,
-    author_email='',
-    description=package_description,
-    long_description=package_long_description,
-    long_description_content_type=package_long_description_content_type,
-    url=package_url,
-    project_urls={
-        'Repository': package_url,
-    },
-    python_requires=package_python_requires,
-)