Request Rule Decorators

Библиотека для валидации и парсинга HTTP-ответов с использованием декораторов.

Установка

pip install -e .

Для разработки с тестами:

pip install -e ".[dev]"

Быстрый старт

from request_rule_decorators import ResponseHandler, Validator, Parser

@ResponseHandler.handlers(
    Validator.STATUS_CODE().whitelist([200, 201]),
    Validator.CONTENT_TYPE().equals("application/json"),
    Validator.JSON("$.username").whitelist().values(["john_doe"]),
    Validator.JSON("$.age").range(18, 100),
    Parser.JSON("$.age").save_to("parsed_age"),
)
async def my_function():
    # Ваша функция, возвращающая response объект
    return response

result = await my_function()
# result.response - оригинальный response
# result.valid.ERRORS - список ошибок валидации
# result.valid.PARSED - распарсенные данные
# result.is_valid() - проверка валидации

Документация

Подробная документация доступна в файле DOCS.md

Запуск тестов

pytest tests/

Запуск демонстрационного примера

python demo.py

Структура проекта

request_rule_decorators/ - основной пакет библиотеки
- dto.py - DTO классы (ValidationError, ValidationData, WithValid)
- decorator.py - декоратор ResponseHandler
- rules.py - фабрика правил (Validator, Parser)
- exceptions.py - кастомные исключения
- validators/ - валидаторы (JSON, Headers, StatusCode, ContentType, HTML)
- parsers/ - парсеры (JSON, HTML)
tests/ - тесты
demo.py - демонстрационный файл
DOCS.md - подробная документация

Документация библиотеки request-rule-decorators

Введение

Библиотека request-rule-decorators предназначена для валидации и парсинга HTTP-ответов с использованием декораторов. Она позволяет легко проверять различные части ответа (JSON, заголовки, статус-код, Content-Type, HTML) и извлекать данные с помощью простого и понятного API.

Быстрый старт

from request_rule_decorators import ResponseHandler, Validator, Parser

@ResponseHandler.handlers(
    Validator.STATUS_CODE().whitelist([200, 201]),
    Validator.CONTENT_TYPE().equals("application/json"),
    Validator.JSON("$.username").whitelist().values(["john_doe", "jane_doe"]),
    Parser.JSON("$.age").save_to("parsed_age"),
)
async def my_function():
    # Ваша функция, возвращающая response объект
    return response

result = await my_function()
print(result.is_valid())  # True/False
print(result.valid.ERRORS)  # Список ошибок
print(result.valid.PARSED)  # Распарсенные данные

Валидаторы

JSONValidator

Валидатор для проверки JSON данных с использованием JSONPath выражений.

Создание:

Validator.JSON(json_path: str, error_key: str | None = None) -> JSONValidator

Параметры:

json_path - JSONPath выражение для извлечения значения (например, "$.username", "$[*].id")
error_key - Опциональный ключ ошибки для идентификации конкретного правила

Методы валидации

`blacklist() -> Blacklist`

Возвращает объект Blacklist для создания правил черного списка.

Пример:

Validator.JSON("$.status").blacklist().values(["error", "failed"])

`whitelist() -> Whitelist`

Возвращает объект Whitelist для создания правил белого списка.

Пример:

Validator.JSON("$.status").whitelist().values(["active", "pending"])

`range(min_val: Union[int, float], max_val: Union[int, float]) -> JSONValidator`

Проверяет, что значение находится в заданном диапазоне.

Параметры:

min_val - Минимальное значение
max_val - Максимальное значение

Пример:

Validator.JSON("$.age").range(18, 100)

`regex(pattern: str) -> JSONValidator`

Проверяет значение по регулярному выражению.

Параметры:

pattern - Регулярное выражение

Пример:

