various-api-tools 0.3.2__tar.gz → 0.3.3__tar.gz

{various_api_tools-0.3.2 → various_api_tools-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: various-api-tools
-Version: 0.3.2
+Version: 0.3.3
 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
@@ -16,8 +16,9 @@ Project-URL: Homepage, https://gitverse.ru/dkurchigin/various-api-tools
 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.11.7
+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
 
 # Various_api_tools

{various_api_tools-0.3.2 → various_api_tools-0.3.3}/pyproject.toml

@@ -1,13 +1,14 @@
 [project]
 name = "various-api-tools"
-version = "0.3.2"
+version = "0.3.3"
 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.11.7",
+    "pydantic>=2.12.3",
     "psycopg2-binary>=2.9.10",
+    "email-validator>=2.3.0",
 ]
 requires-python = ">=3.10"
 readme = "README.md"
@@ -40,6 +41,7 @@ build-backend = "pdm.backend"
 distribution = true
 
 [tool.pdm.scripts]
+isort = "ruff check --select I --fix ."
 test = "pytest --cov-report term-missing --cov=src tests/"
 lint = "ruff check --fix"
 format = "ruff format"
@@ -144,11 +146,22 @@ dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
     "E",
     "ANN",
     "EM",
+    "B",
     "TRY",
     "PT",
+    "FBT",
+    "SLF",
 ]
 "src/various_api_tools/translators/pydantic.py" = [
     "RUF001",
+    "TID252",
+]
+"src/various_api_tools/validators/pydantic.py" = [
+    "EM101",
+    "TID252",
+]
+"src/various_api_tools/error_maps/pydantic.py" = [
+    "RUF001",
 ]
 
 [tool.ruff.format]

{various_api_tools-0.3.2 → various_api_tools-0.3.3}/src/various_api_tools/__init__.py

