Metadata-Version: 2.4
Name: lalafo_api
Version: 0.2.0
Summary: Sync and async Python client for the public Lalafo.kg catalog API
Author: Umar
License-Expression: LicenseRef-Proprietary
Project-URL: Homepage, https://github.com/Umar151515/lalafo-api
Project-URL: Repository, https://github.com/Umar151515/lalafo-api
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx<1,>=0.27
Requires-Dist: pydantic<3,>=2.7
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: build<2,>=1; extra == "dev"
Requires-Dist: ruff<1,>=0.11; extra == "dev"
Provides-Extra: release
Requires-Dist: build<2,>=1; extra == "release"
Requires-Dist: twine<8,>=6; extra == "release"
Requires-Dist: packaging>=24.2; extra == "release"
Requires-Dist: tomli>=2; python_version < "3.11" and extra == "release"

# lalafo-api

Неофициальная Python-библиотека для публичного API [lalafo.kg](https://lalafo.kg/): синхронный и асинхронный клиенты, поиск по ссылке, динамические фильтры категорий и постраничная загрузка.

Python 3.10+, HTTPX, Pydantic 2. Установка из текущего проекта:

```bash
python -m pip install .
```

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

```python
from lalafo_api import LalafoClient, SearchRequest

with LalafoClient() as client:
    results = client.search_ads(q="iPhone 15", price_to=50000)
    for ad in results.items:
        print(ad.id, ad.title, ad.price, ad.currency)

    # Такой же поиск через явную модель запроса.
    request = SearchRequest(q="iPhone 15", price_to=50000, per_page=20)
    results = client.search_ads(request)
```

Каждый клиент владеет своей HTTP-сессией. Используйте `with` / `async with` или явно вызывайте `close()` / `aclose()`.

## Поиск по ссылке

Ссылка сайта может хранить модель, цвет и другие фильтры в самом пути. Клиент загружает страницу и читает запрос, который подготовил сервер Lalafo: категория, город и параметры сохраняются вместе с query string.

```python
from lalafo_api import LalafoClient

url = (
    "https://lalafo.kg/bishkek/"
    "mobilnye-telefony-i-aksessuary/mobilnye-telefony/"
    "apple-iphone/iphone-15/black-iphone?price[to]=50000&sort_by=newest"
)

with LalafoClient() as client:
    request = client.get_search_request_from_url(url)
    print(request.category_id, request.city_id, request.parameters)
    results = client.search_ads_from_url(url)
```

В проверенной ссылке категория — Apple iPhone, параметры — iPhone 15 и черный цвет. Для другого пути ID и параметры определяет сервер. Если структуру страницы нельзя распознать, клиент сообщает об ошибке: фильтры не должны незаметно исчезать.

Ссылки на объявления обрабатываются отдельно:

```python
with LalafoClient() as client:
    details = client.fetch_ad_from_url(
        "https://lalafo.kg/bishkek/ads/example-id-117606715"
    )
    if details.ad is not None:
        print(details.ad.title, details.ad.description)
```

Утилиты без сетевых запросов доступны из `lalafo_api.utils`: `parse_ad_url`, `parse_search_url`, `extract_next_data`, `search_params_from_next_data`, `build_search_url`. Полностью разрешить произвольные SEO-фильтры без данных сайта нельзя; для обычных ссылок используйте метод клиента.

## Фильтры категорий: цвет, память, модель и диапазоны

Библиотека получает актуальные фильтры выбранной категории. Жестко заданного общего словаря цветов нет: например, у категории всех телефонов и Apple у фильтра «Цвет» разные ID.

```python
from lalafo_api import LalafoClient

with LalafoClient() as client:
    request = client.build_search_request(
        category_id=1361,       # Apple iPhone, пример из текущего каталога
        city_id=103184,        # Бишкек
        price_to=50000,
        filters={
            "Модель": "iPhone 15",
            "Цвет": ["Черный", "Белый"],
            "Объем памяти": "128 ГБ",
            "Состояние аккумулятора, %": {"from": 90, "to": 100},
        },
    )
    results = client.search_ads(request)
```

Фильтр можно указать по точному названию, alias или ID; значение — по названию, alias или ID. Регистр и `е`/`ё` нормализуются. Несуществующее или неоднозначное значение вызывает ошибку с пояснением. Диапазоны передаются через `from` / `to`.

Узнать доступные значения:

```python
with LalafoClient() as client:
    catalog = client.get_params_filter(category_id=1361)
    for item in catalog.filters:
        print(item.id, item.name, item.alias, item.is_range)

    color = catalog.find_filter("Цвет")
    if color is not None:
        for value in color.values:
            print(value.id, value.value, value.alias)

    parameters = catalog.resolve_parameters({"Цвет": "Черный"})
```

Если ID уже известны, можно передать их напрямую:

```python
from lalafo_api import SearchRequest

request = SearchRequest(
    category_id=1361,
    parameters={
        "181": [16868],
        "1800": {"from": 90, "to": 100},
    },
)
print(request.to_query_params())
# ... parameters[181][0]=16868, parameters[1800][from]=90, ...
```

Новые параметры API, для которых еще нет отдельного поля модели, передавайте через `extra_params={"new_api_option": "value"}`. Нулевые цены и координаты, `False` и повторяющиеся query-параметры сохраняются при сериализации.

## Асинхронный клиент

Методы поиска, каталога, получения объявления и построения запроса имеют те же имена. Сетевые операции вызываются через `await`.

```python
import asyncio
from lalafo_api import AsyncLalafoClient

async def main():
    async with AsyncLalafoClient() as client:
        request = await client.build_search_request(
            category_id=1361,
            filters={"Цвет": "Черный"},
            price_to=50000,
        )
        results = await client.search_ads(request)
        for ad in results.items:
            print(ad.title, ad.price)

asyncio.run(main())
```

## Пагинация

Итераторы позволяют обрабатывать выдачу без загрузки всех результатов в память. Исходный `SearchRequest` не изменяется. Ошибка на следующей странице передается вызывающему коду.

```python
from lalafo_api import LalafoClient, SearchRequest

request = SearchRequest(category_id=1361, per_page=20)
with LalafoClient() as client:
    for page in client.iter_search_pages(request, max_pages=3):
        print(page.meta.currentPage, len(page.items))

    for ad in client.iter_ads(request, max_pages=3):
        print(ad.id, ad.title)

    # Для небольших выгрузок можно получить готовый список.
    ads = client.search_ads_all_pages(request, max_pages=3)
```

В асинхронном клиенте используйте `async for page in client.iter_search_pages(...)` и `async for ad in client.iter_ads(...)`. `search_ads_all_pages(...)` вызывается через `await`.

Сайт может добавлять продвигаемые карточки, поэтому число элементов не всегда совпадает с `per_page`. Переходы используют ссылки пагинации и метаданные API.

## Категории и объявления

```python
with LalafoClient() as client:
    tree = client.get_categories_tree()
    apple = tree.find_by_id(1361)
    phones = tree.find_by_name("телефон")
    all_categories = tree.flatten()
    path = tree.get_category_path(1361)

    details = client.get_ad_details(117606715)
    if details.ad is not None:
        for parameter in details.ad.params:
            print(parameter.name, parameter.value)
```

Также доступны `get_user_ads`, `get_related_ads`, `get_filters`, `get_feed_elements` и `get_user_status`.

## Поля ответов и изменения API

Поля ответов могут отсутствовать или содержать `null`: скалярные поля возвращают `None`, коллекции — пустые списки/словари. Проверяйте значение перед арифметикой и обращением к вложенным объектам. Новые свойства сервера сохраняются в моделях и доступны через `model_extra` / `model_dump()`. Новые строки перечислений, например тип фильтра, не приводят к падению всего ответа.

Входные модели остаются проверяемыми: отрицательная цена, страница 0, опечатка в имени аргумента или перевернутый диапазон считаются ошибками. Допустимость отсутствующих полей ответа не отменяет проверку неверных типов и поврежденной структуры.

## Сеть и ошибки

```python
from lalafo_api import ClientConfig, LalafoClient, APIError, RateLimitError

config = ClientConfig(
    timeout=20,
    max_retries=2,       # Дополнительные попытки после первого запроса
    retry_delay=1,
    language="ru_RU",
    headers={"User-Agent": "MyLalafoIntegration/1.0"},
)

with LalafoClient(config=config) as client:
    try:
        result = client.search_ads(q="iPhone")
    except RateLimitError as error:
        print("Лимит запросов:", error.retry_after)
    except APIError as error:
        print(error.status_code, error.message, error.url)
```

Базовый адрес настраивается через `ClientConfig.base_url`, адрес страниц — `website_url`. По умолчанию используется `https://lalafo.kg/api` с маршрутами сервисов `search`, `catalog`, `proxy/catalog`. Произвольный другой API должен поддерживать те же пути.

Исключения библиотеки: `APIError`, `NetworkError`, `ResponseValidationError`, `RateLimitError`, `AuthenticationError`, `NotFoundError`, `ValidationError`. Ошибки создания `SearchRequest`/`ClientConfig` — `pydantic.ValidationError`. HTTP-ошибка сохраняет статус и данные ответа; HTML вместо JSON также дает явную ошибку. Повторяемые сетевые ошибки и временные ответы сервера обрабатываются с ограничением числа попыток и учетом `Retry-After`.

## Публикация обновлений на PyPI

```powershell
python -m pip install -e ".[dev,release]"
python publish.py                    # Тесты, сборка, проверка архивов
python publish.py --upload           # Публикация текущей версии на PyPI
python publish.py --bump patch --upload  # Увеличить версию и опубликовать
```

Для TestPyPI добавьте `--repository testpypi`. Токен вводится в скрытом запросе Twine или берется из keyring / `TWINE_PASSWORD`. Без `--upload` команда только готовит архивы. Подробности — в [инструкции по публикации](docs/publishing.md).

## Проверка и миграция

```bash
python -m pip install -e ".[dev]"
python -m pytest
```

Основные тесты работают без сети через HTTPX MockTransport и фикстуры реальных структур. Подробности исследования сайта, проверенные маршруты, пример SEO-ссылки и ограничения — в [docs/api-research.md](docs/api-research.md).

Проверка на живом сайте запускается отдельно: `python scripts/smoke_live.py`.

При переходе со старой версии:

* Импортируйте из `lalafo_api`, как называется установленный пакет.
* Закрывайте клиенты через контекстный менеджер; общих глобальных HTTP-сессий больше нет.
* Учитывайте `None` у полей ответов. Неизвестные поля больше не теряются.
* `max_retries=0` означает один запрос без повторов.
* Ошибки URL и пагинации больше не скрываются за `None` или незаметно обрезанным списком.
* Для фильтров по названиям используйте `build_search_request`, чтобы получить ID из актуальной категории.

Это библиотека для внутреннего API сайта, публичного контракта стабильности у него нет. Набор доступных фильтров зависит от категории, города и текущего состояния сервера.
