various-api-tools 0.2.1__py3-none-any.whl

various_api_tools/__init__.py

@@ -0,0 +1,11 @@
+"""A package for various API utility tools.
+
+Including JSON and Pydantic error translators.
+"""
+from .translators.json import DecodeErrorTranslator
+from .translators.pydantic import ValidationErrorTranslator
+
+__all__ = (
+    "DecodeErrorTranslator",
+    "ValidationErrorTranslator",
+)

various_api_tools/translators/__init__.py

@@ -0,0 +1,5 @@
+"""Module for importing and exporting JSON and Pydantic error translators.
+
+This module provides access to two utility classes that translate common
+validation and parsing errors into user-friendly Russian messages.
+"""

various_api_tools/translators/json.py

@@ -0,0 +1,80 @@
+"""Module for translating JSON decoding errors into user-friendly Russian messages.
+
+This module provides a utility class that converts Python's `JSONDecodeError`
+exceptions into more descriptive and readable error messages in Russian.
+It is useful for improving the end-user experience when parsing JSON data.
+
+"""
+
+from json import JSONDecodeError
+from typing import Final
+
+BASE_JSON_ERROR_MESSAGE: Final[str] = "Ошибка конвертации в формате JSON.\n"
+
+
+class DecodeErrorTranslator:
+    """Translates JSONDecodeError messages into user-friendly Russian descriptions.
+
+    This class provides a method to convert Python's JSONDecodeError exceptions
+    into more readable error messages for end users.
+
+    """
+
+    @classmethod
+    def translate(
+        cls,
+        error: JSONDecodeError,
+        *,
+        msg: str = BASE_JSON_ERROR_MESSAGE,
+        line_number: int | None = None,
+    ) -> str:
+        """Translate a JSONDecodeError into a human-readable message in Russian.
+
+        Args:
+            error: The JSONDecodeError instance to translate.
+            msg: Optional base message to prepend. Defaults to BASE_JSON_ERROR_MESSAGE.
+            line_number: Optional line number for better context.
+
+        Returns:
+            A string containing the translated error message(position and description).
+
+        Raises:
+            TypeError: If 'error' is not an instance of JSONDecodeError.
+
+        Example:
+            ```python
+            try:
+                json.loads('{"name": "Alice",}')
+            except JSONDecodeError as e:
+                print(DecodeErrorTranslator.translate(e))
+
+            #> Ошибка конвертации в формате JSON.
+            #> Позиция: 16.
+            #> Описание: не правильно используются двойные кавычки.
+            ```
+
+        """
+        if line_number is not None:
+            msg += f"Строка: {line_number}, позиция {error.pos}.\n"
+        else:
+            msg += f"Позиция: {error.pos}.\n"
+        exc_msg = error.msg
+
+        if "Expecting" in exc_msg and "delimiter" in exc_msg:
+            msg += "Описание: ожидается разделитель."
+        elif "Expecting property name enclosed in double quotes" in exc_msg:
+            msg += "Описание: не правильно используются двойные кавычки."
+        elif "Expecting value" in exc_msg:
+            msg += "Описание: ожидается значение."
+        elif "Extra data" in exc_msg:
+            msg += "Описание: обнаружены дополнительные данные."
+        elif "Invalid" in exc_msg and "escape" in exc_msg:
+            msg += "Описание: обнаружены недопустимые экранирующие символы."
+        elif "Invalid control character at" in exc_msg:
+            msg += "Описание: обнаружен неэкранированный контрольный символ."
+        elif "Unterminated string starting at" in exc_msg:
+            msg += "Описание: не правильно заверена закрывающая кавычка."
+        else:
+            msg += "Описание: неизвестная ошибка."
+
+        return msg

various_api_tools/translators/pydantic.py

