Metadata-Version: 2.1
Name: fast-bitrix24
Version: 0.2
Summary: A high-level Python SDK for Bitrix24 REST API aiming for speed of high volume transactions. Async operations, automatic batching and traffic throttling to prevent server rejections.
Home-page: https://github.com/leshchenko1979/lxutils
Author: Alexey Leshchenko
Author-email: leshchenko@gmail.com
License: MIT
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: aiohttp
Requires-Dist: asyncio
Requires-Dist: tqdm
Requires-Dist: more-itertools

# fast-bitrix24
Высокоуровневый API для Python 3.7+ для быстрого получения данных от Битрикс24 через REST API.

## Основная функциональность
### Удобство кода
- Высокоуровневые списочные методы для сокращения количества необходимого кода. Большинство операций занимают только одну строку кода.
- Позволяет задавать параметры запроса именно в таком виде, как они приведены в [документации к Bitrix24 REST API](https://dev.1c-bitrix.ru/rest_help/index.php).
- Выполнение запросов автоматически сопровождается прогресс-баром из пакета `tqdm`, иллюстрирующим не только количество обработанных элементов, но и прошедшее и оставшееся время выполнения запроса.

### Высокая скорость обмена данными
- На больших списках скорость обмена данными с сервером достигает тысяч элементов в секунду.
- Использование асинхронных запросов через `asyncio` и `aiohttp` позволяет экономить время, делая несколько запросов к серверу параллельно.
- Автоматическая упаковка запросов в батчи сокращает количество требуемых запросов к серверу и ускоряет обмен данными.

### Избежание отказов сервера
- Скорость отправки запросов к серверу Битрикс контролируется для избежания ошибки HTTP `503 Service unanavilable`
- Размера батча контролируется для избежания ошибки HTTP `414 URI too long`

## Начало
Установите модуль через `pip`:
```shell
pip install fast_bitrix24
```

Далее в python:

```python
from fast_bitrix24 import Bitrix

# замените на ваш вебхук для доступа к Bitrix24
webhook = "https://your_domain.bitrix24.ru/rest/1/your_code/"
b = Bitrix(webhook)
```

Методы полученного объекта `b` в дальнейшем используются для взаимодействия с сервером Битрикс24.

## Использование

### `get_all()`

Чтобы получить полностью список сущностей, используйте метод ```get_all()```:

```python
# список пользователей
users = b.get_all('user.get')
```

Метод `get_all()` возвращает список, где каждый элемент списка является словарем, описывающим одну сущность из запрощенного списка.

Вы также можете использовать параметр ```details```, чтобы кастомизировать запрос:

```python
# список сделок в работе, включая пользовательские поля
deals = b.get_all('crm.deal.get', details={
    'select': ['*', 'UF_*'],
    'filter': ['CLOSED': 'N']
})
```

### `get_by_ID()`
Если у вас есть список ID сущностей, то вы можете получить их при помощи метода `get_by_ID()`:

```python
'''
получим список всех контактов, привзяанных к сдлекам, в виде
[
    (ID сделки1, [контакт1, контакт2, ...]), 
    (ID сделки2, [контакт1, контакт2, ...]), 
    ...
]
'''

contacts = b.get_by_ID('crm.deal.contact.item.get',
    [d['ID'] for d in deals])
```
Метод `get_by_ID()` возвращает список кортежей вида `(ID, result)`, где `result` - ответ сервера относительно этого `ID`.

### `post()`
Чтобы создавать, изменять или удалять сущности, используйте метод `post()`:

```python
# вставим в начало названия сделки ее ID
tasks = [
    {
        'ID': d['ID'],
        'NAME': f'{d["ID"]}: {d["name"]}'
    }
    for d in deals
]

b.post('crm.deal.update', tasks)
```
Метод `post()` возвращает список ответов сервера по каждому элементу переданного списка. 

## Как связаться с автором
- e-mail: leshchenko@gmail.com
- telegram: https://t.me/@leshchenko1979

