various-api-tools 0.3.6__tar.gz → 2.0.0__tar.gz

{various_api_tools-0.3.6 → various_api_tools-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: various-api-tools
-Version: 0.3.6
+Version: 2.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
@@ -28,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.
@@ -43,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
@@ -51,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.6 → various_api_tools-2.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.6 → various_api_tools-2.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "various-api-tools"
-version = "0.3.6"
+version = "2.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" },
@@ -151,16 +151,22 @@ 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",
+    "RUF012",
+]
+"src/various_api_tools/translators/psycopg/psycopg.py" = [
+    "ANN401",
+]
+"src/various_api_tools/translators/psycopg/psycopg2.py" = [
+    "ANN401",
 ]
 
 [tool.ruff.format]

various_api_tools-2.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-2.0.0/src/various_api_tools/translators/psycopg/__init__.py

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

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

@@ -0,0 +1,256 @@
+"""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,
+    DEFAULT_CODE_MAP,
+    UNIQUE_VIOLATION_PATTERN,
+    UNKNOWN_CHECK_DESCRIPTION,
+    UNKNOWN_CODE,
+    UNKNOWN_USER_RAISE_DESCRIPTION,
+)
+
+
+class BasePsycopgTranslator:
+    """Base translator for turning psycopg errors into user-friendly messages.
+
+    Supports customization via:
+    - `code_map`: maps SQLSTATE codes to human-readable messages
+    - `check_map`: maps check constraint names to meaningful descriptions
+    - `user_map`: maps database column names to user-friendly field names
+
+    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).
+        user_map (dict): Mapping from DB column/field names (str)
+            to user-friendly names (str).
+
+    """
+
+    code_map: dict
+    check_map: dict
+    user_map: dict
+
+    check_codes: list[str] = ["23514"]
+    unique_codes: list[str] = ["23505", "23503"]
+    user_codes: list[str] = ["P0001"]
+
+    def __init__(
+        self,
+        *,
+        code_map: dict | None = None,
+        check_map: dict | None = None,
+        user_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.
+            user_map: Optional mapping from database column names to
+                user-friendly field names.
+                    Used to improve readability in error messages.
+                    Example: {"email": "Email пользователя", "phone": "Номер телефона"}
+                    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)
+        ```
+
+        """
+        self.code_map = code_map if code_map is not None else DEFAULT_CODE_MAP
+        self.check_map = check_map if check_map is not None else {}
+        self.user_map = user_map if user_map is not None else {}
+
+    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)
+
+            if pgcode in self.check_codes:
+                msg = self._translate_check_violation(
+                    code_msg=code_msg,
+                    error_msg=pgerror,
+                )
+            elif pgcode in self.unique_codes:
+                msg = self._translate_unique_violation(
+                    code_msg=code_msg,
+                    error_msg=pgerror,
+                )
+            elif pgcode in self.user_codes:
+                msg = self._translate_user_raise(code_msg=code_msg, error_msg=pgerror)
+
+        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, code_msg: str, error_msg: str) -> str:
+        """Extract details from a unique constraint violation and format a message.
+
+        Parses the PostgreSQL error message to extract the violated field and
+        its conflicting value using a predefined regex pattern.
+
+        Args:
+            code_msg: Base message from code_map for this error type.
+            error_msg: Full PostgreSQL error text.
+
+        Returns:
+            Formatted message with field name and value if found;
+            otherwise returns the base code_msg.
+
+        Example:
+            For error_msg = "DETAIL: Key (email)=(user@example.com) already exists",
+            returns: "БД уже содержит значение: ключ email, значение user@example.com"
+
+        """
+        msg = code_msg
+
+        pattern = re.compile(UNIQUE_VIOLATION_PATTERN)
+        matched = pattern.search(error_msg)
+
+        if matched is not None:
+            constraint = matched.group(2)
+            description = matched.group(3)
+            if constraint and description:
+                msg = f"{code_msg}: ключ {constraint}, значение {description}"
+
+        return msg
+
+    def _translate_check_violation(self, code_msg: str, error_msg: str) -> str:
+        """Extract details from a check constraint violation and return a message.
+
+        Looks up the violated constraint in `check_map` for a custom description.
+        Falls back to `UNKNOWN_CHECK_DESCRIPTION` if not found.
+
+        Args:
+            code_msg: Base message from code_map for this error type.
+            error_msg: Full PostgreSQL error text.
+
+        Returns:
+            Formatted message with constraint name and its description if available;
+            otherwise returns the base code_msg.
+
+        Example:
+            If constraint 'age_check' is violated and check_map provides a description,
+            returns: "Нарушено ограничение данных: ключ age_check.
+            Описание: Возраст должен быть от 18 до 120"
+
+        """
+        msg = code_msg
+
+        pattern = re.compile(CHECK_VIOLATION_PATTERN)
+        matched = pattern.search(error_msg)
+        if matched is not None:
+            constraint = matched.group(1)
+            description = self.check_map.get(
+                constraint,
+                UNKNOWN_CHECK_DESCRIPTION,
+            )
+
+            if constraint and description:
+                msg = f"{code_msg}: ключ {constraint}. Описание: {description}"
+
+        return msg
+
+    def _translate_user_raise(self, code_msg: str, error_msg: str) -> str:
+        """Extract details from a user-raised exception and return a message.
+
+        Searches the error message for known field keys defined in `user_map`.
+        Returns a user-friendly description if a match is found; otherwise falls back
+        to `UNKNOWN_USER_RAISE_DESCRIPTION`.
+
+        Args:
+            code_msg: Base message from code_map for this error type.
+            error_msg: Full PostgreSQL error text from RAISE EXCEPTION.
+
+        Returns:
+            Formatted message with a friendly field description if found;
+            otherwise returns the base code_msg with a generic description.
+
+        Example:
+            If error_msg contains 'status' and user_map={"status": "Статус"},
+            returns: "Ошибка БД: Статус"
+
+            If no match is found:
+            returns: "Ошибка БД: Невозможно выполнить операцию"
+
+        """
+        description = UNKNOWN_USER_RAISE_DESCRIPTION
+
+        for key in self.user_map:
+            if key in error_msg:
+                description = self.user_map.get(key)
+                break
+
+        return f"{code_msg}: {description}"

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

@@ -0,0 +1,88 @@
+"""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."""
+
+UNKNOWN_USER_RAISE_DESCRIPTION: Final[str] = "Невозможно выполнить операцию"
+"""Default message shown when a custom database RAISE EXCEPTION is caught,
+but no matching field or rule is found in `user_map`.
+
+Used as a fallback in `BasePsycopgTranslator._translate_user_raise`
+to avoid exposing raw internal messages to end users."""
+
+USER_RAISE_KEY: Final[str] = "Ошибка БД"
+"""Default display key used in error messages generated from RAISE EXCEPTION.
+
+Used as a generic identifier when formatting user-facing errors from custom
+database raises, especially when no specific field mapping is available.
+
+Example: '{Ошибка БД}: {описание}'"""
+
+DEFAULT_CODE_MAP: Final[dict[str, str]] = {
+    "P0001": "Ошибка БД",
+    "23503": "Указан несуществующий идентификатор связанного объекта",
+    "23505": "БД уже содержит значение",
+    "23514": "Нарушено ограничение данных",
+}
+"""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
+
+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-2.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-2.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.6 → various_api_tools-2.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-2.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.6/src/various_api_tools/error_maps/pydantic.py → various_api_tools-2.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."""