Validator.JSON("$.email").regex(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$")

`exists() -> JSONValidator`

Проверяет существование пути в JSON.

Пример:

Validator.JSON("$.username").exists()

`type(expected_type: Type) -> JSONValidator`

Проверяет тип значения.

Параметры:

expected_type - Ожидаемый тип (например, int, str, dict)

Пример:

Validator.JSON("$.age").type(int)

Примеры использования

# Проверка нескольких правил
Validator.JSON("$.user.age").range(18, 100).type(int)

# Проверка массива
Validator.JSON("$[*].id").type(int).range(1, 100)

# Проверка с ERROR_KEY
Validator.JSON("$.status", error_key="BAN").whitelist().values(["active"])

HeadersValidator

Валидатор для проверки HTTP заголовков.

Создание:

Validator.HEADERS(error_key: str | None = None) -> HeadersValidator

Параметры:

error_key - Опциональный ключ ошибки для идентификации конкретного правила

Методы валидации

`has_key(key: str) -> HeadersValidator`

Проверяет наличие ключа в заголовках.

Параметры:

key - Имя заголовка для проверки

Пример:

Validator.HEADERS().has_key("Content-Type")

`missing_key(key: str) -> HeadersValidator`

Проверяет отсутствие ключа в заголовках.

Параметры:

key - Имя заголовка, который должен отсутствовать

Пример:

Validator.HEADERS().missing_key("X-Secret-Header")

`blacklist(key: str, values: List[str]) -> HeadersValidator`

Проверяет, что значение ключа не в черном списке.

Параметры:

key - Имя заголовка
values - Список запрещенных значений

Пример:

Validator.HEADERS().blacklist("X-Status", ["error", "failed"])

`whitelist(key: str, values: List[str]) -> HeadersValidator`

Проверяет, что значение ключа в белом списке.

Параметры:

key - Имя заголовка
values - Список разрешенных значений

Пример:

Validator.HEADERS().whitelist("Content-Type", ["application/json", "text/html"])

`regex(key: str, pattern: str) -> HeadersValidator`

Проверяет значение ключа по регулярному выражению.

Параметры:

key - Имя заголовка
pattern - Регулярное выражение

Пример:

Validator.HEADERS().regex("Content-Type", r"^application/.*$")

Примеры использования

# Проверка наличия нескольких заголовков
Validator.HEADERS().has_key("Content-Type").has_key("Authorization")

# Комбинация проверок
Validator.HEADERS().has_key("Content-Type").whitelist("Content-Type", ["application/json"])

StatusCodeValidator

Валидатор для проверки HTTP статус-кода.

Создание:

Validator.STATUS_CODE(error_key: str | None = None) -> StatusCodeValidator

Параметры:

error_key - Опциональный ключ ошибки для идентификации конкретного правила

Методы валидации

`blacklist(codes: List[int]) -> StatusCodeValidator`

Проверяет, что статус-код не в черном списке.

Параметры:

codes - Список запрещенных статус-кодов

Пример:

Validator.STATUS_CODE().blacklist([400, 401, 403, 404, 500])

`whitelist(codes: List[int]) -> StatusCodeValidator`

Проверяет, что статус-код в белом списке.

Параметры:

codes - Список разрешенных статус-кодов

Пример:

Validator.STATUS_CODE().whitelist([200, 201, 204])

Примеры использования

# Только успешные коды
Validator.STATUS_CODE().whitelist([200, 201, 202, 204])

# Запрет ошибок клиента и сервера
Validator.STATUS_CODE().blacklist([400, 401, 403, 404, 500, 502, 503, 504])

ContentTypeValidator

Валидатор для проверки заголовка Content-Type с поддержкой Literal типов для автодополнения в IDE.

Создание:

Validator.CONTENT_TYPE(error_key: str | None = None) -> ContentTypeValidator

Параметры:

error_key - Опциональный ключ ошибки для идентификации конкретного правила

Методы валидации

`blacklist() -> Blacklist`

Возвращает объект Blacklist для создания правил черного списка типов контента.

Пример:

Validator.CONTENT_TYPE().blacklist().values(["text/plain", "application/xml"])

`whitelist() -> Whitelist`

Возвращает объект Whitelist для создания правил белого списка типов контента.

Пример:

Validator.CONTENT_TYPE().whitelist().values(["application/json", "text/html"])

`equals(content_type: Union[ContentType, str]) -> ContentTypeValidator`

Проверяет, что Content-Type точно равен указанному значению.

Параметры:

content_type - Тип контента (с автодополнением в IDE: "application/json", "text/html" и т.д.)

Пример:

Validator.CONTENT_TYPE().equals("application/json")

Поддерживаемые типы контента

Библиотека поддерживает следующие типы контента с автодополнением в IDE:

Application:

application/json, application/xml, application/pdf, application/zip, application/javascript и др.

Text:

text/plain, text/html, text/css, text/javascript, text/csv, text/markdown и др.

Image:

image/jpeg, image/png, image/gif, image/svg+xml, image/webp и др.

Audio/Video:

audio/mpeg, video/mp4, video/webm и др.

Font:

font/woff, font/woff2, font/ttf и др.

Multipart:

multipart/form-data, multipart/byteranges

Примеры использования

# Точное совпадение (с автодополнением)
Validator.CONTENT_TYPE().equals("application/json")

# Белый список типов
Validator.CONTENT_TYPE().whitelist().values(["application/json", "text/html"])

# Черный список типов
Validator.CONTENT_TYPE().blacklist().values(["text/plain"])

HTMLValidator

Валидатор для проверки HTML данных с использованием XPath выражений.

Создание:

Validator.HTML(xpath: str, error_key: str | None = None) -> HTMLValidator

Параметры:

xpath - XPath выражение для извлечения значения (например, "//div[@class='content']", "//a/@href")
error_key - Опциональный ключ ошибки для идентификации конкретного правила

Методы валидации

Все методы аналогичны JSONValidator:

blacklist() -> Blacklist - Черный список значений
whitelist() -> Whitelist - Белый список значений
range(min_val, max_val) - Проверка диапазона
regex(pattern) - Проверка по регулярному выражению
exists() - Проверка существования элемента
type(expected_type) - Проверка типа

Примеры использования

# Проверка текста элемента
Validator.HTML("//div[@class='status']/text()").whitelist().values(["active", "pending"])

# Проверка атрибута
Validator.HTML("//a/@href").regex(r"^https?://.*$")

# Проверка количества элементов
Validator.HTML("//div[@class='item']").exists()

Парсеры

JSONParser

Парсер для извлечения и обработки JSON данных с использованием JSONPath выражений.

Создание:

Parser.JSON(json_path: str) -> JSONParser

Параметры:

json_path - JSONPath выражение для извлечения значения

Методы парсинга

`save_to(key: str) -> JSONParser`

Указывает ключ для сохранения результата в словарь PARSED.

Параметры:

key - Ключ для сохранения результата

Пример:

Parser.JSON("$.age").save_to("parsed_age")

`regex(pattern: str) -> JSONParser`

Применяет регулярное выражение к значению.

Параметры:

pattern - Регулярное выражение

Пример:

Parser.JSON("$.email").regex(r"^([a-zA-Z0-9._%+-]+)@")

`sum() -> JSONParser`

Суммирует числовые значения (для списков чисел и списков словарей).

Пример:

Parser.JSON("$.numbers").sum()
Parser.JSON("$.data[*]").extract_field("traffic").sum()

`average() -> JSONParser`

Вычисляет среднее значение (для списков чисел и списков словарей).

Пример:

Parser.JSON("$.scores").average()

`max() -> JSONParser`

Находит максимальное значение (для списков чисел и списков словарей).

Пример:

Parser.JSON("$.prices").max()

`min() -> JSONParser`

Находит минимальное значение (для списков чисел и списков словарей).

Пример:

Parser.JSON("$.prices").min()

`count() -> JSONParser`

Подсчитывает количество элементов (для списков).

Пример:

Parser.JSON("$[*].id").count()

`extract_field(field: str) -> JSONParser`

Извлекает поле из списка словарей.

Параметры:

field - Имя поля для извлечения

Пример:

Parser.JSON("$.data[*]").extract_field("traffic")

Примеры использования

# Простое извлечение
Parser.JSON("$.username").save_to("username")

# Извлечение и суммирование
Parser.JSON("$.data[*].traffic").extract_field("traffic").sum().save_to("total_traffic")

# Подсчет элементов
Parser.JSON("$[*].id").count().save_to("user_count")

# Комбинация операций
Parser.JSON("$.items[*].price").max().save_to("max_price")

HTMLParser

Парсер для извлечения и обработки HTML данных с использованием XPath выражений.

Создание:

Parser.HTML(xpath: str) -> HTMLParser

Параметры:

xpath - XPath выражение для извлечения значения

Методы парсинга

Все методы аналогичны JSONParser:

save_to(key) - Сохранение результата
regex(pattern) - Применение regex
sum() - Суммирование
average() - Среднее значение
max() - Максимум
min() - Минимум
count() - Подсчет элементов
extract_field(field) - Извлечение поля из словарей

Примеры использования

# Извлечение текста
Parser.HTML("//div[@class='title']/text()").save_to("title")

# Извлечение всех ссылок
Parser.HTML("//a/@href").save_to("links")

# Подсчет элементов
Parser.HTML("//div[@class='item']").count().save_to("item_count")

Blacklist и Whitelist

Объекты Blacklist и Whitelist используются для создания правил валидации с различными типами проверок.

Blacklist

Объект для создания правил черного списка.

Методы

`values(values: List[Any]) -> BaseValidator`

Проверяет, что значение не в черном списке значений.

Параметры:

values - Список запрещенных значений

Пример:

Validator.JSON("$.status").blacklist().values(["error", "failed"])

`words(words: List[str]) -> BaseValidator`

Проверяет, что строка не содержит ни одного слова из черного списка.

Параметры:

words - Список запрещенных слов

Пример:

Validator.JSON("$.description").blacklist().words(["spam", "forbidden"])

`regex(pattern: str) -> BaseValidator`

Проверяет, что значение не соответствует регулярному выражению.

Параметры:

pattern - Запрещенный regex паттерн

Пример:

Validator.JSON("$.url").blacklist().regex(r".*spam.*")

Whitelist

Объект для создания правил белого списка.

Методы

`values(values: List[Any]) -> BaseValidator`

Проверяет, что значение в белом списке значений.

Параметры:

values - Список разрешенных значений

Пример:

Validator.JSON("$.status").whitelist().values(["active", "pending"])

`words(words: List[str]) -> BaseValidator`

Проверяет, что строка содержит хотя бы одно слово из белого списка.

Параметры:

words - Список разрешенных слов

Пример:

Validator.JSON("$.category").whitelist().words(["tech", "science"])

`regex(pattern: str) -> BaseValidator`

Проверяет, что значение соответствует регулярному выражению.

Параметры:

pattern - Требуемый regex паттерн

Пример:

Validator.JSON("$.email").whitelist().regex(r"^.*@example\.com$")

Примеры использования

Пример 1: Валидация API ответа

@ResponseHandler.handlers(
    Validator.STATUS_CODE().whitelist([200, 201]),
    Validator.CONTENT_TYPE().equals("application/json"),
    Validator.JSON("$.status").whitelist().values(["success"]),
    Validator.JSON("$.data[*].id").type(int).range(1, 1000),
    Validator.JSON("$.data[*].email").regex(r"^[^@]+@[^@]+\.[^@]+$"),
)
async def fetch_users():
    async with httpx.AsyncClient() as client:
        response = await client.get("https://api.example.com/users")
        return response

result = await fetch_users()
if result.is_valid():
    print("Валидация пройдена!")
else:
    for error in result.valid.ERRORS:
        print(f"Ошибка: {error.message}")

Пример 2: Парсинг данных

@ResponseHandler.handlers(
    Validator.STATUS_CODE().whitelist([200]),
    Parser.JSON("$[*].id").count().save_to("total_users"),
    Parser.JSON("$[*].age").average().save_to("avg_age"),
    Parser.JSON("$[*].salary").max().save_to("max_salary"),
    Parser.JSON("$[*].transactions[*]").extract_field("amount").sum().save_to("total_amount"),
)
async def analyze_data():
    # Ваша функция
    return response

result = await analyze_data()
print(f"Всего пользователей: {result.valid.PARSED['total_users']}")
print(f"Средний возраст: {result.valid.PARSED['avg_age']}")
print(f"Максимальная зарплата: {result.valid.PARSED['max_salary']}")
print(f"Общая сумма транзакций: {result.valid.PARSED['total_amount']}")

Пример 3: Использование ERROR_KEY

@ResponseHandler.handlers(
    Validator.STATUS_CODE().whitelist([200]),
    Validator.JSON("$.status", error_key="BAN").whitelist().values(["active"]),
    Validator.JSON("$.age", error_key="AGE_ERROR").range(18, 100),
)
async def check_user():
    return response

result = await check_user()

# Проверка конкретной ошибки
if result.has_error("BAN"):
    print("Пользователь забанен!")
if result.has_error("AGE_ERROR"):
    print("Ошибка возраста!")

Пример 4: Комплексная валидация

@ResponseHandler.handlers(
    # Статус и заголовки
    Validator.STATUS_CODE().whitelist([200, 201]),
    Validator.CONTENT_TYPE().equals("application/json"),
    Validator.HEADERS().has_key("X-Request-ID"),
    
    # Валидация JSON структуры
    Validator.JSON("$.data").exists(),
    Validator.JSON("$.data[*].id").type(int),
    Validator.JSON("$.data[*].name").exists(),
    Validator.JSON("$.data[*].email").regex(r"^[^@]+@[^@]+\.[^@]+$"),
    
    # Проверка на запрещенные слова
    Validator.JSON("$.data[*].description").blacklist().words(["spam", "forbidden"]),
    
    # Парсинг данных
    Parser.JSON("$.data[*].id").count().save_to("count"),
    Parser.JSON("$.data[*].score").average().save_to("avg_score"),
)
async def complex_validation():
    return response

Дополнительная информация

WithValid объект

Декоратор возвращает объект WithValid[T], который содержит:

response: T - Оригинальный response объект
valid: ValidationData - Данные валидации с ошибками и распарсенными данными

Методы

is_valid() -> bool - Проверяет, есть ли ошибки валидации
has_error(error_key: str) -> bool - Проверяет наличие конкретной ошибки по ERROR_KEY
__repr__() - Возвращает строковое представление со всеми ошибками

ValidationData

Объект содержит:

ACTION: Optional[str] - Действие (опционально)
ERRORS: List[ValidationError] - Список ошибок валидации
PARSED: Dict[str, Any] - Распарсенные данные
ATTEMPTS: int - Счетчик попыток

ValidationError

Каждая ошибка содержит:

rule_name: str - Имя правила, на котором произошла ошибка
error_key: Optional[str] - Ключ ошибки для идентификации
expected_values: List[Any] - Ожидаемые значения
received_values: List[Any] - Полученные значения
attempts: int - Количество попыток
max_attempts: int - Максимальное количество попыток
message: str - Сообщение об ошибке

Поддержка

Для вопросов и предложений создайте issue в репозитории проекта.

Metadata

Release files for request-rule-decorators 0.1.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for request-rule-decorators 0.1.2
File	Size	Uploaded
request_rule_decorators-0.1.2.tar.gz	35.9 kB	Jan 20, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for request-rule-decorators 0.1.2
File	Interpreter	ABI	Platform	Reset
request_rule_decorators-0.1.2-py3-none-any.whl 33.4 kB Jan 20, 2026	Python 3	none	any	Details

Total release size: 69.2 kB

Release files / request_rule_decorators-0.1.2.tar.gz

Download URL	request_rule_decorators-0.1.2.tar.gz
Size	35.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`9c8a2e0323b8ef97b2317b607bc299a29a50aed52a1cad5360aa4d8a9f34100f`
BLAKE2b-256 checksum How to use checksums	`f4bd958eeed5b5a3e0f21a690cef46642cdfceae83c0cf1dd6d0c4b01c2fd84e`
Upload date	Jan 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.0`

Release files / request_rule_decorators-0.1.2-py3-none-any.whl

Download URL	request_rule_decorators-0.1.2-py3-none-any.whl
Size	33.4 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`681413751e736bff0a199c591a29853df2d334406d6d6e67d6e671835d86f102`
BLAKE2b-256 checksum How to use checksums	`62b33c8c41f7b1ca170df18068c50cacf32b5f9b45bd8924d5e2b74d73332b02`
Upload date	Jan 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.0`

Release history Release notifications | RSS feed

This release

0.1.2 This release

Jan 20, 2026 2 release files

0.1.1

Dec 13, 2025 2 release files

0.1.0

Dec 13, 2025 2 release files