amochka 0.1.3__tar.gz → 0.1.4__tar.gz

{amochka-0.1.3 → amochka-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: amochka
-Version: 0.1.3
+Version: 0.1.4
 Summary: Библиотека для работы с API amoCRM
 Home-page: UNKNOWN
 Author: Timurka

{amochka-0.1.3 → amochka-0.1.4}/amochka/client.py

@@ -19,7 +19,15 @@ RATE_LIMIT = 7  # Максимум 7 запросов в секунду
 class Deal(dict):
     """
     Объект сделки расширяет стандартный словарь данными из custom_fields_values.
-    (Описание класса без изменений)
+
+    Обеспечивает два способа доступа к кастомным полям:
+      1. get(key): при обращении по названию (строкой) или по ID поля (integer)
+         возвращает текстовое значение поля (например, «Дурина Юлия»).
+      2. get_id(key): возвращает идентификатор выбранного варианта (enum_id) для полей типа select.
+         Если в данных enum_id отсутствует, производится поиск в переданной конфигурации полей,
+         сравнение выполняется без учёта регистра и лишних пробелов.
+
+    Параметр custom_fields_config – словарь, где ключи – ID полей, а значения – модели полей.
     """
     def __init__(self, data, custom_fields_config=None):
         super().__init__(data)
@@ -33,9 +41,11 @@ class Deal(dict):
                 values = field.get("values")
                 if field_name and values and isinstance(values, list) and len(values) > 0:
                     key_name = field_name.lower().strip()
-                    # Сохраняем текстовое значение для доступа по названию
-                    self._custom[key_name] = values[0].get("value")
-                    logger.debug(f"Set custom field '{key_name}' = {self._custom[key_name]}")
+                    stored_value = values[0].get("value")
+                    stored_enum_id = values[0].get("enum_id")  # может быть None для некоторых полей
+                    # Сохраняем полную информацию (и для get() и для get_id())
+                    self._custom[key_name] = {"value": stored_value, "enum_id": stored_enum_id}
+                    logger.debug(f"Set custom field '{key_name}' = {{'value': {stored_value}, 'enum_id': {stored_enum_id}}}")
                 field_id = field.get("field_id")
                 if field_id is not None and values and isinstance(values, list) and len(values) > 0:
                     stored_value = values[0].get("value")
@@ -72,7 +82,12 @@ class Deal(dict):
     def get_id(self, key, default=None):
         """
         Возвращает идентификатор выбранного варианта (enum_id) для кастомного поля.
-        (Описание метода без изменений)
+        Если значение enum_id отсутствует в данных, производится поиск в конфигурации кастомных полей,
+        сравнение значения выполняется без учёта регистра и пробелов.
+
+        :param key: Название поля (строка) или ID поля (integer).
+        :param default: Значение по умолчанию, если enum_id не найден.
+        :return: Идентификатор выбранного варианта (целое число) или default.
         """
         stored = None
         if isinstance(key, str):
@@ -105,22 +120,57 @@ class Deal(dict):
 class AmoCRMClient:
     """
     Клиент для работы с API amoCRM.
-    (Описание класса без изменений, за исключением добавления параметра use_file_cache)
+
+    Основные функции:
+      - load_token: Загружает и проверяет токен авторизации.
+      - _make_request: Выполняет HTTP-запрос с учетом ограничения по скорости.
+      - get_deal_by_id: Получает данные сделки по ID и возвращает объект Deal.
+      - get_custom_fields_mapping: Загружает и кэширует список кастомных полей.
+      - find_custom_field_id: Ищет кастомное поле по его названию.
+      - update_lead: Обновляет сделку, включая стандартные и кастомные поля.
+
+    Дополнительно можно задать уровень логирования через параметр log_level,
+    либо полностью отключить логирование, установив disable_logging=True.
     """
-    def __init__(self, base_url, token_file=None, cache_file=None, log_level=logging.INFO, disable_logging=False, use_file_cache=True):
+    def __init__(
+        self, 
+        base_url, 
+        token_file=None, 
+        cache_file=None, 
+        log_level=logging.INFO, 
+        disable_logging=False,
+        cache_enabled=True,
+        cache_storage='file',         # 'file' или 'memory'
+        cache_hours=24                # время жизни кэша в часах, или None для бесконечного кэша
+    ):
         """
-        Инициализирует клиента, задавая базовый URL, токен авторизации и файл кэша для кастомных полей.
+        Инициализирует клиента, задавая базовый URL, токен авторизации и настройки кэша для кастомных полей.
         
-        :param use_file_cache: Если True, кэш будет сохраняться в файл; иначе — только в оперативной памяти.
+        :param base_url: Базовый URL API amoCRM.
+        :param token_file: Файл, содержащий токен авторизации.
+        :param cache_file: Файл для кэширования данных кастомных полей.
+        :param log_level: Уровень логирования (например, logging.DEBUG, logging.INFO).
+        :param disable_logging: Если True, логирование будет отключено.
+        :param cache_enabled: Если False, кэширование отключается (остальные параметры игнорируются).
+        :param cache_storage: 'file' для файлового кэша, 'memory' для кэша только в оперативной памяти.
+        :param cache_hours: Время жизни кэша в часах. Если None – кэш считается бесконечным.
         """
         self.base_url = base_url.rstrip('/')
         domain = self.base_url.split("//")[-1].split(".")[0]
         self.domain = domain
         self.token_file = token_file or os.path.join(os.path.expanduser('~'), '.amocrm_token.json')
-        if not cache_file:
-            cache_file = f"custom_fields_cache_{self.domain}.json"
-        self.cache_file = cache_file
-        self.use_file_cache = use_file_cache
+        
+        # Если выбран файловый кэш, определяем имя файла, иначе он не используется
+        if cache_storage.lower() == 'file':
+            if not cache_file:
+                cache_file = f"custom_fields_cache_{self.domain}.json"
+            self.cache_file = cache_file
+        else:
+            self.cache_file = None
+        self.cache_enabled = cache_enabled
+        self.cache_storage = cache_storage.lower()  # 'file' или 'memory'
+        self.cache_hours = cache_hours
+        
         self.token = self.load_token()
         self._custom_fields_mapping = None
 
@@ -132,7 +182,12 @@ class AmoCRMClient:
         logger.debug(f"AmoCRMClient initialized for domain {self.domain}")
 
     def load_token(self):
-        # Метод без изменений
+        """
+        Загружает токен авторизации из файла или строки, проверяет его срок действия.
+
+        :return: Действительный access_token.
+        :raises Exception: Если токен не найден или истёк.
+        """
         data = None
         if os.path.exists(self.token_file):
             with open(self.token_file, 'r') as f:
@@ -160,7 +215,16 @@ class AmoCRMClient:
     @sleep_and_retry
     @limits(calls=RATE_LIMIT, period=1)
     def _make_request(self, method, endpoint, params=None, data=None):
-        # Метод без изменений
+        """
+        Выполняет HTTP-запрос к API amoCRM с учетом ограничения по скорости (rate limit).
+
+        :param method: HTTP-метод (GET, PATCH, POST, DELETE и т.д.).
+        :param endpoint: Конечная точка API (начинается с /api/v4/).
+        :param params: GET-параметры запроса.
+        :param data: Данные, отправляемые в JSON-формате.
+        :return: Ответ в формате JSON или None (если статус 204).
+        :raises Exception: При получении кода ошибки, отличного от 200/204.
+        """
         url = f"{self.base_url}{endpoint}"
         headers = {
             "Authorization": f"Bearer {self.token}",
@@ -176,7 +240,12 @@ class AmoCRMClient:
         return response.json()
 
     def get_deal_by_id(self, deal_id):
-        # Метод без изменений
+        """
+        Получает данные сделки по её ID и возвращает объект Deal.
+
+        :param deal_id: ID сделки.
+        :return: Объект Deal, включающий данные стандартных и кастомных полей.
+        """
         endpoint = f"/api/v4/leads/{deal_id}"
         params = {'with': 'contacts,companies,catalog_elements,loss_reason,tags'}
         data = self._make_request("GET", endpoint, params=params)
@@ -187,10 +256,13 @@ class AmoCRMClient:
     def _save_custom_fields_cache(self, mapping):
         """
         Сохраняет кэш кастомных полей в файл, если используется файловый кэш.
-        Если файловый кэш не используется, операция пропускается.
+        Если кэширование отключено или выбран кэш в памяти, операция пропускается.
         """
-        if not self.use_file_cache:
-            logger.debug("File caching disabled; cache stored in memory only.")
+        if not self.cache_enabled:
+            logger.debug("Caching disabled; cache not saved.")
+            return
+        if self.cache_storage != 'file':
+            logger.debug("Using memory caching; no file cache saved.")
             return
         cache_data = {"last_updated": time.time(), "mapping": mapping}
         with open(self.cache_file, "w") as f:
@@ -200,10 +272,13 @@ class AmoCRMClient:
     def _load_custom_fields_cache(self):
         """
         Загружает кэш кастомных полей из файла, если используется файловый кэш.
-        Если файловый кэш не используется, возвращает None.
+        Если кэширование отключено или выбран кэш в памяти, возвращает None.
         """
-        if not self.use_file_cache:
-            logger.debug("File caching disabled; no cache loaded from file.")
+        if not self.cache_enabled:
+            logger.debug("Caching disabled; no cache loaded.")
+            return None
+        if self.cache_storage != 'file':
+            logger.debug("Using memory caching; cache will be kept in memory only.")
             return None
         if os.path.exists(self.cache_file):
             with open(self.cache_file, "r") as f:
@@ -216,21 +291,27 @@ class AmoCRMClient:
                     return None
         return None
 
-    def get_custom_fields_mapping(self, force_update=False, cache_duration_hours=24):
+    def get_custom_fields_mapping(self, force_update=False):
         """
         Возвращает словарь отображения кастомных полей для сделок.
         Если данные кэшированы и не устарели, возвращает кэш; иначе выполняет запросы для получения данных.
         """
-        if not force_update:
-            if self._custom_fields_mapping:
-                return self._custom_fields_mapping
-            cache_data = self._load_custom_fields_cache()
-            if cache_data:
-                last_updated = cache_data.get("last_updated", 0)
-                if time.time() - last_updated < cache_duration_hours * 3600:
+        if not force_update and self._custom_fields_mapping is not None:
+            return self._custom_fields_mapping
+
+        cache_data = self._load_custom_fields_cache() if self.cache_enabled else None
+        if cache_data:
+            last_updated = cache_data.get("last_updated", 0)
+            if self.cache_hours is not None:
+                if time.time() - last_updated < self.cache_hours * 3600:
                     self._custom_fields_mapping = cache_data.get("mapping")
                     logger.debug("Using cached custom fields mapping.")
                     return self._custom_fields_mapping
+            else:
+                # Бесконечный кэш – не проверяем срок
+                self._custom_fields_mapping = cache_data.get("mapping")
+                logger.debug("Using cached custom fields mapping (infinite cache).")
+                return self._custom_fields_mapping
 
         mapping = {}
         page = 1
@@ -249,12 +330,16 @@ class AmoCRMClient:
 
         logger.debug("Custom fields mapping fetched (содержимое маппинга не выводится полностью).")
         self._custom_fields_mapping = mapping
-        self._save_custom_fields_cache(mapping)
+        if self.cache_enabled:
+            self._save_custom_fields_cache(mapping)
         return mapping
 
     def find_custom_field_id(self, search_term):
         """
         Ищет кастомное поле по заданному названию (или части названия).
+
+        :param search_term: Строка для поиска по имени поля.
+        :return: Кортеж (field_id, field_obj) если найдено, иначе (None, None).
         """
         mapping = self.get_custom_fields_mapping()
         search_term_lower = search_term.lower().strip()
@@ -272,6 +357,18 @@ class AmoCRMClient:
     def update_lead(self, lead_id, update_fields: dict, tags_to_add: list = None, tags_to_delete: list = None):
         """
         Обновляет сделку, задавая новые значения для стандартных и кастомных полей.
+
+        Для кастомных полей:
+          - Если значение передается как целое число, оно интерпретируется как идентификатор варианта (enum_id)
+            для полей типа select.
+          - Если значение передается как строка, используется ключ "value".
+
+        :param lead_id: ID сделки, которую нужно обновить.
+        :param update_fields: Словарь с полями для обновления. Ключи могут быть стандартными или названием кастомного поля.
+        :param tags_to_add: Список тегов для добавления к сделке.
+        :param tags_to_delete: Список тегов для удаления из сделки.
+        :return: Ответ API в формате JSON.
+        :raises Exception: Если одно из кастомных полей не найдено.
         """
         payload = {}
         standard_fields = {

{amochka-0.1.3 → amochka-0.1.4}/amochka.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: amochka
-Version: 0.1.3
+Version: 0.1.4
 Summary: Библиотека для работы с API amoCRM
 Home-page: UNKNOWN
 Author: Timurka

{amochka-0.1.3 → amochka-0.1.4}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name='amochka',
-    version='0.1.3',
+    version='0.1.4',
     packages=find_packages(),
     install_requires=[
          'requests',