lalafo-api 0.1.0__tar.gz

lalafo_api-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: lalafo_api
+Version: 0.1.0
+Summary: Библиотека для работы с API Lalafo
+Author: Umar
+License: Proprietary
+Project-URL: Homepage, https://github.com/Umar151515/lalafo-api
+Project-URL: Repository, https://github.com/Umar151515/lalafo-api
+Platform: any
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<1.0.0
+Requires-Dist: pydantic>=2.0
+
+# Документация Lalafo API
+
+Этот код был написан в крайне сжатые сроки (буквально за 2 дня). Изначально стоял выбор: потратить месяц на попытку написать «идеально» или быстро «навайбкодить» рабочее решение. Был выбран второй вариант, однако в дальнейшем была проведена работа над ошибками, чтобы исправить структуру и привести библиотеку к нормальной архитектуре.
+
+Библиотека предоставляет удобный интерфейс для взаимодействия с API Lalafo, поддерживая как синхронный, так и асинхронный режимы работы.
+
+Установка: pip install lalafo-api
+
+## Основные возможности
+* Синхронный (`LalafoClient`) и асинхронный (`AsyncLalafoClient`) клиенты.
+* Полное покрытие моделей данных (объявления, категории, фильтры, пользователи).
+* Удобный поиск с поддержкой пагинации и фильтров.
+* Инструменты для парсинга данных напрямую из URL сайта Lalafo.
+* Автоматическая обработка ошибок API.
+
+## Быстрый старт
+
+### Синхронный клиент
+```python
+from lalafo import LalafoClient, SearchRequest
+
+client = LalafoClient()
+
+# Поиск объявлений
+request = SearchRequest(q="iPhone 15", price_to=100000)
+results = client.search_ads(request)
+
+for item in results.items:
+    print(f"{item.title} - {item.price} {item.currency}")
+```
+
+### Асинхронный клиент
+```python
+import asyncio
+from lalafo import AsyncLalafoClient
+
+async def main():
+    client = AsyncLalafoClient()
+    ad = await client.get_ad_details(ad_id=12345678)
+    print(ad.ad.title)
+    print(ad.ad.description)
+
+asyncio.run(main())
+```
+
+## Архитектура библиотеки
+
+### 1. Клиенты (api/)
+Библиотека использует два основных класса:
+* **LalafoClient**: использует `httpx` для блокирующих запросов. Подходит для простых скриптов.
+* **AsyncLalafoClient**: использует асинхронный `httpx`. Рекомендуется для ботов и веб-приложений.
+
+Оба клиента поддерживают автоматические повторы запросов (retries) при таймаутах, которые настраиваются через `ClientConfig`.
+
+### 2. Конфигурация (ClientConfig)
+Вы можете настроить заголовки, версию приложения и параметры сети:
+```python
+from lalafo import ClientConfig, LalafoClient
+
+config = ClientConfig(
+    timeout=10.0,
+    max_retries=5,
+    language="ru_RU",
+    user_agent="Custom Agent 1.0"
+)
+client = LalafoClient(config=config)
+```
+
+### 3. Поиск и фильтрация (SearchRequest)
+Класс `SearchRequest` инкапсулирует все параметры поиска:
+* `q`: текстовый запрос.
+* `category_id`: ID категории.
+* `city_id`: ID города.
+* `price_from` / `price_to`: диапазон цен.
+* `parameters`: словарь дополнительных параметров.
+
+### 4. Модели данных (models/)
+Все ответы API преобразуются в Pydantic-модели. Это дает подсказки в IDE и гарантирует корректность данных.
+* **AdCompact**: краткая информация в результатах поиска.
+* **AdDetail**: полная информация об объявлении (включая все параметры и статус).
+* **Category**: модель дерева категорий.
+* **SearchResponse**: содержит список элементов, метаданные пагинации и ссылки на следующую/предыдущую страницы.
+
+### 5. Обработка исключений (exceptions.py)
+Библиотека генерирует специфические исключения:
+* `APIError`: базовая ошибка сервера.
+* `RateLimitError`: (429) превышен лимит запросов.
+* `AuthenticationError`: (401) ошибка доступа.
+* `NotFoundError`: (404) ресурс не найден.
+* `ValidationError`: ошибка во входных данных.
+
+## Утилиты (utils/)
+
+Библиотека умеет превращать обычные ссылки с сайта Lalafo в объекты, понятные коду:
+
+* **fetch_ad_from_url(url)**: принимает ссылку на объявление и возвращает его детали.
+* **get_search_request_from_url(url)**: анализирует ссылку поиска на сайте и создает готовый объект `SearchRequest` с примененными фильтрами (работает криво).
+
+Пример:
+```python
+# Получаем объект запроса из ссылки поиска
+request = client.get_search_request_from_url("https://lalafo.kg/bishkek/mobilnye-telefony-i-aksessuary/mobilnye-telefony?price[to]=2000")
+# Выполняем поиск по этому запросу
+results = client.search_ads(request)
+```
+
+## Работа с категориями
+Вы можете получить полное дерево категорий и перемещаться по нему:
+```python
+tree = client.get_categories_tree()
+
+# Поиск категории по ID
+category = tree.find_by_id(123)
+
+# Получение плоского списка всех подкатегорий
+flat_list = tree.flatten()
+```
+
+## Информация о пагинации
+`SearchResponse` предоставляет удобный доступ к навигации:
+* `response.has_next_page`: есть ли еще результаты.
+* `response.meta.totalCount`: общее количество найденных объявлений.
+* Метод `search_ads_all_pages` в клиенте позволяет автоматически собрать объявления с нескольких страниц подряд.