@@ -0,0 +1,130 @@
+"""Module for translating Pydantic validation errors into Russian messages.
+
+This module provides a utility class to convert Pydantic error details into
+descriptive error messages in Russian, suitable for end-user feedback.
+
+"""
+
+from collections.abc import Sequence
+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": "Некорректный тип данных. Ожидается список.",
+}
+
+DEFAULT_LOCATION_PREFIX: Final[str] = "Поле"
+UNKNOWN_ERROR_TYPE: Final[str] = "Неизвестная ошибка"
+
+
+class ValidationErrorTranslator:
+    """Translate Pydantic validation errors into human-readable Russian messages.
+
+    This class provides a method to translate a sequence of Pydantic error details
+    into a formatted string with location, type and input information.
+
+    """
+
+    @classmethod
+    def get_str_pydantic_loc(cls, loc: tuple[str]) -> str:
+        """Convert a Pydantic location tuple into a dot-separated string.
+
+        Args:
+            loc: A tuple representing the field path in the model.
+
+        Returns:
+            A string representation of the field path.
+
+        Example:
+            ```python
+            print(ValidationErrorTranslator.get_str_pydantic_loc(("user", "name")))
+            #> "user.name"
+            ```
+
+        """
+        return ".".join([str(loc_value) for loc_value in loc])
+
+    @classmethod
+    def translate(cls, errors: Sequence[ErrorDetails]) -> str:
+        """Translate a list of Pydantic error details into a human-readable message.
+
+        Args:
+            errors: A sequence of Pydantic ErrorDetails objects.
+
+        Returns:
+            A formatted string containing all translated errors.
+
+        Example:
+           ```python
+           class Model(BaseModel):
+               email: str
+
+           try:
+               Model(email=1)
+           except ValidationError as exc:
+               print(ValidationErrorTranslator.translate(exc.errors())
+
+           #> Поле: "email". Ошибка: "Невалидное строковое значение(str)";
+           ```
+
+        """
+        formatted_errors: list[str] = []
+        for error in errors:
+            error_str: str = ""
+
+            location_part: str = ""
+            type_part: str = ""
+            input_part: str = ""
+
+            if "loc" in error:
+                prefix: str = DEFAULT_LOCATION_PREFIX
+                if error["loc"][0] == "query":
+                    prefix = "Параметр запроса"
+                location_part = (
+                    f'{prefix}: "{cls.get_str_pydantic_loc(loc=error["loc"])}"'
+                )
+
+            if "type" in error:
+                msg = pydantic_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:
+                input_part = f'заполнено неверно: "{error["input"]!r}"'
+
+            if input_part != "":
+                error_str = f"{location_part} {input_part}. {type_part};"
+            else:
+                error_str = f"{location_part}. {type_part};"
+
+            formatted_errors.append(error_str)
+
+        return "\n".join(formatted_errors)

various_api_tools-0.2.1.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.1
+Name: various-api-tools
+Version: 0.2.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
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+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
+Description-Content-Type: text/markdown
+
+# various_api_tools
+
+A lightweight utility package for common API-related tasks in Python, including JSON and Pydantic error translators that provide user-friendly Russian messages.
+
+---
+
+## 📦 Features
+
+- ✅ **JSON Error Translator** – Translates `JSONDecodeError` into clear Russian messages.
+- ✅ **Pydantic Validation Error Translator** – Converts Pydantic validation errors into human-readable Russian strings.
+- ✅ **Easy to integrate** – Designed for use in web APIs and data validation pipelines.
+
+---
+
+## 🐍 Installation
+
+Install using pip from source or a private repository:
+
+```bash
+pip install various_api_tools
+```
+
+## 🧪 Basic Usage
+
+### Translate JSON Decode Errors
+
+```python
+import json
+from various_api_tools.translators.json import DecodeErrorTranslator
+
+try:
+    json.loads('{"name": "Alice",}')
+except json.JSONDecodeError as e:
+    print(DecodeErrorTranslator.translate(e))
+
+# Output:
+# Ошибка конвертации в формате JSON.
+# Позиция: 16.
+# Описание: не правильно используются двойные кавычки.
+```
+
+---
+
+### Translate Pydantic Validation Errors
+
+```python
+from pydantic import BaseModel, ValidationError
+from various_api_tools.translators.pydantic import ValidationErrorTranslator
+
+class User(BaseModel):
+    email: str
+
+try:
+    User(email=123)
+except ValidationError as e:
+    print(ValidationErrorTranslator.translate(e.errors()))
+
+# Output:
+# Поле: "email". Ошибка: "Невалидное строковое значение(str)";
+```
+
+---
+
+## 📄 License
+
+MIT License — feel free to use it in any project! 🎉
+
+---
+
+## 🧑‍💻 Made with ❤️ by [@dkurchigin](https://gitverse.ru/dkurchigin)
+
+Have questions? Open an issue or contribute to the repo!
+
+
+## 🐙 GITVERSE
+
+
+🔗 [https://gitverse.ru/dkurchigin/various-api-tools](https://gitverse.ru/dkurchigin/various-api-tools)

various_api_tools-0.2.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+various_api_tools-0.2.1.dist-info/METADATA,sha256=uFPuvWCUbIR7caXA1sLgwYf2xRQOhy18asGOW4Ug9wQ,2899
+various_api_tools-0.2.1.dist-info/WHEEL,sha256=9P2ygRxDrTJz3gsagc0Z96ukrxjr-LFBGOgv3AuKlCA,90
+various_api_tools-0.2.1.dist-info/entry_points.txt,sha256=6OYgBcLyFCUgeqLgnvMyOJxPCWzgy7se4rLPKtNonMs,34
+various_api_tools/__init__.py,sha256=-NZqqXsqmRrPlaPRLX-1v1PuVaXZXU69CP0cl6rBd-c,285
+various_api_tools/translators/__init__.py,sha256=v2bJFou-sb1R7PhkPOSJ2de8XSEyvft_X73oknoaMok,220
+various_api_tools/translators/json.py,sha256=iMLW0odm1pj2hR3YSkPv2y545zB08nLTSYILP0GsPBk,3363
+various_api_tools/translators/pydantic.py,sha256=lUKqRMFQlslqG5IRxowrEvg8pX3RMNiB5mJbWj2n4Zs,5826
+various_api_tools-0.2.1.dist-info/RECORD,,

various_api_tools-0.2.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.4.5)
+Root-Is-Purelib: true
+Tag: py3-none-any

various_api_tools-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+
+[gui_scripts]
+