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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: various-api-tools
-Version: 0.3.4
+Version: 1.0.0
 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
@@ -17,7 +17,6 @@ Project-URL: Documentation, https://various-api-tools.dkurchigin.ru/
 Project-URL: Source, https://gitverse.ru/dkurchigin/various-api-tools
 Requires-Python: >=3.10
 Requires-Dist: pydantic>=2.12.3
-Requires-Dist: psycopg2-binary>=2.9.10
 Requires-Dist: email-validator>=2.3.0
 Description-Content-Type: text/markdown
 
@@ -29,12 +28,12 @@ Description-Content-Type: text/markdown
 
 ```python
 import json
-from various_api_tools.translators.json import DecodeErrorTranslator
+from various_api_tools.translators.json import JSONDecodeErrorTranslator
 
 try:
     json.loads('{"name": "Alice",}')
 except json.JSONDecodeError as e:
-    print(DecodeErrorTranslator.translate(e))
+    print(JSONDecodeErrorTranslator.translate(e))
 
 # Output:
 # Ошибка конвертации в формате JSON.
@@ -44,7 +43,7 @@ except json.JSONDecodeError as e:
 
 ```python
 from pydantic import BaseModel, ValidationError
-from various_api_tools.translators.pydantic import ValidationErrorTranslator
+from various_api_tools.translators.pydantic import PydanticValidationErrorTranslator
 
 class User(BaseModel):
     email: str
@@ -52,7 +51,7 @@ class User(BaseModel):
 try:
     User(email=123)
 except ValidationError as e:
-    print(ValidationErrorTranslator.translate(e.errors()))
+    print(PydanticValidationErrorTranslator.translate(e.errors()))
 
 # Output:
 # Поле: "email". Ошибка: "Невалидное строковое значение(str)";

{various_api_tools-0.3.4 → various_api_tools-1.0.0}/README.md

@@ -6,12 +6,12 @@
 
 ```python
 import json
-from various_api_tools.translators.json import DecodeErrorTranslator
+from various_api_tools.translators.json import JSONDecodeErrorTranslator
 
 try:
     json.loads('{"name": "Alice",}')
 except json.JSONDecodeError as e:
-    print(DecodeErrorTranslator.translate(e))
+    print(JSONDecodeErrorTranslator.translate(e))
 
 # Output:
 # Ошибка конвертации в формате JSON.
@@ -21,7 +21,7 @@ except json.JSONDecodeError as e:
 
 ```python
 from pydantic import BaseModel, ValidationError
-from various_api_tools.translators.pydantic import ValidationErrorTranslator
+from various_api_tools.translators.pydantic import PydanticValidationErrorTranslator
 
 class User(BaseModel):
     email: str
@@ -29,7 +29,7 @@ class User(BaseModel):
 try:
     User(email=123)
 except ValidationError as e:
-    print(ValidationErrorTranslator.translate(e.errors()))
+    print(PydanticValidationErrorTranslator.translate(e.errors()))
 
 # Output:
 # Поле: "email". Ошибка: "Невалидное строковое значение(str)";

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

@@ -1,13 +1,12 @@
 [project]
 name = "various-api-tools"
-version = "0.3.4"
+version = "1.0.0"
 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" },
 ]
 dependencies = [
     "pydantic>=2.12.3",
-    "psycopg2-binary>=2.9.10",
     "email-validator>=2.3.0",
 ]
 requires-python = ">=3.10"
@@ -152,16 +151,21 @@ dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
     "FBT",
     "SLF",
 ]
