python-custom-exceptions 0.0.1__py3-none-any.whl → 1.0.0__py3-none-any.whl

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/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/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/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/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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+python_custom_exceptions/__init__.py,sha256=JX-P0mYY-z16Aqe3ELepizFbkPIfFebLdgo8WDwmMkc,1411
+python_custom_exceptions/base_custom_exception.py,sha256=9fMv4EqSujbu6SyF9-UEevqN2FWvf4pBu2xqU2m3g1I,1412
+python_custom_exceptions/comparison_exception.py,sha256=0dRXDfFVlSflrKEAyDJCj3gmbsC5mpf-YPdjXD_RhzE,699
+python_custom_exceptions/connection_exceptions.py,sha256=AjOX7_P4bKi7Nm61mk0I7mP5A_YhQ3H55I3iiJ6BxVg,760
+python_custom_exceptions/execution_exception.py,sha256=KkSbvHvNvB-qqbEXoj_QHfCxa5bR7_G11eHUK6RlVGA,537
+python_custom_exceptions/is_exist_exception.py,sha256=38b9HxHcrXytdlN8J8lf6gVSID936UITVgl_1lXKJ8s,1683
+python_custom_exceptions/operation_exception.py,sha256=AxrCnpEuUMTGdPkl41bStZjxgU1TOdoXgDV246NiRTE,1254
+python_custom_exceptions/os_exceptions.py,sha256=826rmNcSdeJv7ZbdVNdyL8IqHQwFNTJn83l7nraWkXM,472
+python_custom_exceptions/unsupported_exception.py,sha256=f44xg_1MKS2_5tq7ahtWygj3yj_tiFdfarN-FR9q9gk,489
+python_custom_exceptions/wrong_exception.py,sha256=9BMp5bIo-NDp-unChsRpSusv-PC0CEn-cZxwVjoWoJ4,461
+python_custom_exceptions-1.0.0.dist-info/licenses/LICENSE,sha256=cSikHY6SZFsPZSBizCDAJ0-Bjjzxt-JtX6TVbKxwimo,1067
+python_custom_exceptions-1.0.0.dist-info/METADATA,sha256=ZQlzEY5ZA6LorGcUvfHNQZv8DJrYpbotP4Kzn6Gr9JI,5484
+python_custom_exceptions-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+python_custom_exceptions-1.0.0.dist-info/top_level.txt,sha256=_dIQhOUJyiSda1cdPIziqTOHW4_ge023lo3kpj7j3kE,25
+python_custom_exceptions-1.0.0.dist-info/RECORD,,

{python_custom_exceptions-0.0.1.dist-info → python_custom_exceptions-1.0.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

python_custom_exceptions-1.0.0.dist-info/top_level.txt

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

python_custom_exceptions-0.0.1.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -1,5 +0,0 @@
-python_custom_exceptions-0.0.1.dist-info/licenses/LICENSE,sha256=cSikHY6SZFsPZSBizCDAJ0-Bjjzxt-JtX6TVbKxwimo,1067
-python_custom_exceptions-0.0.1.dist-info/METADATA,sha256=NXazVqks713rw1YlO_Mb2-mh99fN0gdaJEuR4rabY6o,1100
-python_custom_exceptions-0.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-python_custom_exceptions-0.0.1.dist-info/top_level.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
-python_custom_exceptions-0.0.1.dist-info/RECORD,,

python_custom_exceptions-0.0.1.dist-info/top_level.txt

@@ -1 +0,0 @@
-