@@ -3,12 +3,16 @@
 Including JSON and Pydantic error translators.
 """
 
+from .error_maps.pydantic import PYDANTIC_ERROR_TYPES
 from .translators.json import JSONDecodeErrorTranslator
 from .translators.psycopg2 import Psycopg2ErrorTranslator
 from .translators.pydantic import PydanticValidationErrorTranslator
+from .validators.pydantic import PydanticValidator
 
 __all__ = (
+    "PYDANTIC_ERROR_TYPES",
     "JSONDecodeErrorTranslator",
     "Psycopg2ErrorTranslator",
     "PydanticValidationErrorTranslator",
+    "PydanticValidator",
 )

various_api_tools-0.3.3/src/various_api_tools/error_maps/__init__.py

@@ -0,0 +1 @@
+"""Module for some error mappings."""

various_api_tools-0.3.3/src/various_api_tools/error_maps/pydantic.py

@@ -0,0 +1,40 @@
+"""Module for mapping Pydantic validation error codes to messages in Russian.
+
+This module provides a dictionary that maps common Pydantic error types to descriptive
+error messages in Russian, used for user-friendly validation feedback.
+"""
+
+from typing import Final
+
+PYDANTIC_ERROR_TYPES: dict[str, str] = {
+    "missing": "Не заполнено обязательное поле",
+    "uuid_parsing": "Невалидное значение для UUID",
+    "uuid_type": "Невалидное значение для UUID",
+    "uuid_version": "Невалидное значение для UUID",
+    "bool_parsing": "Невалидное значение для логического типа(bool)",
+    "bool_type": "Невалидное значение для логического типа(bool)",
+    "date_type": "Невалидное значение даты(date)",
+    "datetime_from_date_parsing": "Невалидное значение даты и времени(datetime)",
+    "datetime_type": "Невалидное значение даты и времени(datetime)",
+    "dict_type": "Невалидное значение словаря",
+    "list_type": "Невалидное значение списка",
+    "string_type": "Невалидное строковое значение(str)",
+    "enum": "Невалидное значение Enum",
+    "float_parsing": "Невалидное значение числа с плавающей точкой(float)",
+    "float_type": "Невалидное значение числа с плавающей точкой(float)",
+    "int_from_float": "Невалидное значение для целочисленного числа(int)",
+    "int_parsing": "Невалидное значение для целочисленного числа(int)",
+    "int_parsing_size": "Невалидное значение для целочисленного числа(int)",
+    "int_type": "Невалидное значение для целочисленного числа(int)",
+    "non_negative_int": "Невалидное значение для целочисленного числа(int), "
+    "должно быть больше или равно 0",
+    "incorrect_latitude": "Некорректное значение широты, должно быть больше, "
+    "чем -90.0 и меньше, чем 90.0",
+    "incorrect_longitude": "Некорректное значение долготы, должно быть больше, "
+    "чем -180.0 и меньше, чем 180.0",
+    "string_too_short": "Cтрока слишком короткая",
+    "ip_address": "Невалидное значение адреса IPv4/IPv6",
+    "incorrect_email": "Невалидное значение email-адреса",
+    "list_expected": "Некорректный тип данных. Ожидается список.",
+}
+UNKNOWN_ERROR_TYPE: Final[str] = "Неизвестная ошибка"

{various_api_tools-0.3.2 → various_api_tools-0.3.3}/src/various_api_tools/translators/pydantic.py

@@ -10,40 +10,9 @@ from typing import Final
 
 from pydantic_core import ErrorDetails
 
-pydantic_error_types: dict[str, str] = {
-    "missing": "Не заполнено обязательное поле",
-    "uuid_parsing": "Невалидное значение для UUID",
-    "uuid_type": "Невалидное значение для UUID",
-    "uuid_version": "Невалидное значение для UUID",
-    "bool_parsing": "Невалидное значение для логического типа(bool)",
-    "bool_type": "Невалидное значение для логического типа(bool)",
-    "date_type": "Невалидное значение даты(date)",
-    "datetime_from_date_parsing": "Невалидное значение даты и времени(datetime)",
-    "datetime_type": "Невалидное значение даты и времени(datetime)",
-    "dict_type": "Невалидное значение словаря",
-    "list_type": "Невалидное значение списка",
-    "string_type": "Невалидное строковое значение(str)",
-    "enum": "Невалидное значение Enum",
-    "float_parsing": "Невалидное значение числа с плавающей точкой(float)",
-    "float_type": "Невалидное значение числа с плавающей точкой(float)",
-    "int_from_float": "Невалидное значение для целочисленного числа(int)",
-    "int_parsing": "Невалидное значение для целочисленного числа(int)",
-    "int_parsing_size": "Невалидное значение для целочисленного числа(int)",
-    "int_type": "Невалидное значение для целочисленного числа(int)",
-    "non_negative_int": "Невалидное значение для целочисленного числа(int), "
-    "должно быть больше или равно 0",
-    "incorrect_latitude": "Некорректное значение широты, должно быть больше, "
-    "чем -90.0 и меньше, чем 90.0",
-    "incorrect_longitude": "Некорректное значение долготы, должно быть больше, "
-    "чем -180.0 и меньше, чем 180.0",
-    "string_too_short": "Cтрока слишком короткая",
-    "ip_address": "Невалидное значение адреса IPv4/IPv6",
-    "incorrect_email": "Невалидное значение email-адреса",
-    "list_expected": "Некорректный тип данных. Ожидается список.",
-}
+from ..error_maps.pydantic import PYDANTIC_ERROR_TYPES, UNKNOWN_ERROR_TYPE
 
 DEFAULT_LOCATION_PREFIX: Final[str] = "Поле"
-UNKNOWN_ERROR_TYPE: Final[str] = "Неизвестная ошибка"
 
 
 class PydanticValidationErrorTranslator:
@@ -54,6 +23,8 @@ class PydanticValidationErrorTranslator:
 
     """
 
