amochka 0.1.8__tar.gz → 0.3.0__tar.gz

amochka-0.3.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: amochka
+Version: 0.3.0
+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`
+
+### Основные функции
+
+- `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` демонстрирует полный процесс получения сделок и сохранения их в файл.

amochka-0.3.0/README.md

@@ -0,0 +1,94 @@
+# 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` демонстрирует полный процесс получения сделок и сохранения их в файл.

{amochka-0.1.8/amochka → amochka-0.3.0}/amochka/__init__.py

@@ -2,7 +2,7 @@
 amochka: Библиотека для работы с API amoCRM.
 """
 
-__version__ = "0.1.8"
+__version__ = "0.2.0"
 
 from .client import AmoCRMClient, CacheConfig
 from .etl import (

{amochka-0.1.8/amochka → amochka-0.3.0}/amochka/client.py

@@ -174,33 +174,77 @@ class Deal(dict):
 class CacheConfig:
     """
     Конфигурация кэширования для AmoCRMClient.
-    
+
     Параметры:
         enabled (bool): Включено ли кэширование
         storage (str): Тип хранилища ('file' или 'memory')
-        file (str): Путь к файлу кэша (используется только при storage='file')
-        lifetime_hours (int|None): Время жизни кэша в часах (None для бесконечного)
+        base_dir (str): Базовая директория для кэша (по умолчанию ~/.amocrm/cache/)
+        file (str): Путь к файлу кэша (устаревший, для обратной совместимости)
+        lifetime_hours (int|dict|None): Время жизни кэша в часах
+            - int: одинаковое время для всех типов данных
+            - dict: разное время для каждого типа (например, {'pipelines': 168, 'users': 24})
+            - None: бесконечный кэш
     """
-    def __init__(self, enabled=True, storage='file', file=None, lifetime_hours=24):
+    DEFAULT_LIFETIMES = {
+        'custom_fields': 24,
+        'pipelines': 168,  # 7 дней
+        'users': 24,
+    }
+
+    def __init__(self, enabled=True, storage='file', base_dir=None, file=None, lifetime_hours='default'):
         self.enabled = enabled
         self.storage = storage.lower()
-        self.file = file
-        self.lifetime_hours = lifetime_hours
-    
+        self.base_dir = base_dir or os.path.join(os.path.expanduser('~'), '.amocrm', 'cache')
+        self.file = file  # Для обратной совместимости с custom fields
+
+        # Обработка lifetime_hours: может быть int, dict, None, или 'default'
+        if lifetime_hours == 'default':
+            # Используем дефолтные значения
+            self.lifetime_hours = self.DEFAULT_LIFETIMES.copy()
+        elif isinstance(lifetime_hours, dict):
+            # Объединяем дефолтные значения с пользовательскими
+            self.lifetime_hours = {**self.DEFAULT_LIFETIMES, **lifetime_hours}
+        elif lifetime_hours is None:
+            # Бесконечный кэш для всех типов
+            self.lifetime_hours = None
+        elif isinstance(lifetime_hours, (int, float)):
+            # Одинаковое время для всех типов
+            self.lifetime_hours = {
+                'custom_fields': lifetime_hours,
+                'pipelines': lifetime_hours,
+                'users': lifetime_hours,
+            }
+        else:
+            # Fallback на дефолтные значения
+            self.lifetime_hours = self.DEFAULT_LIFETIMES.copy()
+
+    def get_lifetime(self, data_type):
+        """
+        Получает время жизни кэша для указанного типа данных.
+
+        :param data_type: Тип данных ('custom_fields', 'pipelines', 'users')
+        :return: Время жизни в часах или None для бесконечного кэша
+        """
+        if self.lifetime_hours is None:
+            return None
+        if isinstance(self.lifetime_hours, dict):
+            return self.lifetime_hours.get(data_type, 24)
+        return self.lifetime_hours
+
     @classmethod
     def disabled(cls):
         """Создает конфигурацию с отключенным кэшированием"""
         return cls(enabled=False)
-    
+
     @classmethod
     def memory_only(cls, lifetime_hours=24):
         """Создает конфигурацию с кэшированием только в памяти"""
         return cls(enabled=True, storage='memory', lifetime_hours=lifetime_hours)
-    
+
     @classmethod
-    def file_cache(cls, file=None, lifetime_hours=24):
+    def file_cache(cls, file=None, base_dir=None, lifetime_hours='default'):
         """Создает конфигурацию с файловым кэшированием"""
-        return cls(enabled=True, storage='file', file=file, lifetime_hours=lifetime_hours)
+        return cls(enabled=True, storage='file', base_dir=base_dir, file=file, lifetime_hours=lifetime_hours)
 
 class AmoCRMClient:
     """