lalafo_api-0.1.0/README.md

@@ -0,0 +1,123 @@
+# Документация Lalafo API
+
+Этот код был написан в крайне сжатые сроки (буквально за 2 дня). Изначально стоял выбор: потратить месяц на попытку написать «идеально» или быстро «навайбкодить» рабочее решение. Был выбран второй вариант, однако в дальнейшем была проведена работа над ошибками, чтобы исправить структуру и привести библиотеку к нормальной архитектуре.
+
+Библиотека предоставляет удобный интерфейс для взаимодействия с API Lalafo, поддерживая как синхронный, так и асинхронный режимы работы.
+
+Установка: pip install lalafo-api
+
+## Основные возможности
+* Синхронный (`LalafoClient`) и асинхронный (`AsyncLalafoClient`) клиенты.
+* Полное покрытие моделей данных (объявления, категории, фильтры, пользователи).
+* Удобный поиск с поддержкой пагинации и фильтров.
+* Инструменты для парсинга данных напрямую из URL сайта Lalafo.
+* Автоматическая обработка ошибок API.
+
+## Быстрый старт
+
+### Синхронный клиент
+```python
+from lalafo import LalafoClient, SearchRequest
+
+client = LalafoClient()
+
+# Поиск объявлений
+request = SearchRequest(q="iPhone 15", price_to=100000)
+results = client.search_ads(request)
+
+for item in results.items:
+    print(f"{item.title} - {item.price} {item.currency}")
+```
+
+### Асинхронный клиент
+```python
+import asyncio
+from lalafo import AsyncLalafoClient
+
+async def main():
+    client = AsyncLalafoClient()
+    ad = await client.get_ad_details(ad_id=12345678)
+    print(ad.ad.title)
+    print(ad.ad.description)
+
+asyncio.run(main())
+```
+
+## Архитектура библиотеки
+
+### 1. Клиенты (api/)
+Библиотека использует два основных класса:
+* **LalafoClient**: использует `httpx` для блокирующих запросов. Подходит для простых скриптов.
+* **AsyncLalafoClient**: использует асинхронный `httpx`. Рекомендуется для ботов и веб-приложений.
+
+Оба клиента поддерживают автоматические повторы запросов (retries) при таймаутах, которые настраиваются через `ClientConfig`.
+
+### 2. Конфигурация (ClientConfig)
+Вы можете настроить заголовки, версию приложения и параметры сети:
+```python
+from lalafo import ClientConfig, LalafoClient
+
+config = ClientConfig(
+    timeout=10.0,
+    max_retries=5,
+    language="ru_RU",
+    user_agent="Custom Agent 1.0"
+)
+client = LalafoClient(config=config)
+```
+
+### 3. Поиск и фильтрация (SearchRequest)
+Класс `SearchRequest` инкапсулирует все параметры поиска:
+* `q`: текстовый запрос.
+* `category_id`: ID категории.
+* `city_id`: ID города.
+* `price_from` / `price_to`: диапазон цен.
+* `parameters`: словарь дополнительных параметров.
+
+### 4. Модели данных (models/)
+Все ответы API преобразуются в Pydantic-модели. Это дает подсказки в IDE и гарантирует корректность данных.
+* **AdCompact**: краткая информация в результатах поиска.
+* **AdDetail**: полная информация об объявлении (включая все параметры и статус).
+* **Category**: модель дерева категорий.
+* **SearchResponse**: содержит список элементов, метаданные пагинации и ссылки на следующую/предыдущую страницы.
+
+### 5. Обработка исключений (exceptions.py)
+Библиотека генерирует специфические исключения:
+* `APIError`: базовая ошибка сервера.
+* `RateLimitError`: (429) превышен лимит запросов.
+* `AuthenticationError`: (401) ошибка доступа.
+* `NotFoundError`: (404) ресурс не найден.
+* `ValidationError`: ошибка во входных данных.
+
+## Утилиты (utils/)
+
+Библиотека умеет превращать обычные ссылки с сайта Lalafo в объекты, понятные коду:
+
+* **fetch_ad_from_url(url)**: принимает ссылку на объявление и возвращает его детали.
+* **get_search_request_from_url(url)**: анализирует ссылку поиска на сайте и создает готовый объект `SearchRequest` с примененными фильтрами (работает криво).
+
+Пример:
+```python
+# Получаем объект запроса из ссылки поиска
+request = client.get_search_request_from_url("https://lalafo.kg/bishkek/mobilnye-telefony-i-aksessuary/mobilnye-telefony?price[to]=2000")
+# Выполняем поиск по этому запросу
+results = client.search_ads(request)
+```
+
+## Работа с категориями
+Вы можете получить полное дерево категорий и перемещаться по нему:
+```python
+tree = client.get_categories_tree()
+
+# Поиск категории по ID
+category = tree.find_by_id(123)
+
+# Получение плоского списка всех подкатегорий
+flat_list = tree.flatten()
+```
+
+## Информация о пагинации
+`SearchResponse` предоставляет удобный доступ к навигации:
+* `response.has_next_page`: есть ли еще результаты.
+* `response.meta.totalCount`: общее количество найденных объявлений.
+* Метод `search_ads_all_pages` в клиенте позволяет автоматически собрать объявления с нескольких страниц подряд.