+    error_types = PYDANTIC_ERROR_TYPES
+
     @classmethod
     def get_str_pydantic_loc(cls, loc: tuple[str]) -> str:
         """Convert a Pydantic location tuple into a dot-separated string.
@@ -114,10 +85,10 @@ class PydanticValidationErrorTranslator:
                 )
 
             if "type" in error:
-                msg = pydantic_error_types.get(error["type"], UNKNOWN_ERROR_TYPE)
+                msg = cls.error_types.get(error["type"], UNKNOWN_ERROR_TYPE)
                 type_part = f'Ошибка: "{msg}"'
 
-            if "input" in error and pydantic_error_types["missing"] not in type_part:
+            if "input" in error and cls.error_types["missing"] not in type_part:
                 input_part = f'заполнено неверно: "{error["input"]!r}"'
 
             if input_part != "":

various_api_tools-0.3.3/src/various_api_tools/validators/__init__.py

@@ -0,0 +1 @@
+"""Module for various API validators."""

various_api_tools-0.3.3/src/various_api_tools/validators/pydantic.py

@@ -0,0 +1,221 @@
+"""Module for custom Pydantic validators with user-friendly error messages.
+
+Provides a class with methods to validate various types of input data,
+raising PydanticCustomError with predefined error descriptions.
+"""
+
+from decimal import Decimal
+from typing import Any
+
+from pydantic import EmailStr
+from pydantic_core._pydantic_core import PydanticCustomError
+
+from ..error_maps.pydantic import PYDANTIC_ERROR_TYPES
+
+MIN_LATITUDE = -90.0
+MAX_LATITUDE = 90.0
+MIN_LONGITUDE = -180.0
+MAX_LONGITUDE = 180.0
+
+
+class PydanticValidator:
+    """A class that provides custom validation methods for Pydantic models.
+
+    These methods are designed to raise PydanticCustomError with specific error codes
+    and human-readable error messages for better end-user experience.
+    """
+
+    error_types = PYDANTIC_ERROR_TYPES
+
+    @classmethod
+    def strip_validator(cls, value: str) -> str:
+        """Strip whitespace from both ends of a string.
+
+        Args:
+            value: Input string to be stripped.
+
+        Returns:
+            The stripped string.
+
+        Example:
+            ```python
+            print(PydanticValidator.strip_validator("  test  "))
+            #> "test"
+            ```
+
+        """
+        return value.strip()
+
+    @classmethod
+    def optional_string_validator(cls, value: Any | None) -> str | None:  # noqa: ANN401
+        """Validate and strips an optional string value.
+
+        Args:
+            value: Input value to be validated.
+
+        Returns:
+            A stripped string or None if the value is empty.
+
+        Raises:
+            PydanticCustomError: If the value is not a string.
+
+        Example:
+            ```python
+            print(PydanticValidator.optional_string_validator("  test  "))
+            #> "test"
+
+            print(PydanticValidator.optional_string_validator(""))
+            #> None
+
+            print(PydanticValidator.optional_string_validator(123))
+            #> Traceback (most recent call last):
+            #> ...
+            #> PydanticCustomError: 'string_type'
+            ```
+
+        """
+        if value is not None:
+            if not isinstance(value, str):
+                raise PydanticCustomError("string_type", cls.error_types["string_type"])
+
+            value = cls.strip_validator(value=value)
+            if value == "":
+                value = None
+
+        return value
+
+    @classmethod
+    def email_validator(cls, value: str) -> EmailStr | None:
+        """Validate an email address format.
+
+        Args:
+            value: Input string to be validated as an email.
+
+        Returns:
+            Validated EmailStr object or None if input is invalid.
+
+        Raises:
+            PydanticCustomError: If the email format is incorrect.
+
+        Example:
+            ```python
+            print(PydanticValidator.email_validator("test@example.com"))
+            #> EmailStr('test@example.com')
+
+            print(PydanticValidator.email_validator("invalid-email"))
+            #> Traceback (most recent call last):
+            #> ...
+            #> PydanticCustomError: 'incorrect_email'
+            ```
+
+        """
+        email_str: EmailStr | None = None
+        stripped_value: str | None = cls.optional_string_validator(value=value)
+
+        if stripped_value is not None:
+            try:
+                email_str = EmailStr._validate(stripped_value)  # noqa: SLF001
+            except ValueError as exc:
+                raise PydanticCustomError(
+                    "incorrect_email",
+                    cls.error_types["incorrect_email"],
+                ) from exc
+
+        return email_str
+
+    @classmethod
+    def latitude_validator(cls, value: Decimal) -> Decimal:
+        """Validate that a value is a valid geographic latitude.
+
+        Args:
+            value: Input Decimal to be validated.
+
+        Returns:
+            The validated Decimal value.
+
+        Raises:
+            PydanticCustomError: If the value is not in the range [-90.0, 90.0].
+
+        Example:
+            ```python
+            print(PydanticValidator.latitude_validator(Decimal("45.0")))
+            #> Decimal('45.0')
+
+            print(PydanticValidator.latitude_validator(Decimal("100.0")))
+            #> Traceback (most recent call last):
+            #> ...
+            #> PydanticCustomError: 'incorrect_latitude'
+            ```
+
+        """
+        if not MIN_LATITUDE <= value <= MAX_LATITUDE:
+            raise PydanticCustomError(
+                "incorrect_latitude",
+                cls.error_types["incorrect_latitude"],
+            )
+        return value
+
+    @classmethod
+    def longitude_validator(cls, value: Decimal) -> Decimal:
+        """Validate that a value is a valid geographic longitude.
+
+        Args:
+            value: Input Decimal to be validated.
+
+        Returns:
+            The validated Decimal value.
+
+        Raises:
+            PydanticCustomError: If the value is not in the range [-180.0, 180.0].
+
+        Example:
+            ```python
+            print(PydanticValidator.longitude_validator(Decimal("90.0")))
+            #> Decimal('90.0')
+
+            print(PydanticValidator.longitude_validator(Decimal("200.0")))
+            #> Traceback (most recent call last):
+            #> ...
+            #> PydanticCustomError: 'incorrect_longitude'
+            ```
+
+        """
+        if not MIN_LONGITUDE <= value <= MAX_LONGITUDE:
+            raise PydanticCustomError(
+                "incorrect_longitude",
+                cls.error_types["incorrect_longitude"],
+            )
+        return value
+
+    @classmethod
+    def validate_required_field(cls, value: Any | None) -> Any:  # noqa: ANN401
+        """Validate that a field is not missing in update models.
+
+        Args:
+            value: Input value to be validated.
+
+        Returns:
+            The original value if it's valid.
+
+        Raises:
+            PydanticCustomError: If the value is None or empty string.
+
+        Example:
+            ```python
+            print(PydanticValidator.validate_required_field("test"))
+            #> "test"
+
+            print(PydanticValidator.validate_required_field(None))
+            #> Traceback (most recent call last):
+            #> ...
+            #> PydanticCustomError: 'missing'
+            ```
+
+        """
+        if isinstance(value, str):
+            value = cls.optional_string_validator(value=value)
+
+        if value is None:
+            raise PydanticCustomError("missing", cls.error_types["missing"])
+
+        return value

various_api_tools-0.3.3/tests/validators/test_pydantic.py

@@ -0,0 +1,120 @@
+from decimal import Decimal
+from typing import Any
+
+import pytest
+from pydantic import EmailStr
+from pydantic_core._pydantic_core import PydanticCustomError
+
+from src.various_api_tools.validators.pydantic import PydanticValidator
+
+
+class TestPydanticValidator:
+    @pytest.mark.parametrize(
+        "input_value, expected_output",
+        [
+            ("  test  ", "test"),
+            ("", ""),
+            ("   ", ""),
+        ],
+    )
+    def test_strip_validator(self, input_value: str, expected_output: str):
+        result = PydanticValidator.strip_validator(input_value)
+        assert result == expected_output
+
+    @pytest.mark.parametrize(
+        "input_value, expected_output, is_raised",
+        [
+            ("  test  ", "test", False),
+            ("", None, False),
+            (123, None, True),
+        ],
+    )
+    def test_optional_string_validator(
+        self,
+        input_value: Any,
+        expected_output: str | None,
+        is_raised: bool,
+    ):
+        if is_raised:
+            with pytest.raises(Exception):
+                PydanticValidator.optional_string_validator(input_value)
+        else:
+            result = PydanticValidator.optional_string_validator(input_value)
+            assert result == expected_output
+
+    @pytest.mark.parametrize(
+        "input_value, expected_output, is_raised",
+        [
+            ("test@example.com", EmailStr._validate("test@example.com"), False),
+            (None, None, False),
+            ("invalid-email", None, True),
+        ],
+    )
+    def test_email_validator(
+        self, input_value: Any, expected_output: EmailStr | None, is_raised: bool,
+    ):
+        if is_raised:
+            with pytest.raises(Exception):
+                PydanticValidator.email_validator(input_value)
+        else:
+            result = PydanticValidator.email_validator(input_value)
+            assert result == expected_output
+
+    @pytest.mark.parametrize(
+        "input_value, expected_output, is_raised",
+        [
+            (Decimal("45.0"), Decimal("45.0"), False),
+            (Decimal("90.0"), Decimal("90.0"), False),
+            (Decimal("-90.0"), Decimal("-90.0"), False),
+            (Decimal("100.0"), None, True),
+        ],
+    )
+    def test_latitude_validator(
+        self, input_value: Decimal, expected_output: Decimal | None, is_raised: bool,
+    ):
+        if is_raised:
+            with pytest.raises(Exception):
+                PydanticValidator.latitude_validator(input_value)
+        else:
+            result = PydanticValidator.latitude_validator(input_value)
+            assert result == expected_output
+
+    @pytest.mark.parametrize(
+        "input_value, expected_output, is_raised",
+        [
+            (Decimal("90.0"), Decimal("90.0"), False),
+            (Decimal("-180.0"), Decimal("-180.0"), False),
+            (Decimal("180.0"), Decimal("180.0"), False),
+            (Decimal("200.0"), None, True),
+        ],
+    )
+    def test_longitude_validator(
+        self, input_value: Decimal, expected_output: Decimal | None, is_raised: bool,
+    ):
+        if is_raised:
+            with pytest.raises(Exception):
+                PydanticValidator.longitude_validator(input_value)
+        else:
+            result = PydanticValidator.longitude_validator(input_value)
+            assert result == expected_output
+
+    @pytest.mark.parametrize(
+        "input_value, expected_output, is_raised",
+        [
+            ("test", "test", False),
+            (None, pytest.raises(PydanticCustomError), True),
+            ("", pytest.raises(PydanticCustomError), True),
+        ],
+    )
+    def test_validate_required_field(
+        self,
+        input_value: Any,
+        expected_output: Any,
+        is_raised: bool,
+    ):
+        if is_raised:
+            with pytest.raises(Exception):
+                PydanticValidator.validate_required_field(input_value)
+        else:
+            result = PydanticValidator.validate_required_field(input_value)
+            assert result == expected_output