various-api-tools 1.0.0__tar.gz → 2.0.1__tar.gz

{various_api_tools-1.0.0 → various_api_tools-2.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: various-api-tools
-Version: 1.0.0
+Version: 2.0.1
 Summary: A lightweight utility package for common API-related tasks in Python, including JSON and Pydantic error translators that provide user-friendly Russian messages.
 Author-Email: dkurchigin <kurchigin.dmitry@yandex.ru>
 License: MIT

{various_api_tools-1.0.0 → various_api_tools-2.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "various-api-tools"
-version = "1.0.0"
+version = "2.0.1"
 description = "A lightweight utility package for common API-related tasks in Python, including JSON and Pydantic error translators that provide user-friendly Russian messages."
 authors = [
     { name = "dkurchigin", email = "kurchigin.dmitry@yandex.ru" },
@@ -160,6 +160,7 @@ dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
 ]
 "src/various_api_tools/translators/psycopg/base.py" = [
     "ANN401",
+    "RUF012",
 ]
 "src/various_api_tools/translators/psycopg/psycopg.py" = [
     "ANN401",

various_api_tools-2.0.1/src/various_api_tools/translators/psycopg/base.py

@@ -0,0 +1,279 @@
+"""Abstract base class for translating psycopg/psycopg2 database errors.
+
+This module provides a foundation for parsing PostgreSQL error
+details (such as `pgcode` and `pgerror`) from psycopg exceptions and converting
+them into structured, human-readable error descriptions.
+It supports both `psycopg2` and `psycopg3` by abstracting access to error attributes,
+allowing concrete implementations to handle version-specific details.
+"""
+
+import re
+from typing import Any
+
+from .constants import (
+    CHECK_VIOLATION_PATTERN,
+    UNIQUE_VIOLATION_PATTERN,
+    UNKNOWN_CHECK_DESCRIPTION,
+    UNKNOWN_CODE,
+)
+
+
+class BaseErrorHandler:
+    """Base class for PostgreSQL error handlers.
+
+    Each handler is responsible for detecting and translating specific
+    PostgreSQL error codes (e.g., ``23505`` for unique violations).
+    Subclasses must implement `_get_pgcode`, `_get_pgerror`, and `handle`.
+    """
+
+    codes: list[str]
+    """PostgreSQL error codes (SQLSTATE) this handler supports."""
+
+    message_map: dict[str, str]
+    """Optional mapping to customize error messages per field/constraint name."""
+
+    def __init__(self, codes: list[str], message_map: dict[str, str]) -> None:
+        """Initialize the error handler with codes and optional message map.
+
+        Args:
+            codes: List of PostgreSQL SQLSTATE error codes this handler handles.
+            message_map: Optional mapping of constraint/field names to descriptions.
+
+        """
+        self.codes = codes
+        self.message_map = message_map
+
+    def can_handle(self, error: Any) -> bool:
+        """Check if this handler can process the given error.
+
+        Args:
+            error: A PostgreSQL exception instance (e.g., `psycopg.Error`).
+
+        Returns:
+            ``True`` if the error code matches one of the supported codes,
+            ``False`` otherwise.
+
+        """
+        return self._get_pgcode(error=error) in self.codes
+
+    def handle(self, error: Any) -> str:
+        """Process the error and return a translated message.
+
+        Args:
+            error: A PostgreSQL exception instance.
+
+        Returns:
+            A human-readable error message.
+
+        Raises:
+            NotImplementedError: Must be implemented by subclasses.
+
+        """
+        raise NotImplementedError
+
+    def _get_pgcode(self, error: Any) -> str | None:
+        """Extract the PostgreSQL SQLSTATE error code from the error object.
+
+        Args:
+            error: A PostgreSQL exception instance.
+
+        Returns:
+            The error code (e.g., ``'23505'``), or ``None`` if not available.
+
+        Raises:
+            NotImplementedError: Must be implemented by subclasses (e.g., in mixin).
+
+        """
+        raise NotImplementedError
+
+    def _get_pgerror(self, error: Any) -> str | None:
+        """Extract the human-readable PostgreSQL error message.
+
+        Args:
+            error: A PostgreSQL exception instance.
+
+        Returns:
+            The full error message string, or ``None`` if not available.
+
+        Raises:
+            NotImplementedError: Must be implemented by subclasses (e.g., in mixin).
+
+        """
+        raise NotImplementedError
+
+
+class BaseCheckErrorHandler(BaseErrorHandler):
+    """Handler for PostgreSQL check constraint violations (SQLSTATE ``23514``).
+
+    Extracts the check constraint field name from the error message
+    and returns a human-readable description (custom or default).
+    """
+
+    def __init__(
+        self,
+        codes: list[str] | None = None,
+        message_map: dict[str, str] | None = None,
+    ) -> None:
+        """Initialize the check constraint error handler.
+
+        Args:
+            codes: PostgreSQL error codes. Defaults to ``["23514"]``.
+            message_map: Optional mapping of field/constraint names to custom messages.
+                If a field name isn't in the map, uses `UNKNOWN_CHECK_DESCRIPTION`.
+
+        """
+        super().__init__(
+            codes=["23514"] if codes is None else codes,
+            message_map={} if message_map is None else message_map,
+        )
+
+    def handle(self, error: Any) -> str:
+        """Handle a PostgreSQL check constraint violation.
+
+        Args:
+            error: A PostgreSQL exception instance (must contain ``pgerror``).
+
+        Returns:
+            A human-readable error message for the check constraint violation.
+
+        Returns:
+            The translated string with an appropriate explanation
+
+        """
+        pg_error = self._get_pgerror(error=error)
+
+        pattern = re.compile(CHECK_VIOLATION_PATTERN)
+        matched = pattern.search(pg_error)
+
+        if matched is not None:
+            value: str = matched.group(1)
+            return self.message_map.get(
+                value,
+                UNKNOWN_CHECK_DESCRIPTION,
+            )
+
+        return UNKNOWN_CODE
+
+
+class BaseUniqueErrorHandler(BaseErrorHandler):
+    """Handler for PostgreSQL unique constraint violations (SQLSTATE 23505, 23503).
+
+    Extracts the field/constraint name from the error message
+    and returns a human-readable description (custom or default).
+    """
+
+    def __init__(
+        self,
+        codes: list[str] | None = None,
+        message_map: dict[str, str] | None = None,
+    ) -> None:
+        """Initialize the unique constraint error handler.
+
+        Args:
+            codes: PostgreSQL error codes. Defaults to ``["23505", "23503"]``.
+            message_map: Optional mapping of field/constraint names to custom messages.
+                If a field name isn't in the map, uses `UNKNOWN_CHECK_DESCRIPTION`.
+
+        """
+        super().__init__(
+            codes=["23505", "23503"] if codes is None else codes,
+            message_map={} if message_map is None else message_map,
+        )
+
+    def handle(self, error: Any) -> str:
+        """Handle a PostgreSQL unique constraint violation.
+
+        Args:
+            error: A PostgreSQL exception instance (must contain ``pgerror``).
+
+        Returns:
+            A human-readable error message for the unique constraint violation.
+
+        Example:
+            Assuming error message:
+            ```
+            duplicate key value violates unique constraint "users_email_key"
+            DETAIL:  Key (email)=(test@example.com) already exists.
+            ```
+
+            And ``message_map = {"users_email_key": "This email already exists."}``
+
+        Returns:
+            ```python
+            "This email already exists."
+            ```
+
+        """
+        pg_error = self._get_pgerror(error=error)
+
+        pattern = re.compile(UNIQUE_VIOLATION_PATTERN)
+        matched = pattern.search(pg_error)
+
+        if matched is not None:
+            key = matched.group(2)
+            # value = matched.group(3)
+
+            return self.message_map.get(
+                key,
+                UNKNOWN_CHECK_DESCRIPTION,
+            )
+
+        return UNKNOWN_CODE
+
+
+class BasePsycopgTranslator:
+    """Base class for translating PostgreSQL errors using error handlers.
+
+    Implements the Chain of Responsibility pattern over error handlers.
+    Each handler decides if it can process the error; the first matching one does.
+    Concrete subclasses should provide implementation
+    of ``_get_pgcode``/``_get_pgerror``
+    (typically via mixin like `Psycopg3HandlerMixin`).
+    """
+
+    handers: list[BaseErrorHandler]
+
+    def __init__(self) -> None:
+        """Initialize the translator with default handlers."""
+        self.handlers = self._default_handlers()
+
+    @classmethod
+    def _default_handlers(cls) -> list[BaseErrorHandler]:
+        """Return the list of default error handlers.
+
+        Returns:
+            A list containing:
+            - `BaseUniqueErrorHandler`
+            - `BaseCheckErrorHandler`
+
+        """
+        return [BaseUniqueErrorHandler(), BaseCheckErrorHandler()]
+
+    def translate(
+        self,
+        error: Any,
+    ) -> str:
+        """Translate a PostgreSQL error into a human-readable message.
+
+        Iterates through registered handlers and returns the first match.
+
+        Args:
+            error: A PostgreSQL exception instance (e.g., `psycopg.Error`).
+
+        Returns:
+            A translated error message string, or `UNKNOWN_CODE` if no handler matches.
+
+        Example:
+            ```python
+            translator = SomeTranslator()
+            error = psycopg2.IntegrityError(...)
+            print(translator.translate(error))
+            #> "This email already exists."
+            ```
+
+        """
+        for handler in self.handlers:
+            if handler.can_handle(error):
+                return handler.handle(error)
+
+        return UNKNOWN_CODE

{various_api_tools-1.0.0 → various_api_tools-2.0.1}/src/various_api_tools/translators/psycopg/constants.py

@@ -49,6 +49,7 @@ Used as the default value when a constraint name is not found in `check_map`.
 Displayed to users when the system cannot provide more specific validation feedback."""
 
 DEFAULT_CODE_MAP: Final[dict[str, str]] = {
+    "P0001": "Ошибка БД",
     "23503": "Указан несуществующий идентификатор связанного объекта",
     "23505": "БД уже содержит значение",
     "23514": "Нарушено ограничение данных",
@@ -56,6 +57,7 @@ DEFAULT_CODE_MAP: Final[dict[str, str]] = {
 """Default mapping of PostgreSQL SQLSTATE codes to user-friendly Russian error messages.
 
 Each key is a standardized SQLSTATE code:
+    - "P0001" (raise_exception): Custom exception raised in PL/pgSQL
     - "23503" (foreign_key_violation): Referenced object does not exist
     - "23505" (unique_violation): Duplicate key value
     - "23514" (check_violation): Data fails check constraint

various_api_tools-2.0.1/src/various_api_tools/translators/psycopg/psycopg.py

@@ -0,0 +1,176 @@
+"""Translator implementation for psycopg3 (psycopg) database errors.
+
+This module provides a concrete implementation of `BasePsycopgTranslator` tailored
+for `psycopg` (aka psycopg3) exceptions.
+It extracts error details using psycopg3's exception interface:
+- `sqlstate`: the SQLSTATE code (e.g. '23505' for unique violation)
+- `str(error)`: the full error message, as psycopg3 does not expose `pgerror` directly
+"""
+
+from typing import Any
+
+from .base import (
+    BaseCheckErrorHandler,
+    BaseErrorHandler,
+    BasePsycopgTranslator,
+    BaseUniqueErrorHandler,
+)
+
+
+class PsycopgHandlerMixin:
+    """Mixin providing psycopg3-specific error extraction logic.
+
+    Implements :meth:`BaseErrorHandler._get_pgcode` and
+    :meth:`BaseErrorHandler._get_pgerror` using psycopg3's native interface.
+
+    Example:
+        ```python
+        import psycopg
+
+        class MyTranslator(PsycopgHandlerMixin, BasePsycopgTranslator): ...
+
+        try:
+            ...
+        except psycopg.Error as e:
+            translator = MyTranslator()
+            message = translator.translate(e)
+            print(message)  # Translated, human-readable
+
+    """
+
+    def _get_pgcode(self, error: Any) -> str | None:
+        """Extract the PostgreSQL SQLSTATE code from a psycopg3 error.
+
+        Args:
+            error: A psycopg3 exception instance (e.g., `IntegrityError`).
+
+        Returns:
+            The SQLSTATE code as a 5-character string (e.g., ``'23505'``),
+            or ``None`` if the attribute is missing or not set.
+
+        Note:
+            psycopg3 uses ``error.sqlstate`` instead of the deprecated ``error.pgcode``.
+            The value is a string (not int) — e.g., ``"23505"``.
+
+        """
+        return getattr(error, "sqlstate", None)
+
+    def _get_pgerror(self, error: Any) -> str | None:
+        """Extract the full human-readable error message from a psycopg3 error.
+
+        Args:
+            error: A psycopg3 exception instance.
+
+        Returns:
+            The full error message as a string, or ``None`` if not available.
+
+        Note:
+            psycopg3 does *not* expose a dedicated ``pgerror`` attribute.
+            The full message is obtained via ``str(error)``, which includes
+            both the main error text and the ``DETAIL:`` portion.
+
+        Example:
+            For an error with message:
+
+            ```
+            duplicate key value violates unique constraint "users_email_key"
+            DETAIL:  Key (email)=(test@example.com) already exists.
+            ```
+
+            This method returns the full string above.
+
+        """
+        return str(error)
+
+
+class CheckErrorHandler(PsycopgHandlerMixin, BaseCheckErrorHandler):
+    """Handler for PostgreSQL check constraint violations(sqlstate='23514') in psycopg3.
+
+    Extracts the constraint name from the error message using the pattern:
+
+        ``Key (value)=(...) violates check constraint "(<name>)".``
+
+    and returns a custom description from :attr:`BaseCheckErrorHandler.message_map`
+    if available; otherwise falls back to ``UNKNOWN_CHECK_DESCRIPTION``.
+
+    Args:
+        codes: List of SQLSTATE codes. Defaults to ``["23514"]``.
+        message_map: Optional mapping from constraint name → custom message.
+
+    Example:
+        ```python
+        handler = CheckErrorHandler(
+            message_map={"age_must_be_positive": "Age must be greater than zero."}
+        )
+        # Error: "Key (age)=(0) violates check constraint "age_must_be_positive"."
+        # → "Age must be greater than zero."
+        ```
+
+    """
+
+
+class UniqueErrorHandler(PsycopgHandlerMixin, BaseUniqueErrorHandler):
+    r"""Handler for PostgreSQL unique/concurrent constraint violations in psycopg3.
+
+    Handles SQLSTATE codes:
+    - ``'23505'``: unique violation
+    - ``'23503'``: foreign key violation
+
+    Extracts the constraint name and value from:
+
+        ``Key (<field>)=(<value>) already exists.``
+
+    Uses :attr:`BaseUniqueErrorHandler.message_map` for custom messages.
+
+    Args:
+        codes: List of SQLSTATE codes. Defaults to ``["23505", "23503"]``.
+        message_map: Optional mapping from constraint name → custom message.
+
+    Example:
+        ```python
+        handler = UniqueErrorHandler(
+            message_map={"users_email_key": "A user with this email already exists."}
+        )
+        # Error: "duplicate key value violates unique constraint \"users_email_key\""
+        #        "DETAIL:  Key (email)=(test@example.com) already exists."
+        # → "A user with this email already exists."
+        ```
+
+    """
+
+
+class PsycopgErrorTranslator(BasePsycopgTranslator):
+    """Translator for PostgreSQL errors in psycopg3.
+
+    Implements :meth:`BasePsycopgTranslator._default_handlers` to provide
+    a chain of psycopg3-specific handlers:
+
+    1. :class:`UniqueErrorHandler` (for ``23505``, ``23503``)
+    2. :class:`CheckErrorHandler` (for ``23514``)
+
+    Use this class directly for psycopg3, or subclass to override defaults.
+
+    Example:
+        ```python
+        translator = PsycopgErrorTranslator()
+        error = psycopg.Error(...)
+        print(translator.translate(error))
+        #> "A user with this email already exists."
+        ```
+
+    See Also:
+        :class:`Psycopg2ErrorTranslator` — for ``psycopg2`` compatibility.
+
+    """
+
+    @classmethod
+    def _default_handlers(cls) -> list[BaseErrorHandler]:
+        """Return a list of default handlers for psycopg3 errors.
+
+        Returns:
+            A list containing:
+            - :class:`UniqueErrorHandler`
+            - :class:`CheckErrorHandler`
+
+        """
+        return [UniqueErrorHandler(), CheckErrorHandler()]

various_api_tools-2.0.1/src/various_api_tools/translators/psycopg/psycopg2.py

@@ -0,0 +1,178 @@
+"""Translator implementation for psycopg2-specific database errors.
+
+This module provides a concrete implementation of `BasePsycopgTranslator`
+tailored for `psycopg2`exceptions.
+It extracts error details using `psycopg2`'s attribute-based interface:
+- `pgcode`: the SQLSTATE code (e.g. '23505' for unique violation)
+- `pgerror`: the full error message from PostgreSQL
+"""
+
+from typing import Any
+
+from .base import (
+    BaseCheckErrorHandler,
+    BaseErrorHandler,
+    BasePsycopgTranslator,
+    BaseUniqueErrorHandler,
+)
+
+
+class Psycopg2HandlerMixin:
+    """Mixin providing psycopg2-specific error extraction logic.
+
+    Implements :meth:`BaseErrorHandler._get_pgcode` and
+    :meth:`BaseErrorHandler._get_pgerror` using psycopg2's native interface.
+
+    Example:
+        ```python
+        import psycopg2
+
+        class MyTranslator(Psycopg2HandlerMixin, BasePsycopgTranslator): ...
+
+        try:
+            ...
+        except psycopg2.Error as e:
+            translator = MyTranslator()
+            message = translator.translate(e)
+            print(message)  # Translated, human-readable
+
+    """
+
+    def _get_pgcode(self, error: Any) -> str | None:
+        """Extract the PostgreSQL SQLSTATE code from a psycopg2 error.
+
+        Args:
+            error: A psycopg2 exception instance (e.g., `IntegrityError`).
+
+        Returns:
+            The SQLSTATE code as a string (e.g., ``'23505'``),
+            or ``None`` if the attribute is missing or not set.
+
+        Note:
+            psycopg2 uses ``error.pgcode`` — a string (not integer), as required
+            by PostgreSQL's SQLSTATE standard.
+
+        See Also:
+            :meth:`PsycopgHandlerMixin._get_pgcode` — for psycopg3 equivalent.
+
+        """
+        return getattr(error, "pgcode", None)
+
+    def _get_pgerror(self, error: Any) -> str | None:
+        """Extract the full human-readable error message from a psycopg2 error.
+
+        Args:
+            error: A psycopg2 exception instance.
+
+        Returns:
+            The full error message as a string, or ``None`` if not available.
+
+        Note:
+            psycopg2 stores the complete PostgreSQL error message in ``error.pgerror``,
+            which includes both the main error text and the ``DETAIL:`` portion.
+
+        Example:
+            For an error with message:
+
+            ```
+            duplicate key value violates unique constraint "users_email_key"
+            DETAIL:  Key (email)=(test@example.com) already exists.
+            ```
+
+            This method returns the full string above.
+
+        """
+        return getattr(error, "pgerror", None)
+
+
+class CheckErrorHandler(Psycopg2HandlerMixin, BaseCheckErrorHandler):
+    """Handler for PostgreSQL check constraint violations (pgcode='23514') in psycopg2.
+
+    Extracts the constraint name from the error message using the pattern:
+
+        ``Key (value)=(...) violates check constraint "(<name>)".``
+
+    and returns a custom description from :attr:`BaseCheckErrorHandler.message_map`
+    if available; otherwise falls back to ``UNKNOWN_CHECK_DESCRIPTION``.
+
+    Args:
+        codes: List of SQLSTATE codes. Defaults to ``["23514"]``.
+        message_map: Optional mapping from constraint name → custom message.
+
+    Example:
+        ```python
+        handler = CheckErrorHandler(
+            message_map={"age_must_be_positive": "Age must be greater than zero."}
+        )
+        # Error: "Key (age)=(0) violates check constraint "age_must_be_positive"."
+        # → "Age must be greater than zero."
+        ```
+
+    """
+
+
+class UniqueErrorHandler(Psycopg2HandlerMixin, BaseUniqueErrorHandler):
+    r"""Handler for PostgreSQL unique/concurrent constraint violations in psycopg2.
+
+    Handles SQLSTATE codes:
+    - ``'23505'``: unique violation
+    - ``'23503'``: foreign key violation
+
+    Extracts the constraint name and value from:
+
+        ``Key (<field>)=(<value>) already exists.``
+
+    Uses :attr:`BaseUniqueErrorHandler.message_map` for custom messages.
+
+    Args:
+        codes: List of SQLSTATE codes. Defaults to ``["23505", "23503"]``.
+        message_map: Optional mapping from constraint name → custom message.
+
+    Example:
+        ```python
+        handler = UniqueErrorHandler(
+            message_map={"users_email_key": "A user with this email already exists."}
+        )
+        # Error: "duplicate key value violates unique constraint \"users_email_key\""
+        #        "DETAIL:  Key (email)=(test@example.com) already exists."
+        # → "A user with this email already exists."
+        ```
+
+    """
+
+
+class Psycopg2ErrorTranslator(BasePsycopgTranslator):
+    """Translator for PostgreSQL errors in psycopg2.
+
+    Implements :meth:`BasePsycopgTranslator._default_handlers` to provide
+    a chain of psycopg2-specific handlers:
+
+    1. :class:`UniqueErrorHandler` (for ``23505``, ``23503``)
+    2. :class:`CheckErrorHandler` (for ``23514``)
+
+    Use this class directly for psycopg2, or subclass to override defaults.
+
+    Example:
+        ```python
+        translator = Psycopg2ErrorTranslator()
+        error = psycopg2.IntegrityError(...)
+        print(translator.translate(error))
+        #> "A user with this email already exists."
+        ```
+
+    See Also:
+        :class:`PsycopgErrorTranslator` — for psycopg3 compatibility.
+
+    """
+
+    @classmethod
+    def _default_handlers(cls) -> list[BaseErrorHandler]:
+        """Return a list of default handlers for psycopg2 errors.
+
+        Returns:
+            A list containing:
+            - :class:`UniqueErrorHandler`
+            - :class:`CheckErrorHandler`
+
+        """
+        return [UniqueErrorHandler(), CheckErrorHandler()]