-"src/various_api_tools/translators/pydantic.py" = [
+"src/various_api_tools/validators/pydantic/constants.py" = [
     "RUF001",
-    "TID252",
 ]
-"src/various_api_tools/validators/pydantic.py" = [
+"src/various_api_tools/validators/pydantic/utils.py" = [
     "EM101",
-    "TID252",
+    "ANN401",
 ]
-"src/various_api_tools/error_maps/pydantic.py" = [
-    "RUF001",
+"src/various_api_tools/translators/psycopg/base.py" = [
+    "ANN401",
+]
+"src/various_api_tools/translators/psycopg/psycopg.py" = [
+    "ANN401",
+]
+"src/various_api_tools/translators/psycopg/psycopg2.py" = [
+    "ANN401",
 ]
 
 [tool.ruff.format]

various_api_tools-1.0.0/src/various_api_tools/__init__.py

@@ -0,0 +1,32 @@
+"""A package for various API utility tools.
+
+Including JSON and Pydantic error translators.
+"""
+
+from .translators.json import JSONDecodeErrorTranslator
+from .translators.psycopg.psycopg import PsycopgErrorTranslator
+from .translators.psycopg.psycopg2 import Psycopg2ErrorTranslator
+from .translators.pydantic import PydanticValidationErrorTranslator
+from .validators.pydantic.constants import PYDANTIC_ERROR_TYPES
+from .validators.pydantic.utils import (
+    email_validator,
+    latitude_validator,
+    longitude_validator,
+    optional_string_validator,
+    strip_validator,
+    validate_required_field,
+)
+
+__all__ = (
+    "PYDANTIC_ERROR_TYPES",
+    "JSONDecodeErrorTranslator",
+    "Psycopg2ErrorTranslator",
+    "PsycopgErrorTranslator",
+    "PydanticValidationErrorTranslator",
+    "email_validator",
+    "latitude_validator",
+    "longitude_validator",
+    "optional_string_validator",
+    "strip_validator",
+    "validate_required_field",
+)

various_api_tools-1.0.0/src/various_api_tools/translators/psycopg/__init__.py

@@ -0,0 +1 @@
+"""Module for concrete translator for psycopg/psycopg2 errors."""

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

@@ -0,0 +1,229 @@
+"""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 dataclasses import dataclass
+from typing import Any
+
+from .constants import (
+    CHECK_VIOLATION_PATTERN,
+    DEFAULT_CODE_MAP,
+    UNIQUE_VIOLATION_PATTERN,
+    UNKNOWN_CHECK_DESCRIPTION,
+    UNKNOWN_CODE,
+)
+
+
+@dataclass
+class ErrorData:
+    """Represents structured data extracted from a database error.
+
+    Used to capture constraint details such as the violated field and
+    its conflicting value.
+
+    Attributes:
+        key: The name of the field or constraint involved in the error.
+        value: The value that caused the constraint violation.
+
+    """
+
+    key: str
+    value: Any
+
+
+class BasePsycopgTranslator:
+    """Base translator for turning psycopg errors into user-friendly messages.
+
+    Supports customizing error messages via:
+    - `code_map`: maps SQLSTATE codes to human-readable messages
+    - `check_map`: maps check constraint names to meaningful descriptions
+
+    Subclasses must implement `_get_pgcode()` and `_get_pgerror()` to support specific
+    psycopg versions (e.g., psycopg2 vs. psycopg3).
+
+    Attributes:
+        code_map (dict): Mapping from SQLSTATE codes (str) to error messages (str).
+        check_map (dict): Mapping from check constraint names (str)
+            to descriptions (str).
+
+    """
+
+    code_map: dict
+    check_map: dict
+
+    def __init__(
+        self,
+        *,
+        code_map: dict | None = None,
+        check_map: dict | None = None,
+    ) -> None:
+        """Initialize the translator with optional custom message mappings.
+
+        Args:
+            code_map: Optional mapping from SQLSTATE codes (e.g. '23505')
+                to error messages. If None, defaults to `DEFAULT_CODE_MAP`.
+            check_map: Optional mapping from check constraint names
+                to descriptive messages. If None, defaults to an empty dict.
+
+        Example:
+        ```python
+            custom_codes = {"23505": "Значение уже существует"}
+            custom_checks = {"age_check": "Возраст должен быть от 18 до 120"}
+            t = BasePsycopgTranslator(code_map=custom_codes, check_map=custom_checks)
+        ```
+
+        """
+        if code_map is not None:
+            self.code_map = code_map
+        else:
+            self.code_map = DEFAULT_CODE_MAP
+
+        if check_map is not None:
+            self.check_map = check_map
+        else:
+            self.check_map = {}
+
+    def translate(
+        self,
+        error: Any,
+    ) -> str:
+        """Translate a psycopg database error into a user-friendly message.
+
+        Extracts `pgcode` and `pgerror` from the error and formats a meaningful response
+        based on the type of constraint violation (unique, check, foreign key).
+
+        Args:
+            error: A psycopg exception (e.g. IntegrityError, DatabaseError).
+
+        Returns:
+            A formatted error message, or a fallback if no match is found.
+
+        Example:
+        ```python
+            # Given error: unique_violation on email = 'test@example.com'
+            print(translator.translate(error))
+            #> "БД уже содержит значение: ключ email, значение test@example.com"
+        ```
+
+        """
+        msg: str = UNKNOWN_CODE
+
+        pgcode = self._get_pgcode(error)
+        pgerror = self._get_pgerror(error)
+
+        if pgcode is not None:
+            code_msg: str | None = self.code_map.get(pgcode, UNKNOWN_CODE)
+            data: ErrorData | None = None
+
+            if pgcode == "23514":
+                data = self._translate_check_violation(error_msg=pgerror)
+            elif pgcode in ["23505", "23503"]:
+                data = self._translate_unique_violation(error_msg=pgerror)
+
+            if data and code_msg:
+                msg = f"{code_msg}: ключ {data.key}, значение {data.value}."
+            else:
+                msg = code_msg
+
+        return msg
+
+    def _get_pgcode(self, error: Any) -> str | None:
+        """Extract pgcode code from the error.
+
+        Must be implemented by subclasses to support specific psycopg versions.
+
+        Args:
+            error: The raw database exception.
+
+        Returns:
+            The SQLSTATE code as a string (e.g. '23505'), or None if not available.
+
+        """
+        raise NotImplementedError
+
+    def _get_pgerror(self, error: Any) -> str | None:
+        """Extract the full error message from the exception.
+
+        Must be implemented by subclasses to support specific psycopg versions.
+
+        Args:
+            error: The raw database exception.
+
+        Returns:
+            Full error message string, or None if not available.
+
+        """
+        raise NotImplementedError
+
+    @classmethod
+    def _translate_unique_violation(cls, error_msg: str) -> ErrorData:
+        """Extract field and value from a unique constraint violation error.
+
+        Uses a regex to parse the PostgreSQL
+        "DETAIL: Key (field)=(value) already exists" message.
+
+        Args:
+            error_msg: The full error text from the database.
+
+        Returns:
+            ErrorData with extracted field name and value, or None if not matched.
+
+        Example:
+        ```python
+            error_msg = "DETAIL: Key (email)=(user@example.com) already exists."
+            print(BasePsycopgTranslator._translate_unique_violation(error_msg))
+            #> ErrorData(key='email', value='user@example.com')
+        ```
+
+        """
+        data: ErrorData | None = None
+
+        pattern = re.compile(UNIQUE_VIOLATION_PATTERN)
+        matched = pattern.search(error_msg)
+
+        if matched is not None:
+            data = ErrorData(key=matched.group(2), value=matched.group(3))
+
+        return data
+
+    def _translate_check_violation(self, error_msg: str) -> ErrorData | None:
+        """Extract constraint name and description from a check constraint violation.
+
+        Looks up a human-readable description in `self.check_map`. If not found,
+        returns a default message.
+
+        Args:
+            error_msg: The full error text from the database.
+
+        Returns:
+            ErrorData with constraint name and description, or None if not matched.
+
+        Example:
+        ```python
+            error_msg = "violates check constraint 'age_check'"
+            check_map = {"age_check": "Возраст должен быть от 18 до 120"}
+            translator = BasePsycopgTranslator(check_map=check_map)
+            print(translator._translate_check_violation(error_msg))
+            #> ErrorData(key='age_check', value='Возраст должен быть от 18 до 120')
+        ```
+
+        """
+        data: ErrorData | None = None
+
+        pattern = re.compile(CHECK_VIOLATION_PATTERN)
+        matched = pattern.search(error_msg)
+        if matched is not None:
+            check_constraint = matched.group(1)
+            constraint_description = self.check_map.get(
+                check_constraint,
+                UNKNOWN_CHECK_DESCRIPTION,
+            )
+            data = ErrorData(key=check_constraint, value=constraint_description)
+
+        return data

various_api_tools-1.0.0/src/various_api_tools/translators/psycopg/constants.py

@@ -0,0 +1,71 @@
+"""Psycopg error translation constants.
+
+This module defines constants used by the PsycopgErrorTranslator for parsing and
+translating PostgreSQL error messages from psycopg and psycopg2 into user-friendly
+localized messages.
+
+The constants include:
+- Regular expressions to extract structured details from PostgreSQL error texts
+- Mappings from SQLSTATE codes to human-readable messages
+- Default error descriptions for common constraint violations
+
+These are primarily used to enhance error reporting in API responses by providing
+clear, actionable feedback based on database-level constraints (e.g., unique,
+foreign key, and check violations).
+"""
+
+from typing import Final
+
+UNIQUE_VIOLATION_PATTERN: Final[str] = r"DETAIL:.*(Key|Ключ).*\((.*?)\)=\((.*?)\)"
+"""Regex pattern to extract details from PostgreSQL unique constraint violation errors.
+
+Matches the standard PostgreSQL error detail message format:
+'DETAIL: Key (field)=(value) already exists.' or localized version 'Ключ'.
+
+Captures:
+    Group 1: 'Key' or 'Ключ' (language-independent match)
+    Group 2: Column name involved in the constraint
+    Group 3: Conflicting value
+
+Used by: `BasePsycopgTranslator._translate_unique_violation`
+Example match: 'DETAIL: Key (email)=(user@example.com) already exists.' →
+key='email', value='user@example.com'"""
+
+CHECK_VIOLATION_PATTERN: Final[str] = r'violates check constraint.*?"(.*?)"'
+"""Regex pattern to extract the name of a violated check constraint from PSQL error.
+
+Matches error messages containing: 'violates check constraint "constraint_name"'.
+Captures the constraint name in group 1.
+
+Used by: `BasePsycopgTranslator._translate_check_violation`
+Example: 'new row for relation "users" violates check constraint "users_age_check"'
+→ 'users_age_check'"""
+
+UNKNOWN_CHECK_DESCRIPTION: Final[str] = "Невалидная запись в БД"
+"""Fallback message used when a check constraint is violated but no custom description
+is configured.
+
+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]] = {
+    "23503": "Указан несуществующий идентификатор связанного объекта",
+    "23505": "БД уже содержит значение",
+    "23514": "Нарушено ограничение данных",
+}
+"""Default mapping of PostgreSQL SQLSTATE codes to user-friendly Russian error messages.
+
+Each key is a standardized SQLSTATE code:
+    - "23503" (foreign_key_violation): Referenced object does not exist
+    - "23505" (unique_violation): Duplicate key value
+    - "23514" (check_violation): Data fails check constraint
+
+Values are localized messages suitable for API responses.
+Can be overridden in translator instances for custom messaging."""
+
+UNKNOWN_CODE: Final[str] = "Неизвестная ошибка БД"
+"""Fallback message used when an unrecognized SQLSTATE code is encountered.
+
+Ensures that no raw database error codes or technical messages are exposed to end users.
+Should be replaced with more specific messages during
+system localization or customization."""

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

@@ -0,0 +1,43 @@
+"""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 BasePsycopgTranslator
+
+
+class PsycopgErrorTranslator(BasePsycopgTranslator):
+    """Concrete error translator for psycopg (psycopg3) exceptions.
+
+    Implements the `_get_pgcode` and `_get_pgerror` methods to extract error details
+    from `psycopg` exception objects:
+    - Uses `.sqlstate` attribute for SQLSTATE code (psycopg3 equivalent of pgcode)
+    - Uses `str(error)` as the error message, since psycopg3 does not expose `.pgerror`
+
+    Supports customization via:
+    - `code_map`: mapping of SQLSTATE codes to user-facing messages
+    - `check_map`: mapping of check constraint names to human-readable descriptions
+
+    Usage:
+        translator = PsycopgErrorTranslator(
+            code_map={"23505": "Значение уже существует"},
+            check_map={"users_age_check": "Возраст должен быть от 18 до 120"}
+        )
+
+    Note:
+        This class is intended for use with `psycopg` >= 3.0. For `psycopg2`, use
+        `Psycopg2ErrorTranslator` instead.
+
+    """
+
+    def _get_pgcode(self, error: Any) -> str | None:
+        return getattr(error, "sqlstate", None)
+
+    def _get_pgerror(self, error: Any) -> str | None:
+        return str(error)

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

@@ -0,0 +1,36 @@
+"""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 BasePsycopgTranslator
+
+
+class Psycopg2ErrorTranslator(BasePsycopgTranslator):
+    """Concrete error translator for psycopg2 exceptions.
+
+    Implements the `_get_pgcode` and `_get_pgerror` methods to extract error details
+    from `psycopg2` exception objects using their standard attributes.
+
+    This class supports customization via:
+    - `code_map`: mapping of SQLSTATE codes to user-friendly messages
+    - `check_map`: mapping of check constraint names to descriptive texts
+
+    Usage:
+        translator = Psycopg2ErrorTranslator(
+            code_map={"23505": "Значение уже существует"},
+            check_map={"users_age_check": "Возраст должен быть от 18 до 120"}
+        )
+    """
+
+    def _get_pgcode(self, error: Any) -> str | None:
+        return getattr(error, "pgcode", None)
+
+    def _get_pgerror(self, error: Any) -> str | None:
+        return getattr(error, "pgerror", None)

{various_api_tools-0.3.4 → various_api_tools-1.0.0}/src/various_api_tools/translators/pydantic.py

@@ -10,7 +10,10 @@ from typing import Final
 
 from pydantic_core import ErrorDetails
 
-from ..error_maps.pydantic import PYDANTIC_ERROR_TYPES, UNKNOWN_ERROR_TYPE
+from ..validators.pydantic.constants import (  # noqa: TID252
+    PYDANTIC_ERROR_TYPES,
+    UNKNOWN_ERROR_TYPE,
+)
 
 DEFAULT_LOCATION_PREFIX: Final[str] = "Поле"
 

various_api_tools-1.0.0/src/various_api_tools/validators/pydantic/__init__.py

@@ -0,0 +1 @@
+"""Module for concrete API validators with Pydantic."""

various_api_tools-0.3.4/src/various_api_tools/error_maps/pydantic.py → various_api_tools-1.0.0/src/various_api_tools/validators/pydantic/constants.py

@@ -1,11 +1,40 @@
-"""Module for mapping Pydantic validation error codes to messages in Russian.
+"""Module: Pydantic Validator Constants.
 
-This module provides a dictionary that maps common Pydantic error types to descriptive
-error messages in Russian, used for user-friendly validation feedback.
+This module defines constants used across Pydantic-based
+validators in the application.
+It includes:
+- Geographical coordinate boundaries (latitude and longitude limits)
+- A centralized mapping of error codes to localized human-readable
+messages (`PYDANTIC_ERROR_TYPES`)
+- Default error message for unknown validation issues (`UNKNOWN_ERROR_TYPE`)
 """
 
 from typing import Final
 
+MIN_LATITUDE: Final[float] = -90.0
+"""Minimum allowed latitude value in degrees (-90.0 corresponds to the South Pole).
+
+Used in geographic validation to ensure latitude values are within valid range.
+See: `latitude_validator` in `utils.py`."""
+
+MAX_LATITUDE: Final[float] = 90.0
+"""Maximum allowed latitude value in degrees (90.0 corresponds to the North Pole).
+
+Used in geographic validation to ensure latitude values are within valid range.
+See: `latitude_validator` in `utils.py`."""
+
+MIN_LONGITUDE: Final[float] = -180.0
+"""Minimum allowed longitude value in degrees (-180.0 corresponds to the IDL).
+
+Used in geographic validation to ensure longitude values are within valid range.
+See: `longitude_validator` in `utils.py`."""
+
+MAX_LONGITUDE: Final[float] = 180.0
+"""Maximum allowed longitude value in degrees (180.0 corresponds to the IDL).
+
+Used in geographic validation to ensure longitude values are within valid range.
+See: `longitude_validator` in `utils.py`."""
+
 PYDANTIC_ERROR_TYPES: dict[str, str] = {
     "missing": "Не заполнено обязательное поле",
     "uuid_parsing": "Невалидное значение для UUID",
@@ -37,4 +66,22 @@ PYDANTIC_ERROR_TYPES: dict[str, str] = {
     "incorrect_email": "Невалидное значение email-адреса",
     "list_expected": "Некорректный тип данных. Ожидается список.",
 }
+"""Mapping of Pydantic built-in error codes to localized Russian messages.
+
+Used by custom validators to provide consistent, user-friendly error descriptions
+in API responses. Each key corresponds to a standard Pydantic error type.
+Values are human-readable messages suitable for end users or frontend display.
+
+Example keys:
+- 'string_type': invalid type for string field
+- 'incorrect_email': failed email format validation
+- 'missing': required field is missing
+
+Used in: `optional_string_validator`, `email_validator`, etc."""
+
 UNKNOWN_ERROR_TYPE: Final[str] = "Неизвестная ошибка"
+"""Default fallback message for validation errors with
+no matching code in `PYDANTIC_ERROR_TYPES`.
+
+Used when an unexpected or unrecognized error code is encountered during validation,
+ensuring that no raw or technical messages are exposed to the user."""