amochka 0.1.9__py3-none-any.whl → 0.3.1__py3-none-any.whl

amochka/etl.py

@@ -0,0 +1,302 @@
+import json
+from pathlib import Path
+from typing import Callable, Iterable, List, Optional, Sequence, Set, Union
+
+from .client import AmoCRMClient
+
+
+def _ensure_path(path: Union[str, Path]) -> Path:
+    output_path = Path(path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    return output_path
+
+
+def _resolve_timestamp(record: dict, timestamp_fields: Sequence[str]) -> Optional[Union[int, float, str]]:
+    for field in timestamp_fields:
+        if not field:
+            continue
+        value = record.get(field)
+        if value is not None:
+            return value
+    return None
+
+
+def write_ndjson(
+    records: Iterable[dict],
+    output_path: Union[str, Path],
+    *,
+    entity: str,
+    account_id: Optional[Union[int, str]] = None,
+    timestamp_fields: Sequence[str] = ("updated_at", "created_at"),
+    transform: Optional[Callable[[dict], dict]] = None,
+    on_record: Optional[Callable[[dict], None]] = None,
+) -> int:
+    """
+    Записывает переданные записи в формат NDJSON.
+
+    Возвращает количество записанных строк.
+    """
+    path = _ensure_path(output_path)
+    count = 0
+    with path.open("w", encoding="utf-8") as handler:
+        for original in records:
+            payload = transform(original) if transform else original
+            timestamp = _resolve_timestamp(original, timestamp_fields)
+            line = {
+                "entity": entity,
+                "account_id": account_id,
+                "updated_at": timestamp,
+                "payload": payload,
+            }
+            handler.write(json.dumps(line, ensure_ascii=False))
+            handler.write("\n")
+            count += 1
+            if on_record:
+                on_record(original)
+    return count
+
+
+def export_leads_to_ndjson(
+    client: AmoCRMClient,
+    output_path: Union[str, Path],
+    account_id: Union[int, str],
+    *,
+    start=None,
+    end=None,
+    pipeline_ids=None,
+    include_contacts: bool = True,
+    include=None,
+    limit: int = 250,
+    extra_params: Optional[dict] = None,
+    on_record: Optional[Callable[[dict], None]] = None,
+) -> int:
+    """
+    Выгружает сделки и записывает их в NDJSON.
+    """
+    records = client.iter_leads(
+        updated_from=start,
+        updated_to=end,
+        pipeline_ids=pipeline_ids,
+        include_contacts=include_contacts,
+        include=include,
+        limit=limit,
+        extra_params=extra_params,
+    )
+    return write_ndjson(
+        records,
+        output_path,
+        entity="lead",
+        account_id=account_id,
+        timestamp_fields=("updated_at", "created_at"),
+        on_record=on_record,
+    )
+
+
+def export_contacts_to_ndjson(
+    client: AmoCRMClient,
+    output_path: Union[str, Path],
+    account_id: Union[int, str],
+    *,
+    start=None,
+    end=None,
+    contact_ids=None,
+    limit: int = 250,
+    extra_params: Optional[dict] = None,
+    on_record: Optional[Callable[[dict], None]] = None,
+) -> int:
+    """
+    Выгружает контакты и записывает их в NDJSON.
+    """
+    contact_id_list: Optional[List[int]] = None
+    if contact_ids is not None:
+        if isinstance(contact_ids, (list, tuple, set)):
+            contact_id_list = [int(cid) for cid in contact_ids if cid is not None]
+        else:
+            contact_id_list = [int(contact_ids)]
+
+    def _iter_contacts():
+        seen: Set[int] = set()
+        if contact_id_list:
+            params = dict(extra_params or {})
+            params["filter[id][]"] = [str(cid) for cid in contact_id_list]
+            params["page"] = 1
+            params["limit"] = limit
+            while True:
+                response = client._make_request("GET", "/api/v4/contacts", params=params)
+                embedded = (response or {}).get("_embedded", {})
+                contacts = embedded.get("contacts") or []
+                if not contacts:
+                    break
+                for contact in contacts:
+                    cid = contact.get("id")
+                    if cid is not None:
+                        seen.add(int(cid))
+                    yield contact
+                total_pages = response.get("_page_count", params["page"])
+                if params["page"] >= total_pages:
+                    break
+                params["page"] += 1
+        else:
+            for contact in client.iter_contacts(
+                updated_from=start,
+                updated_to=end,
+                contact_ids=None,
+                limit=limit,
+                extra_params=extra_params,
+            ):
+                cid = contact.get("id")
+                if cid is not None:
+                    seen.add(int(cid))
+                yield contact
+
+        if contact_id_list:
+            missing = [cid for cid in contact_id_list if cid not in seen]
+            for cid in missing:
+                try:
+                    contact = client.get_contact_by_id(cid)
+                except Exception:
+                    continue
+                retrieved_id = contact.get("id")
+                if retrieved_id is not None and int(retrieved_id) not in seen:
+                    seen.add(int(retrieved_id))
+                    yield contact
+
+    return write_ndjson(
+        _iter_contacts(),
+        output_path,
+        entity="contact",
+        account_id=account_id,
+        timestamp_fields=("updated_at", "created_at"),
+        on_record=on_record,
+    )
+
+
+def export_notes_to_ndjson(
+    client: AmoCRMClient,
+    output_path: Union[str, Path],
+    account_id: Union[int, str],
+    *,
+    entity: str = "lead",
+    start=None,
+    end=None,
+    note_type=None,
+    entity_ids=None,
+    limit: int = 250,
+    extra_params: Optional[dict] = None,
+    on_record: Optional[Callable[[dict], None]] = None,
+) -> int:
+    """
+    Выгружает примечания и записывает их в NDJSON.
+    """
+    records = client.iter_notes(
+        entity=entity,
+        updated_from=start,
+        updated_to=end,
+        note_type=note_type,
+        entity_ids=entity_ids,
+        limit=limit,
+        extra_params=extra_params,
+    )
+    entity_name = f"{entity}_note" if entity else "note"
+    return write_ndjson(
+        records,
+        output_path,
+        entity=entity_name,
+        account_id=account_id,
+        timestamp_fields=("updated_at", "created_at"),
+        on_record=on_record,
+    )
+
+
+def export_events_to_ndjson(
+    client: AmoCRMClient,
+    output_path: Union[str, Path],
+    account_id: Union[int, str],
+    *,
+    entity: Optional[str] = "lead",
+    start=None,
+    end=None,
+    event_type=None,
+    entity_ids=None,
+    limit: int = 250,
+    extra_params: Optional[dict] = None,
+    on_record: Optional[Callable[[dict], None]] = None,
+) -> int:
+    """
+    Выгружает события и записывает их в NDJSON.
+    """
+    records = client.iter_events(
+        entity=entity,
+        entity_ids=entity_ids,
+        event_type=event_type,
+        created_from=start,
+        created_to=end,
+        limit=limit,
+        extra_params=extra_params,
+    )
+    entity_name = f"{entity}_event" if entity else "event"
+    return write_ndjson(
+        records,
+        output_path,
+        entity=entity_name,
+        account_id=account_id,
+        timestamp_fields=("created_at", "updated_at"),
+        on_record=on_record,
+    )
+
+
+def export_users_to_ndjson(
+    client: AmoCRMClient,
+    output_path: Union[str, Path],
+    account_id: Union[int, str],
+    *,
+    limit: int = 250,
+    extra_params: Optional[dict] = None,
+    on_record: Optional[Callable[[dict], None]] = None,
+) -> int:
+    """
+    Выгружает пользователей и записывает их в NDJSON.
+    """
+    records = client.iter_users(limit=limit, extra_params=extra_params)
+    return write_ndjson(
+        records,
+        output_path,
+        entity="user",
+        account_id=account_id,
+        timestamp_fields=("updated_at", "created_at"),
+        on_record=on_record,
+    )
+
+
+def export_pipelines_to_ndjson(
+    client: AmoCRMClient,
+    output_path: Union[str, Path],
+    account_id: Union[int, str],
+    *,
+    limit: int = 250,
+    extra_params: Optional[dict] = None,
+    on_record: Optional[Callable[[dict], None]] = None,
+) -> int:
+    """
+    Выгружает воронки и записывает их в NDJSON.
+    """
+    records = client.iter_pipelines(limit=limit, extra_params=extra_params)
+    return write_ndjson(
+        records,
+        output_path,
+        entity="pipeline",
+        account_id=account_id,
+        timestamp_fields=("updated_at", "created_at"),
+        on_record=on_record,
+    )
+
+
+__all__ = [
+    "write_ndjson",
+    "export_leads_to_ndjson",
+    "export_contacts_to_ndjson",
+    "export_notes_to_ndjson",
+    "export_events_to_ndjson",
+    "export_users_to_ndjson",
+    "export_pipelines_to_ndjson",
+]

amochka-0.3.1.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: amochka
+Version: 0.3.1
+Summary: Python library for working with amoCRM API with ETL capabilities
+Author-email: Timur <timurdt@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/amochka
+Project-URL: Documentation, https://github.com/yourusername/amochka
+Project-URL: Repository, https://github.com/yourusername/amochka
+Project-URL: Bug Tracker, https://github.com/yourusername/amochka/issues
+Keywords: amocrm,crm,api,client,automation,etl
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Requires-Dist: ratelimit>=2.2.0
+Requires-Dist: psycopg2-binary>=2.9.0
+Requires-Dist: python-dotenv>=1.0.0
+
+# amochka
+
+Официальная документация API amocrm - https://www.amocrm.ru/developers/content/crm_platform/api-reference
+
+**amochka** — библиотека для работы с API amoCRM на Python. Она поддерживает:
+- Получение данных сделок с вложенными сущностями (контакты, компании, теги, и т.д.)
+- Редактирование сделок, включая обновление стандартных и кастомных полей
+- Поддержку нескольких amoCRM-аккаунтов с персистентным кэшированием кастомных полей для каждого аккаунта отдельно
+- Ограничение запросов (7 запросов в секунду) с использованием декораторов из библиотеки `ratelimit`
+- **Полнофункциональный ETL модуль** для синхронизации данных amoCRM в PostgreSQL
+
+## Возможности
+
+### API клиент
+
+- `get_deal_by_id(deal_id)` — получение детальной информации по сделке
+- `get_pipelines()` — список воронок и статусов
+- `fetch_updated_leads_raw(pipeline_id, updated_from, ...)` — выгрузка необработанных сделок за период
+
+### ETL модуль
+
+- **Extractors**: извлечение данных из amoCRM (сделки, контакты, события, примечания)
+- **Transformers**: преобразование в табличный формат для БД
+- **Loaders**: загрузка в PostgreSQL с UPSERT логикой и сохранением внутренних ID
+- **Migrations**: автоматическое создание таблиц и схем
+- **Incremental sync**: инкрементальная синхронизация по updated_at
+- Интеграция с **Apache Airflow** для автоматизации ETL процессов
+
+## Требования к окружению
+
+Python 3.6 или новее.
+
+## Установка
+
+```bash
+pip install amochka
+```
+
+Для использования ETL модуля установите дополнительные зависимости:
+
+```bash
+pip install amochka psycopg2-binary python-dotenv
+```
+
+## Кэширование кастомных полей
+
+Для уменьшения количества запросов к API кастомные поля кэшируются персистентно. Если параметр cache_file не указан, имя файла кэша генерируется автоматически на основе домена amoCRM-аккаунта. Вы можете обновлять кэш принудительно, передавая параметр force_update=True в метод get_custom_fields_mapping() или настроить время жизни кэша (по умолчанию — 24 часа).
+
+## Примеры использования
+
+### Быстрый старт: выгрузка обновленных сделок
+
+```python
+from datetime import datetime, timedelta
+from amochka import AmoCRMClient, CacheConfig
+
+client = AmoCRMClient(
+    base_url="https://example.amocrm.ru",
+    token_file="token.json",
+    cache_config=CacheConfig.disabled(),
+    disable_logging=True
+)
+
+three_hours_ago = datetime.utcnow() - timedelta(hours=3)
+leads = client.fetch_updated_leads_raw(
+    pipeline_id=123456,
+    updated_from=three_hours_ago,
+    save_to_file="leads.json",
+    include_contacts=True
+)
+```
+
+### ETL: синхронизация в PostgreSQL
+
+```python
+from etl.config import DatabaseConfig, AmoCRMAccount
+from etl.extractors import AmoCRMExtractor
+from etl.loaders import PostgresLoader
+from etl.run_etl import sync_leads_with_contacts
+from datetime import datetime, timezone
+
+# Настройка БД
+db_config = DatabaseConfig(
+    host="localhost",
+    port=5432,
+    dbname="amocrm",
+    user="postgres",
+    password="password",
+    schema="public"
+)
+
+# Настройка amoCRM аккаунта
+account = AmoCRMAccount(
+    id=1,
+    name="main",
+    base_url="https://example.amocrm.ru",
+    token_path="token.json",
+    mybi_account_id=1,
+    pipeline_ids=[123456]
+)
+
+# ETL процесс
+loader = PostgresLoader(db_config)
+extractor = AmoCRMExtractor(account)
+
+result = sync_leads_with_contacts(
+    extractor=extractor,
+    loader=loader,
+    mybi_account_id=1,
+    updated_from=datetime(2025, 1, 1, tzinfo=timezone.utc),
+    updated_to=datetime.now(timezone.utc),
+    pipeline_ids=[123456]
+)
+
+print(f"Загружено сделок: {result['leads_count']}")
+print(f"Загружено контактов: {result['contacts_count']}")
+```
+
+### Пример структуры данных
+
+```json
+[
+  {
+    "id": 12345678,
+    "name": "Сделка: Заявка от клиента",
+    "custom_fields_values": [
+      {
+        "field_name": "utm_source",
+        "values": [{"value": "google"}]
+      }
+    ],
+    "_embedded": {
+      "tags": [
+        {"id": 123, "name": "Приоритетный клиент"}
+      ]
+    }
+  }
+]
+```
+
+## Интеграция с Apache Airflow
+
+Модуль ETL разработан для использования в Airflow DAG. Пример минимального DAG:
+
+```python
+from airflow.decorators import dag, task
+from etl.config import DatabaseConfig, AmoCRMAccount
+from etl.run_etl import sync_leads_with_contacts
+
+@dag(schedule_interval=None)
+def amocrm_sync():
+    @task
+    def sync_data():
+        db_config = DatabaseConfig.from_env()
+        account = AmoCRMAccount.from_env()
+        # ... ETL процесс
+
+amocrm_sync()
+```
+
+## Тесты
+
+Запустить тесты можно командой:
+
+```bash
+pytest -q
+```
+
+Тесты проверяют основную функциональность API клиента и помогают убедиться, что изменения в коде не ломают работу библиотеки.
+
+## Лицензия
+
+MIT

amochka-0.3.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+amochka/__init__.py,sha256=NFAgMbhBnrx3nF--MeY9Chpu5gtZ5kVn-QYnmO3Nhpk,620
+amochka/client.py,sha256=mGoDEE0XOt-c9f2FmqFVzDMrXQel_zComtyAFXdCHjg,66155
+amochka/etl.py,sha256=N8rXNFbtmlKfsYpgr7HDcP4enoj63XQPWuTDxGuMhw4,8901
+etl/__init__.py,sha256=bp9fPqbKlOc7xzs27diHEvysy1FgBrwlpX6GnR6GL9U,255
+etl/config.py,sha256=YY6M7pib_XD7bjPW8J_iWzt2hoXzDpx6yIvZHmlUlrE,8873
+etl/extractors.py,sha256=-QCBZ6PoJ51j0drNQaH5bLfvjPqAQmfVgaT1D_ZSwjI,12909
+etl/loaders.py,sha256=nQx6TDwnuHVWzjmuKY9v-23hmmk4Ex6ZoGtb3PApO1k,31974
+etl/run_etl.py,sha256=p_2NxJwXMiACMETvRsjrozMgz66U9ezDNSWZXUieNMs,26262
+etl/transformers.py,sha256=OwYJ_9l3oqvy2Y3-umXjAGweOIqlfRI0iSiCFPrcQ8E,17867
+etl/migrations/001_create_tables.sql,sha256=YrSaZjpofC1smjYx0bM4eHQumboruIBY3fwRDlJLLSo,15749
+amochka-0.3.1.dist-info/METADATA,sha256=CF7UAIgc6PvyJv9I8CULTlBQOV8BITZlwscrUo3BM10,7562
+amochka-0.3.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+amochka-0.3.1.dist-info/top_level.txt,sha256=grRX8aLFG-yYKPsAqCD6sUBmdLSQeOMHsc9Dl6S7Lzo,12
+amochka-0.3.1.dist-info/RECORD,,

amochka-0.3.1.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+amochka
+etl

etl/__init__.py

@@ -0,0 +1,7 @@
+"""
+ETL-коннектор для выгрузки данных из amoCRM в PostgreSQL.
+
+Структура таблиц совместима с mybi.ru для работы с существующими dbt-моделями.
+"""
+
+__version__ = "0.1.0"