slow + bugfixes + remove redundant code

README.md

@@ -4,7 +4,7 @@
 ## Основная функциональность
 ### Удобство кода
 - Высокоуровневые списочные методы для сокращения количества необходимого кода. Большинство операций занимают только одну строку кода. Обработка параллельных запросов, упаковка запросов в батчи и многое другое убрано "под капот".
-- Позволяет задавать параметры запроса именно в таком виде, как они приведены в [документации к Bitrix24 REST API](https://dev.1c-bitrix.ru/rest_help/index.php).
+- Позволяет задавать параметры запроса именно в таком виде, как они приведены в [документации к Bitrix24 REST API](https://dev.1c-bitrix.ru/rest_help/index.php). Параметры проверяются на корректность для облегчения отладки.
 - Выполнение запросов автоматически сопровождается прогресс-баром из пакета `tqdm`, иллюстрирующим не только количество обработанных элементов, но и прошедшее и оставшееся время выполнения запроса.
 
 ### Высокая скорость обмена данными
@@ -13,8 +13,9 @@
 - Автоматическая упаковка запросов в батчи сокращает количество требуемых запросов к серверу и ускоряет обмен данными.
 
 ### Избежание отказов сервера
-- Скорость отправки запросов к серверу Битрикс контролируется для избежания ошибки HTTP `503 Service unanavilable`
-- Размера батча контролируется для избежания ошибки HTTP `414 URI too long`
+- Скорость отправки запросов к серверу Битрикс контролируется для избежания ошибки HTTP `503 Service unanavilable`.
+- Размера батча контролируется для избежания ошибки HTTP `414 URI too long`.
+- Если сервер для сложных запросов начинает возвращать `500 HTTP Internal Server Error`, можно в одну строку понизить скорость запроосов.
 
 ## Начало
 Установите модуль через `pip`:
@@ -83,7 +84,7 @@ contacts = b.get_by_ID('crm.deal.contact.item.get',
 tasks = [
     {
         'ID': d['ID'],
-        'NAME': f'{d["ID"]}: {d["NAME"]}'
+        'NAME': f'{d["ID"]} - {d["NAME"]}'
     }
     for d in deals
 ]
@@ -92,25 +93,21 @@ b.call('crm.deal.update', tasks)
 ```
 Метод `call()` возвращает список ответов сервера по каждому элементу переданного списка. 
 
-## Подробнее о классе `Bitrix`
+## Класс `Bitrix`
 Объект класса `Bitrix ` создаётся, чтобы через него выполнять все запросы к серверу Битрикс24. Внутри объекта ведётся учёт скорости отправки запросов к серверу, поэтому важно, чтобы все запросы приложения отправлялись из одного экземпляра `Bitrix`.
 
 Под капотом все методы класса используют параллельные запросы и автоматическое построение батчей, чтобы ускорить получение данных. 
 
 Все методы будут поднимать исключения класса `aiohttp.ClientError`, если сервер Битрикс вернул HTTP-ошибку, и `RuntimeError`, если код ответа был `200`, но ошибка сдержалась в теле ответа сервера (_да, иногда бывает и такое!_).
 
-### Метод ` __init__(self, webhook: str, custom_pool_size: int = 50, requests_per_second: float = 2, cautious: bool = False, autobatch: bool = True, verbose: bool = True):`
+Перед обращением к серверу во всех методах происходит проверка корректности параметров, передаваемых к серверу, и поднимается `TypeError` или `ValueError` при наличии ошибок.
+
+### Метод ` __init__(self, webhook: str, autobatch: bool = True, verbose: bool = True):`
 Создаёт экземпляр объекта `Bitrix`.
 
 #### Параметры 
 * `webhook: str` - URL вебхука, полученного от сервера Битрикс.
-
-* `custom_pool_size: int = 50` - размер пула запросов. По умолчанию 50 запросов - это размер, указанный в официальной документации Битрикс24 на июль 2020 г. (https://dev.1c-bitrix.ru/rest_help/rest_sum/index.php)
-
-* `requests_per_second: float = 2` - скорость отправки запросов. По умолчанию 2 запроса в секунду - предельная скорость, согласно официальной документации.
-
-* `cautious: bool = False` - стартовать, считая, что пул запросов уже исчерпан, и нужно контролировать скорость запросов с первого запроса.
-
+
 * `autobatch: bool = True` - автоматически объединять списки запросов в батчи для ускорения обмена с сервером.
 
 * `verbose: bool = True` - показывать прогрессбар при выполнении запроса.
@@ -174,25 +171,36 @@ contacts = b.get_by_ID('crm.deal.contact.item.get',
 
 `call()` вызывает `method`, последовательно подставляя в параметры запроса все элементы `item_list` и возвращает список ответов сервера для каждого из отправленных запросов.
 
-### Метод `set_requests_per_second(self, requests_per_second: float)`
+## Контекстный менеджер `slow`
 
-Установить скорость запросов к серверу Битрикса, равную 
-`requests_per_second`. Может использоваться для понижения скорости
-запросов припроведении большого количества операций, нагружающих сервер
-(например, создание лидов или сделок), из-за чего он может возвращать
-ошибку `500 Internal Server Error`.
+Иногда, когда серверу Битрикса посылается запрос, отбирающий много ресурсов сервера
+(например, на создание 2500 лидов), то сервер не выдерживает даже стандартных
+темпов подачи запросов, описанных в официальной документации, возвращая `500 Internal Server Error`
+после нескольких первых запросов. 
 
-Обратите внимание, что класс `Bitrix` замеряет время, прошедшее между
-вызовами его списочных методов, чтобы определить, какое количество запросов
-"накопилось" в пуле запросов с момента последнего вызова. Для этого расчета
-используется как раз установленная скорость в запросах в секунду.
-Изменение этого параметра соответственно изменит этот расчет - понижение
-`requests_per_second` понизит расчетную скорость накопления запросов в пуле.
+В такой ситуации помогает замедление запросов при
+помощи контекстного менеджера `slow`:
 
-#### Параметры
-- `requests_per_second` - новая скорость в запросах в секунду
+```python
+# временно снижаем скорость до 0.2 запроса в секунду
+slower_requests_per_second = 0.2
+with fast_bitrix24.slow(slower_requests_per_second):
+    b.call('crm.lead.add', [{} for x in range(2500)])
+
+# а теперь несемся с прежней скоростью
+leads = b.get_all('crm.lead.list')
+...
+```
+
+### `slow(requests_per_second: float = 0.5)`
+Снижает скорость запросов. По вызовам Bitrix, происходящим внутри выхова этого контекстного менеджера:
+* скорость запросов гарантированно не превысит `requests_per_second`
+* механика "пула запросов" отключается - считается, что размер пула равен 0, и запросы подаются равномерно
 
-Возвращает `None`.
+После выхода из контекстного менеджера механика пула восстанавливается, однако пул считается пустым и начинает наполняться с обычной скоростью 2 запроса в секунду.
+
+#### Параметры
+* `requests_per_second: float = 0.5` - требуемая замедленная скорость запросов. По умолчанию 0.5 запросов в секунду.
 
 ## Как связаться с автором
 - e-mail: leshchenko@gmail.com

fast_bitrix24/__init__.py

@@ -1,3 +1,3 @@
 '''Высокоуровневый API для доступа к Битрикс24'''
 
-from fast_bitrix24.bitrix import Bitrix
+from fast_bitrix24.bitrix import Bitrix, slow