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

{amochka-0.3.0.dist-info → amochka-0.3.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: amochka
-Version: 0.3.0
+Version: 0.3.1
 Summary: Python library for working with amoCRM API with ETL capabilities
 Author-email: Timur <timurdt@gmail.com>
 License: MIT
@@ -39,88 +39,167 @@ Requires-Dist: python-dotenv>=1.0.0
 - Редактирование сделок, включая обновление стандартных и кастомных полей
 - Поддержку нескольких 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.8 или новее. Потребуются пакеты `requests` и `ratelimit`.
+Python 3.6 или новее.
 
 ## Установка
 
-Установите зависимости командой:
-
 ```bash
-pip install requests ratelimit
+pip install amochka
 ```
 
-Затем скопируйте репозиторий или установите пакет из PyPI (после публикации):
+Для использования ETL модуля установите дополнительные зависимости:
 
 ```bash
-pip install amochka
+pip install amochka psycopg2-binary python-dotenv
 ```
 
 ## Кэширование кастомных полей
 
 Для уменьшения количества запросов к API кастомные поля кэшируются персистентно. Если параметр cache_file не указан, имя файла кэша генерируется автоматически на основе домена amoCRM-аккаунта. Вы можете обновлять кэш принудительно, передавая параметр force_update=True в метод get_custom_fields_mapping() или настроить время жизни кэша (по умолчанию — 24 часа).
 
-## Выгрузка обновленных сделок
+## Примеры использования
 
-Метод `fetch_updated_leads_raw()` позволяет получить все сделки из указанной воронки, которые были изменены в заданный промежуток времени. Результат можно сохранить в JSON-файл без какой‑либо обработки:
+### Быстрый старт: выгрузка обновленных сделок
 
 ```python
 from datetime import datetime, timedelta
 from amochka import AmoCRMClient, CacheConfig
 
 client = AmoCRMClient(
-    base_url="https://bneginskogo.amocrm.ru",
-    token_file="/path/to/token.json",
+    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)
-client.fetch_updated_leads_raw(6241334, updated_from=three_hours_ago, save_to_file="leads.json")
+leads = client.fetch_updated_leads_raw(
+    pipeline_id=123456,
+    updated_from=three_hours_ago,
+    save_to_file="leads.json",
+    include_contacts=True
+)
 ```
 
-Пример получаемого JSON (укороченный):
+### 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": 26282337,
-    "name": "Автосделка: Заявка от (Максим Брокер Дубай Бюро Негинского)",
+    "id": 12345678,
+    "name": "Сделка: Заявка от клиента",
     "custom_fields_values": [
       {
-        "field_name": "roistat",
-        "values": [{"value": "2026"}]
+        "field_name": "utm_source",
+        "values": [{"value": "google"}]
       }
     ],
     "_embedded": {
       "tags": [
-        {"id": 179813, "name": "WZ (Федор 971568113315)"}
+        {"id": 123, "name": "Приоритетный клиент"}
       ]
     }
   }
 ]
 ```
 
-Для подключения к реальному аккаунту сохраните JSON с OAuth‑токеном и укажите его путь в параметре `token_file` при создании клиента. Базовый URL можно взять из переменной окружения `AMO_BASE_URL`.
+## Интеграция с 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()
+```
 
 ## Тесты
 
-Файл `tests/test_client.py` содержит небольшой набор автоматических тестов, написанных на [pytest](https://docs.pytest.org/). Они запускают методы клиента на подставном классе `DummyClient` и проверяют, что функции работают так, как ожидается. Запустить тесты можно командой:
+Запустить тесты можно командой:
 
 ```bash
 pytest -q
 ```
 
-Эти тесты помогают убедиться, что изменения в коде не ломают основную функциональность.
+Тесты проверяют основную функциональность API клиента и помогают убедиться, что изменения в коде не ломают работу библиотеки.
 
-## Пример использования `fetch_updated_leads_raw`
+## Лицензия
 
-Кроме примера в разделе выше, код из `example_fetch.py` демонстрирует полный процесс получения сделок и сохранения их в файл.
+MIT

{amochka-0.3.0.dist-info → amochka-0.3.1.dist-info}/RECORD

@@ -8,7 +8,7 @@ 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.0.dist-info/METADATA,sha256=5dZFPOs2wupzc0VsYVXyk1pJ-F4Kwm997N9EA_Z7htE,6371
-amochka-0.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-amochka-0.3.0.dist-info/top_level.txt,sha256=grRX8aLFG-yYKPsAqCD6sUBmdLSQeOMHsc9Dl6S7Lzo,12
-amochka-0.3.0.dist-info/RECORD,,
+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,,