lalafo_api-0.1.0/lalafo_api/__init__.py

@@ -0,0 +1,22 @@
+"""
+Библиотека для работы с API Lalafo
+"""
+from .exceptions import (
+    LalafoError, APIError, ValidationError,
+    RateLimitError, AuthenticationError, NotFoundError
+)
+from .models import *
+from .enums import Currency, SortBy, FilterKind, AdStatus
+from .api import *
+
+__all__ = [
+    'LalafoError', 'APIError', 'ValidationError',
+    'RateLimitError', 'AuthenticationError', 'NotFoundError',
+    
+    'ClientConfig', 'SearchRequest', 'Currency', 'SortBy', 'FilterKind', 'AdStatus',
+    'Category', 'AdCompact', 'AdDetail', 'User', 'Image', 'Filter', 'FilterValue',
+    'CategoriesResponse', 'FiltersResponse', 'ParamsFilterResponse',
+    'AdDetailsResponse', 'SearchResponse',
+    
+    'LalafoClient', 'AsyncLalafoClient'
+]

lalafo_api-0.1.0/lalafo_api/api/__init__.py

@@ -0,0 +1,8 @@
+from .lalafo_client import LalafoClient
+from .async_lalafo_client import AsyncLalafoClient
+
+
+__all__ = [
+    'LalafoClient',
+    'AsyncLalafoClient'
+]

lalafo_api-0.1.0/lalafo_api/api/async_lalafo_client.py