@@ -274,12 +318,16 @@ class AmoCRMClient:
                 self.cache_config.file = f"custom_fields_cache_{self.domain}.json"
         
         self.logger.debug(f"AmoCRMClient initialized for domain {self.domain}")
-        
+
         self.token = None
         self.refresh_token = None
         self.expires_at = None
         self.load_token()
+
+        # Memory caches для разных типов данных
         self._custom_fields_mapping = None
+        self._pipelines_cache = None
+        self._users_cache = None
 
     def load_token(self):
         """
@@ -416,6 +464,133 @@ class AmoCRMClient:
 
         return access_token
 
+    def _extract_account_name(self):
+        """
+        Извлекает имя аккаунта из пути к файлу токена.
+
+        Примеры:
+            ~/.amocrm/accounts/bneginskogo.json -> default
+            ~/.amocrm/accounts/bneginskogo_eng.json -> eng
+            ~/.amocrm/accounts/bneginskogo_thai.json -> thai
+
+        :return: Имя аккаунта или 'default'
+        """
+        if not self.token_file:
+            return 'default'
+
+        # Получаем имя файла без расширения
+        filename = os.path.splitext(os.path.basename(self.token_file))[0]
+
+        # Проверяем паттерн: base_name или base_name_account
+        parts = filename.split('_')
+        if len(parts) > 1:
+            # Последняя часть - это имя аккаунта (eng, thai и т.д.)
+            return parts[-1]
+
+        return 'default'
+
+    def _get_cache_file_path(self, data_type):
+        """
+        Получает путь к файлу кэша для указанного типа данных.
+
+        :param data_type: Тип данных ('custom_fields', 'pipelines', 'users')
+        :return: Путь к файлу кэша
+        """
+        # Для custom_fields используем старый путь, если указан (обратная совместимость)
+        if data_type == 'custom_fields' and self.cache_config.file:
+            return self.cache_config.file
+
+        # Создаем директорию кэша, если не существует
+        os.makedirs(self.cache_config.base_dir, exist_ok=True)
+
+        # Формируем имя файла: {account}_{data_type}.json
+        account_name = self._extract_account_name()
+        cache_filename = f"{account_name}_{data_type}.json"
+        return os.path.join(self.cache_config.base_dir, cache_filename)
+
+    def _is_cache_valid(self, data_type, last_updated):
+        """
+        Проверяет, валиден ли кэш на основе времени последнего обновления.
+
+        :param data_type: Тип данных ('custom_fields', 'pipelines', 'users')
+        :param last_updated: Время последнего обновления (timestamp)
+        :return: True если кэш валиден, False если устарел
+        """
+        lifetime = self.cache_config.get_lifetime(data_type)
+
+        if lifetime is None:
+            # Бесконечный кэш
+            return True
+
+        # Проверяем срок жизни
+        return time.time() - last_updated < lifetime * 3600
+
+    def _save_cache(self, data_type, data):
+        """
+        Сохраняет данные в кэш.
+
+        :param data_type: Тип данных ('custom_fields', 'pipelines', 'users')
+        :param data: Данные для сохранения
+        """
+        if not self.cache_config.enabled:
+            self.logger.debug(f"Caching disabled; {data_type} cache not saved.")
+            return
+
+        if self.cache_config.storage != 'file':
+            self.logger.debug(f"Using memory caching; {data_type} cache not saved to file.")
+            return
+
+        cache_file = self._get_cache_file_path(data_type)
+        cache_data = {
+            "last_updated": time.time(),
+            "data": data
+        }
+
+        try:
+            with open(cache_file, "w", encoding="utf-8") as f:
+                json.dump(cache_data, f, ensure_ascii=False, indent=2)
+            self.logger.debug(f"{data_type} cache saved to {cache_file}")
+        except Exception as e:
+            self.logger.error(f"Failed to save {data_type} cache: {e}")
+
+    def _load_cache(self, data_type):
+        """
+        Загружает данные из кэша.
+
+        :param data_type: Тип данных ('custom_fields', 'pipelines', 'users')
+        :return: Кэшированные данные или None
+        """
+        if not self.cache_config.enabled:
+            self.logger.debug(f"Caching disabled; no {data_type} cache loaded.")
+            return None
+
+        if self.cache_config.storage != 'file':
+            self.logger.debug(f"Using memory caching; {data_type} cache kept in memory only.")
+            return None
+
+        cache_file = self._get_cache_file_path(data_type)
+
+        if not os.path.exists(cache_file):
+            self.logger.debug(f"{data_type} cache file not found: {cache_file}")
+            return None
+
+        try:
+            with open(cache_file, "r", encoding="utf-8") as f:
+                cache_data = json.load(f)
+
+            last_updated = cache_data.get("last_updated", 0)
+
+            if not self._is_cache_valid(data_type, last_updated):
+                self.logger.debug(f"{data_type} cache expired.")
+                return None
+
+            self.logger.debug(f"{data_type} cache loaded from {cache_file}")
+            return cache_data.get("data")
+
+        except Exception as e:
+            self.logger.error(f"Error loading {data_type} cache: {e}")
+            return None
+
     def _to_timestamp(self, value: Optional[Union[int, float, str, datetime]]) -> Optional[int]:
         """
         Преобразует значение даты/времени в Unix timestamp.
