amochka 0.3.0__tar.gz → 0.3.1__tar.gz

{amochka-0.3.0 → amochka-0.3.1}/PKG-INFO

@@ -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.1/README.md

@@ -0,0 +1,173 @@
+# 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.0 → amochka-0.3.1}/amochka.egg-info/PKG-INFO

@@ -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 → amochka-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "amochka"
-version = "0.3.0"
+version = "0.3.1"
 description = "Python library for working with amoCRM API with ETL capabilities"
 readme = "README.md"
 authors = [

amochka-0.3.0/README.md

@@ -1,94 +0,0 @@
-# amochka
-
-Официальная документация API amocrm - https://www.amocrm.ru/developers/content/crm_platform/api-reference
-
-**amochka** — библиотека для работы с API amoCRM на Python. Она поддерживает:
-- Получение данных сделок с вложенными сущностями (контакты, компании, теги, и т.д.)
-- Редактирование сделок, включая обновление стандартных и кастомных полей
-- Поддержку нескольких amoCRM-аккаунтов с персистентным кэшированием кастомных полей для каждого аккаунта отдельно
-- Ограничение запросов (7 запросов в секунду) с использованием декораторов из библиотеки `ratelimit`
-
-### Основные функции
-
-- `get_deal_by_id(deal_id)` — получение детальной информации по сделке
-- `get_pipelines()` — список воронок и статусов
-- `fetch_updated_leads_raw(pipeline_id, updated_from, ...)` — выгрузка необработанных сделок за период
-
-## Требования к окружению
-
-Python 3.8 или новее. Потребуются пакеты `requests` и `ratelimit`.
-
-## Установка
-
-Установите зависимости командой:
-
-```bash
-pip install requests ratelimit
-```
-
-Затем скопируйте репозиторий или установите пакет из PyPI (после публикации):
-
-```bash
-pip install amochka
-```
-
-## Кэширование кастомных полей
-
-Для уменьшения количества запросов к 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",
-    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")
-```
-
-Пример получаемого JSON (укороченный):
-
-```json
-[
-  {
-    "id": 26282337,
-    "name": "Автосделка: Заявка от (Максим Брокер Дубай Бюро Негинского)",
-    "custom_fields_values": [
-      {
-        "field_name": "roistat",
-        "values": [{"value": "2026"}]
-      }
-    ],
-    "_embedded": {
-      "tags": [
-        {"id": 179813, "name": "WZ (Федор 971568113315)"}
-      ]
-    }
-  }
-]
-```
-
-Для подключения к реальному аккаунту сохраните JSON с OAuth‑токеном и укажите его путь в параметре `token_file` при создании клиента. Базовый URL можно взять из переменной окружения `AMO_BASE_URL`.
-
-## Тесты
-
-Файл `tests/test_client.py` содержит небольшой набор автоматических тестов, написанных на [pytest](https://docs.pytest.org/). Они запускают методы клиента на подставном классе `DummyClient` и проверяют, что функции работают так, как ожидается. Запустить тесты можно командой:
-
-```bash
-pytest -q
-```
-
-Эти тесты помогают убедиться, что изменения в коде не ломают основную функциональность.
-
-## Пример использования `fetch_updated_leads_raw`
-
-Кроме примера в разделе выше, код из `example_fetch.py` демонстрирует полный процесс получения сделок и сохранения их в файл.