@@ -0,0 +1,266 @@
+import asyncio
+from typing import Optional, Dict, Any, List
+import logging
+
+import httpx
+from ..enums import Currency
+from ..models import (
+    ClientConfig, SearchRequest, CategoriesResponse,
+    FiltersResponse, ParamsFilterResponse, AdDetailsResponse,
+    SearchResponse, AdCompact
+)
+from ..utils import parse_ad_url, parse_search_url
+from ..exceptions import APIError
+from .base_lalafo_client import BaseLalafoClient
+from .clients import get_async_client
+
+
+class AsyncLalafoClient(BaseLalafoClient):
+    """Асинхронный клиент Lalafo API"""
+    
+    def __init__(
+        self,
+        config: Optional[ClientConfig] = None,
+        logger: Optional[logging.Logger] = None
+    ):
+        super().__init__(config, logger)
+    
+    async def _make_request(
+        self,
+        method: str,
+        endpoint: str,
+        params: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
+        retries: int = None
+    ) -> Dict[str, Any]:
+        retries = retries or self.config.max_retries
+        headers = self._prepare_headers(headers)
+        
+        for attempt in range(retries):
+            try:
+                self._log_request(method, endpoint, params)
+                
+                async with get_async_client() as client:
+                    response = await client.request(
+                        method=method,
+                        url=endpoint,
+                        params=params,
+                        headers=headers
+                    )
+                
+                self._log_response(response)
+                return self._handle_response(response)
+                
+            except httpx.TimeoutException as e:
+                self.logger.warning(f"Таймаут запроса (попытка {attempt + 1}/{retries}): {e}")
+                if attempt == retries - 1:
+                    raise APIError(f"Таймаут запроса после {retries} попыток", 408)
+                await asyncio.sleep(self.config.retry_delay * (attempt + 1))
+                
+            except httpx.RequestError as e:
+                self.logger.error(f"Ошибка запроса: {e}")
+                if attempt == retries - 1:
+                    raise APIError(f"Ошибка сети: {str(e)}", 0)
+                await asyncio.sleep(self.config.retry_delay * (attempt + 1))
+    
+    async def get_categories_tree(self, with_duplicates: bool = True) -> CategoriesResponse:
+        endpoint = "/v3/categories/tree"
+        params = {"with_duplicates": 1 if with_duplicates else 0}
+        
+        data = await self._make_request("GET", endpoint, params=params)
+        return CategoriesResponse.from_api_response(data)
+    
+    async def get_filters(
+        self,
+        category_id: Optional[int] = None,
+        city_id: Optional[int] = None,
+        currency: Currency = Currency.KGS,
+        sort_by: str = "default",
+        with_filters: bool = True,
+        with_empty_values: bool = True,
+        with_category_counter: bool = True,
+        parameters: Optional[Dict[str, List[int]]] = None,
+        price_from: Optional[int] = None,
+        price_to: Optional[int] = None
+    ) -> FiltersResponse:
+        endpoint = "/v3/ads/filters"
+        
+        params = {
+            "with_filters": str(with_filters).lower(),
+            "with_empty_values": str(with_empty_values).lower(),
+            "with_category_counter": str(with_category_counter).lower(),
+            "currency": currency.value,
+            "sort_by": sort_by
+        }
+        
+        if category_id:
+            params["category_id"] = category_id
+        if city_id:
+            params["city_id"] = city_id
+        if price_from is not None:
+            params["price[from]"] = price_from
+        if price_to is not None:
+            params["price[to]"] = price_to
+        
+        if parameters:
+            for param_id, values in parameters.items():
+                for i, value_id in enumerate(values):
+                    params[f"parameters[{param_id}][{i}]"] = value_id
+        
+        data = await self._make_request("GET", endpoint, params=params)
+        return FiltersResponse(**data)
+    
+    async def get_params_filter(
+        self,
+        category_id: int,
+        city_id: Optional[int] = None,
+        radius: int = 0,
+        location_lat: Optional[float] = None,
+        location_lng: Optional[float] = None
+    ) -> ParamsFilterResponse:
+        endpoint = "/v3/params/filter"
+        
+        params = {
+            "category_id": category_id,
+            "radius": radius
+        }
+        
+        if city_id:
+            params["city_id"] = city_id
+        if location_lat:
+            params["location[lat]"] = location_lat
+        if location_lng:
+            params["location[lng]"] = location_lng
+        
+        data = await self._make_request("GET", endpoint, params=params)
+        return ParamsFilterResponse.from_api_response(data)
+    
+    async def get_ad_details(self, ad_id: int) -> AdDetailsResponse:
+        endpoint = f"/v3/ads/details/{ad_id}"
+        
+        data = await self._make_request("GET", endpoint)
+        return AdDetailsResponse.from_api_response(data)
+    
+    async def search_ads(self, search_request: SearchRequest) -> SearchResponse:
+        endpoint = "/v3/ads/search"
+        params = search_request.to_query_params()
+        
+        data = await self._make_request("GET", endpoint, params=params)
+        return SearchResponse.from_api_response(data)
+    
+    async def search_ads_all_pages(
+        self,
+        search_request: SearchRequest,
+        max_pages: int = 100,
+        delay_between_pages: float = 0.5
+    ) -> List[AdCompact]:
+        all_items = []
+        current_page = search_request.page
+        
+        for page_num in range(max_pages):
+            search_request.page = current_page
+            
+            try:
+                response = await self.search_ads(search_request)
+                all_items.extend(response.items)
+                
+                if not response.has_next_page:
+                    break
+                
+                current_page += 1
+                
+                if delay_between_pages > 0:
+                    await asyncio.sleep(delay_between_pages)
+                    
+            except Exception as e:
+                break
+        
+        return all_items
+    
+    async def search_ads_simple(
+        self,
+        category_id: Optional[int] = None,
+        city_id: Optional[int] = None,
+        q: Optional[str] = None,
+        price_from: Optional[int] = None,
+        price_to: Optional[int] = None,
+        page: int = 1,
+        per_page: int = 40
+    ) -> SearchResponse:
+        search_request = SearchRequest(
+            category_id=category_id,
+            city_id=city_id,
+            q=q,
+            price_from=price_from,
+            price_to=price_to,
+            page=page,
+            per_page=per_page
+        )
+        
+        return await self.search_ads(search_request)
+    
+    async def get_user_ads(
+        self,
+        user_id: int,
+        page: int = 1,
+        per_page: int = 40
+    ) -> SearchResponse:
+        search_request = SearchRequest(
+            user_id=user_id,
+            page=page,
+            per_page=per_page
+        )
+        
+        return await self.search_ads(search_request)
+    
+    async def get_related_ads(
+        self,
+        ad_id: int,
+        category_id: int,
+        city_id: int,
+        per_page: int = 40,
+        vip_count: int = 2
+    ) -> SearchResponse:
+        endpoint = f"/v3/ads/related-items/{ad_id}"
+        
+        params = {
+            "category_id": category_id,
+            "city_id": city_id,
+            "per-page": per_page,
+            "vip-count": vip_count,
+            "with_feed_banner": "true"
+        }
+        
+        data = await self._make_request("GET", endpoint, params=params)
+        return SearchResponse.from_api_response(data)
+    
+    async def get_feed_elements(self, category_id: int) -> Dict[str, Any]:
+        endpoint = "/v3/feed-elements/scheme"
+        params = {"category_id": category_id}
+        
+        return await self._make_request("GET", endpoint, params=params)
+    
+    async def get_user_status(self, user_ids: List[int]) -> List[Dict[str, Any]]:
+        endpoint = "/v3/users/get-user-status"
+        
+        params = {}
+        for i, user_id in enumerate(user_ids):
+            params[f"userIds[{i}]"] = user_id
+        
+        return await self._make_request("GET", endpoint, params=params)
+
+    async def fetch_ad_from_url(self, url: str) -> AdDetailsResponse:
+        parsed = parse_ad_url(url)
+        if not parsed or 'ad_id' not in parsed:
+            raise ValueError(f"Не удалось извлечь ID объявления из URL: {url}")
+        
+        return await self.get_ad_details(parsed['ad_id'])
+
+    async def get_search_request_from_url(
+            self, url: str,
+            currency: Currency = Currency.KGS
+        ) -> Optional[SearchRequest]:
+        parsed = parse_search_url(url, (await self.get_filters(currency = currency)).filters[0].cities, await self.get_categories_tree())
+        if not parsed:
+            return None
+        return SearchRequest(**parsed['search_params'])