@@ -701,6 +876,45 @@ class AmoCRMClient:
         """
         return list(self.iter_users(*args, **kwargs))
 
+    def get_users_cached(self, force_update=False):
+        """
+        Возвращает список пользователей с кэшированием (по умолчанию 24 часа).
+
+        Использует трехуровневое кэширование:
+        1. Memory cache (самый быстрый)
+        2. File cache (персистентный)
+        3. API request (если кэш устарел или отсутствует)
+
+        :param force_update: Если True, игнорирует кэш и загружает данные из API
+        :return: Список пользователей
+        """
+        # 1. Проверяем memory cache
+        if not force_update and self._users_cache is not None:
+            self.logger.debug("Using memory-cached users.")
+            return self._users_cache
+
+        # 2. Проверяем file cache
+        if not force_update and self.cache_config.enabled:
+            cached_data = self._load_cache('users')
+            if cached_data is not None:
+                self._users_cache = cached_data
+                self.logger.debug("Users loaded from file cache.")
+                return cached_data
+
+        # 3. Загружаем из API
+        self.logger.debug("Fetching users from API...")
+        users = self.fetch_users()
+
+        # Сохраняем в memory cache
+        self._users_cache = users
+
+        # Сохраняем в file cache
+        if self.cache_config.enabled:
+            self._save_cache('users', users)
+
+        self.logger.debug(f"Fetched {len(users)} users from API.")
+        return users
+
     def iter_pipelines(
         self,
         limit: int = 250,
@@ -785,29 +999,46 @@ class AmoCRMClient:
 
     def get_custom_fields_mapping(self, force_update=False):
         """
-        Возвращает словарь отображения кастомных полей для сделок.
-        Если данные кэшированы и не устарели, возвращает кэш; иначе выполняет запросы для получения данных.
+        Возвращает словарь отображения кастомных полей для сделок с кэшированием (по умолчанию 24 часа).
+
+        Использует трехуровневое кэширование:
+        1. Memory cache (самый быстрый)
+        2. File cache (персистентный)
+        3. API request (если кэш устарел или отсутствует)
+
+        :param force_update: Если True, игнорирует кэш и загружает данные из API
+        :return: Словарь с кастомными полями (ключ - field_id, значение - объект поля)
         """
+        # 1. Проверяем memory cache
         if not force_update and self._custom_fields_mapping is not None:
+            self.logger.debug("Using memory-cached custom fields mapping.")
             return self._custom_fields_mapping
 
-        cache_data = self._load_custom_fields_cache() if self.cache_config.enabled else None
-        if cache_data:
-            last_updated = cache_data.get("last_updated", 0)
-            if self.cache_config.lifetime_hours is not None:
-                if time.time() - last_updated < self.cache_config.lifetime_hours * 3600:
-                    self._custom_fields_mapping = cache_data.get("mapping")
-                    self.logger.debug("Using cached custom fields mapping.")
-                    return self._custom_fields_mapping
-            else:
-                # Бесконечный кэш – не проверяем срок
-                self._custom_fields_mapping = cache_data.get("mapping")
-                self.logger.debug("Using cached custom fields mapping (infinite cache).")
-                return self._custom_fields_mapping
-
+        # 2. Проверяем file cache (с поддержкой старого формата)
+        if not force_update and self.cache_config.enabled:
+            # Пробуем новый формат
+            cached_data = self._load_cache('custom_fields')
+            if cached_data is not None:
+                self._custom_fields_mapping = cached_data
+                self.logger.debug("Custom fields loaded from file cache (new format).")
+                return cached_data
+
+            # Пробуем старый формат для обратной совместимости
+            legacy_cache = self._load_custom_fields_cache()
+            if legacy_cache:
+                mapping = legacy_cache.get("mapping")
+                if mapping:
+                    self._custom_fields_mapping = mapping
+                    self.logger.debug("Custom fields loaded from legacy cache format.")
+                    # Мигрируем в новый формат
+                    self._save_cache('custom_fields', mapping)
+                    return mapping
+
+        # 3. Загружаем из API
+        self.logger.debug("Fetching custom fields from API...")
         mapping = {}
         page = 1
-        total_pages = 1  # Значение по умолчанию
+        total_pages = 1
         while page <= total_pages:
             endpoint = f"/api/v4/leads/custom_fields?limit=250&page={page}"
             response = self._make_request("GET", endpoint)
@@ -820,10 +1051,14 @@ class AmoCRMClient:
             else:
                 break
 
-        self.logger.debug("Custom fields mapping fetched (содержимое маппинга не выводится полностью).")
+        # Сохраняем в memory cache
         self._custom_fields_mapping = mapping
+
+        # Сохраняем в file cache (новый формат)
         if self.cache_config.enabled:
-            self._save_custom_fields_cache(mapping)
+            self._save_cache('custom_fields', mapping)
+
+        self.logger.debug(f"Fetched {len(mapping)} custom fields from API.")
         return mapping
 
     def find_custom_field_id(self, search_term):
@@ -1099,3 +1334,42 @@ class AmoCRMClient:
             return pipelines
         self.logger.error("Не удалось получить воронки из amoCRM")
         raise Exception("Ошибка получения воронок из amoCRM")
+
+    def get_pipelines_cached(self, force_update=False):
+        """
+        Возвращает список воронок с кэшированием (по умолчанию 7 дней).
+
+        Использует трехуровневое кэширование:
+        1. Memory cache (самый быстрый)
+        2. File cache (персистентный)
+        3. API request (если кэш устарел или отсутствует)
+
+        :param force_update: Если True, игнорирует кэш и загружает данные из API
+        :return: Список воронок со статусами
+        """
+        # 1. Проверяем memory cache
+        if not force_update and self._pipelines_cache is not None:
+            self.logger.debug("Using memory-cached pipelines.")
+            return self._pipelines_cache
+
+        # 2. Проверяем file cache
+        if not force_update and self.cache_config.enabled:
+            cached_data = self._load_cache('pipelines')
+            if cached_data is not None:
+                self._pipelines_cache = cached_data
+                self.logger.debug("Pipelines loaded from file cache.")
+                return cached_data
+
+        # 3. Загружаем из API
+        self.logger.debug("Fetching pipelines from API...")
+        pipelines = self.fetch_pipelines()
+
+        # Сохраняем в memory cache
+        self._pipelines_cache = pipelines
+
+        # Сохраняем в file cache
+        if self.cache_config.enabled:
+            self._save_cache('pipelines', pipelines)
+
+        self.logger.debug(f"Fetched {len(pipelines)} pipelines from API.")
+        return pipelines