b24api 0.4.1__tar.gz → 0.6.0__tar.gz

{b24api-0.4.1/b24api.egg-info → b24api-0.6.0}/PKG-INFO

@@ -1,14 +1,16 @@
 Metadata-Version: 2.4
 Name: b24api
-Version: 0.4.1
+Version: 0.6.0
 Summary: Bitrix24 API
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: aioitertools>=0.12.0
 Requires-Dist: fast-depends>=2.4.12
 Requires-Dist: httpx[http2]>=0.28.1
-Requires-Dist: pydantic>=2.10.6
-Requires-Dist: pydantic-settings>=2.8.1
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Dist: pytest-asyncio>=1.1.0
 Requires-Dist: tenacity>=9.1.2
 Dynamic: license-file
 
@@ -18,19 +20,31 @@ Low-level API client with multiple strategies for lists gathering.
 All methods support retries.
 
 ## Regular call (any method)
+
 ```python
-from b24api import Bitrix24
+from b24api import SyncBitrix24
 
-b24 = Bitrix24()
+b24 = SyncBitrix24()
 result = b24.call({"method": "user.access", "parameters": {"ACCESS": ["G2", "AU"]}})
 print(result)
 ```
 
+or the same with async
+
+```python
+from b24api import AsyncBitrix24
+
+b24 = AsyncBitrix24()
+result = await b24.call({"method": "user.access", "parameters": {"ACCESS": ["G2", "AU"]}})
+print(result)
+```
+
 ## Batch call (any method, no limit)
+
 ```python
-from b24api import Bitrix24
+from b24api import SyncBitrix24
 
-b24 = Bitrix24()
+b24 = SyncBitrix24()
 
 requests = ({"method": "user.update", "parameters": {"ID": u, "UF_SKYPE": ""}} for u in range(1000))
 result = b24.batch(requests)
@@ -42,9 +56,9 @@ Applicable to list methods with `start=<offset>` support.
 Fetches list chunks one by one.
 
 ```python
-from b24api import Bitrix24
+from b24api import SyncBitrix24
 
-b24 = Bitrix24()
+b24 = SyncBitrix24()
 result = b24.list_sequential({"method": "user.get"})
 print(list(result))
 ```
@@ -52,12 +66,12 @@ print(list(result))
 ## Gathering full list (faster)
 Applicable to list methods with `start=<offset>` support. 
 Fetches first list chunk with regular call, then fetches other chunks with `batch`.
-Approximately 3 times faster then `list_sequential`. 
+Approximately 3 times faster then `list_sequential`.
 
 ```python
-from b24api import Bitrix24
+from b24api import SyncBitrix24
 
-b24 = Bitrix24()
+b24 = SyncBitrix24()
 result = b24.list_batched({"method": "user.get"})
 print(list(result))
 ```
@@ -65,12 +79,12 @@ print(list(result))
 ## Gathering full list (fastest)
 Applicable to list methods with `filter={<parameters>}` support. 
 Fetches first and last list chunk with batch call, then fetches other chunks with `batch`. Doesn't use counting (`start=-1`).
-Approximately 2 times faster then `list_batched`. 
+Approximately 2 times faster then `list_batched`.
 
 ```python
-from b24api import Bitrix24
+from b24api import SyncBitrix24
 
-b24 = Bitrix24()
+b24 = SyncBitrix24()
 result = b24.list_batched_no_count({"method": "user.get"})
 print(list(result))
 ```
@@ -80,9 +94,9 @@ Applicable to list methods with `select=[<fields>]` and `filter={<parameters>}`
 Fetches first and last list chunk with batch call, then fetches other chunks with `batch`. Doesn't use counting (`start=-1`).
 
 ```python
-from b24api import Bitrix24
+from b24api import SyncBitrix24
 
-b24 = Bitrix24()
+b24 = SyncBitrix24()
 deal_ids = [1, 2, 3]  # deals IDs (e.g. from "crm.deal.list" call)
 filter_updates = ({"=ENTITY_ID": i} for i in deal_ids)
 result = b24.reference_batched_no_count(

{b24api-0.4.1 → b24api-0.6.0}/README.md

@@ -4,19 +4,31 @@ Low-level API client with multiple strategies for lists gathering.
 All methods support retries.
 
 ## Regular call (any method)
+
 ```python
-from b24api import Bitrix24
+from b24api import SyncBitrix24
 
-b24 = Bitrix24()
+b24 = SyncBitrix24()
 result = b24.call({"method": "user.access", "parameters": {"ACCESS": ["G2", "AU"]}})
 print(result)
 ```
 
+or the same with async
+
+```python
+from b24api import AsyncBitrix24
+
+b24 = AsyncBitrix24()
+result = await b24.call({"method": "user.access", "parameters": {"ACCESS": ["G2", "AU"]}})
+print(result)
+```
+
 ## Batch call (any method, no limit)
+
 ```python
-from b24api import Bitrix24
+from b24api import SyncBitrix24
 
-b24 = Bitrix24()
+b24 = SyncBitrix24()
 
 requests = ({"method": "user.update", "parameters": {"ID": u, "UF_SKYPE": ""}} for u in range(1000))
 result = b24.batch(requests)
@@ -28,9 +40,9 @@ Applicable to list methods with `start=<offset>` support.
 Fetches list chunks one by one.
 
 ```python
-from b24api import Bitrix24
+from b24api import SyncBitrix24
 
-b24 = Bitrix24()
+b24 = SyncBitrix24()
 result = b24.list_sequential({"method": "user.get"})
 print(list(result))
 ```
@@ -38,12 +50,12 @@ print(list(result))
 ## Gathering full list (faster)
 Applicable to list methods with `start=<offset>` support. 
 Fetches first list chunk with regular call, then fetches other chunks with `batch`.
-Approximately 3 times faster then `list_sequential`. 
+Approximately 3 times faster then `list_sequential`.
 
 ```python
-from b24api import Bitrix24
+from b24api import SyncBitrix24
 
-b24 = Bitrix24()
+b24 = SyncBitrix24()
 result = b24.list_batched({"method": "user.get"})
 print(list(result))
 ```
@@ -51,12 +63,12 @@ print(list(result))
 ## Gathering full list (fastest)
 Applicable to list methods with `filter={<parameters>}` support. 
 Fetches first and last list chunk with batch call, then fetches other chunks with `batch`. Doesn't use counting (`start=-1`).
-Approximately 2 times faster then `list_batched`. 
+Approximately 2 times faster then `list_batched`.
 
 ```python
-from b24api import Bitrix24
+from b24api import SyncBitrix24
 
-b24 = Bitrix24()
+b24 = SyncBitrix24()
 result = b24.list_batched_no_count({"method": "user.get"})
 print(list(result))
 ```
@@ -66,9 +78,9 @@ Applicable to list methods with `select=[<fields>]` and `filter={<parameters>}`
 Fetches first and last list chunk with batch call, then fetches other chunks with `batch`. Doesn't use counting (`start=-1`).
 
 ```python
-from b24api import Bitrix24
+from b24api import SyncBitrix24
 
-b24 = Bitrix24()
+b24 = SyncBitrix24()
 deal_ids = [1, 2, 3]  # deals IDs (e.g. from "crm.deal.list" call)
 filter_updates = ({"=ENTITY_ID": i} for i in deal_ids)
 result = b24.reference_batched_no_count(

b24api-0.6.0/b24api/__init__.py

@@ -0,0 +1,4 @@
+from b24api.async_api import AsyncBitrix24
+from b24api.sync_api import SyncBitrix24
+
+__all__ = ["AsyncBitrix24", "SyncBitrix24"]

b24api-0.6.0/b24api/async_api.py

@@ -0,0 +1,262 @@
+from collections.abc import AsyncGenerator, AsyncIterable, Iterable
+from itertools import batched, islice
+from typing import Any
+
+from aioitertools.itertools import chain as achain
+from httpx import AsyncClient
+from tenacity import AsyncRetrying
+
+from b24api.base_api import BaseBitrix24, BatchedNoCountHelper, ReferenceNoCountHelper
+from b24api.entity import ApiTypes, ListRequest, Request, Response
+
+
+class AsyncBitrix24(BaseBitrix24):
+    @staticmethod
+    def _http() -> type[AsyncClient]:
+        return AsyncClient
+
+    @staticmethod
+    def _retry() -> type[AsyncRetrying]:
+        return AsyncRetrying
+
+    async def _call(self, request: Request | dict) -> Response:
+        """Call any method and return full response."""
+        request = Request.model_validate(request)
+        self.logger.debug("Sending request: %s", request)
+
+        response = await self.http.post(
+            f"{self.settings.webhook_url}{request.method}",
+            headers={"Content-Type": "application/json"},
+            json=request.model_dump(mode="json")["parameters"],
+        )
+        response = self._validate_call_response(request, response)
+        self.logger.debug("Received response: %s", response)
+
+        return response
+
+    async def call(self, request: Request | dict) -> ApiTypes:
+        """Call any method (with retries) and return `result` from response."""
+        return (await self.retry(self._call, request)).result
+
+    async def _batch(self, requests: tuple[Request | dict, ...]) -> list[Response]:
+        """Call limited batch of methods and return full responses."""
+        commands, request = self._batch_requests(requests)
+
+        response = await self._call(request)
+
+        return self._batch_responses(commands, response)
+
+    async def batch(
+        self,
+        requests: Iterable[Request | dict | tuple[Request | dict, Any]],
+        *,
+        batch_size: int | None = None,
+        list_method: bool = False,
+        with_payload: bool = False,
+    ) -> AsyncGenerator[ApiTypes | tuple[ApiTypes, Any]]:
+        """Call unlimited sequence of methods within batches and return `result` from responses."""
+        batch_size = batch_size or self.settings.batch_size
+
+        for batched_requests in batched(requests, batch_size):
+            if with_payload:
+                batched_requests, batched_payloads = zip(*batched_requests, strict=True)
+            else:
+                batched_payloads = None
+
+            batched_responses = await self.retry(self._batch, batched_requests)
+
+            for i, response in enumerate(batched_responses):
+                result = response.list_result if list_method else response.result
+                if with_payload:
+                    yield result, batched_payloads[i]
+                else:
+                    yield result
+
+    async def list_sequential(
+        self,
+        request: Request | dict,
+        *,
+        list_size: int | None = None,
+    ) -> AsyncGenerator[ApiTypes]:
+        """Call `list` method and return full `result`.
+
+        Slow (sequential tail) list gathering for methods without `filter` parameter (e.g. `department.get`).
+        """
+        request = Request.model_validate(request)
+        list_size = list_size or self.settings.list_size
+
+        head_request = request.model_copy(deep=True)
+        head_request.parameters["start"] = 0
+
+        head_response = await self.retry(self._call, head_request)
+        for item in head_response.list_result:
+            yield item
+
+        tail_requests = self._list_tail_requests(head_request, head_response, list_size=list_size)
+        for tail_request in tail_requests:
+            tail_response = await self.retry(self._call, tail_request)
+
+            start = tail_request.parameters["start"]
+            if tail_response.next and tail_response.next != start + list_size:
+                raise ValueError(
+                    f"Expecting next list chunk to start at {start + list_size}. Got: {tail_response.next}",
+                )
+
+            for item in tail_response.list_result:
+                yield item
+
+    async def list_batched(
+        self,
+        request: Request | dict,
+        *,
+        list_size: int | None = None,
+        batch_size: int | None = None,
+    ) -> AsyncGenerator[ApiTypes]:
+        """Call `list` method and return full `result`.
+
+        Faster (batched tail) list gathering for methods without `filter` parameter (e.g. `department.get`).
+        """
+        request = Request.model_validate(request)
+        list_size = list_size or self.settings.list_size
+        batch_size = batch_size or self.settings.batch_size
+
+        head_request = request.model_copy(deep=True)
+        head_request.parameters["start"] = 0
+
+        head_response = await self.retry(self._call, head_request)
+        for item in head_response.list_result:
+            yield item
+
+        tail_requests = self._list_tail_requests(head_request, head_response, list_size=list_size)
+        tail_responses = self.batch(tail_requests, batch_size=batch_size, list_method=True)
+        async for tail_response in tail_responses:
+            for item in tail_response:
+                yield item
+
+    async def list_batched_no_count(
+        self,
+        request: ListRequest | dict,
+        *,
+        id_key: str = "ID",
+        list_size: int | None = None,
+        batch_size: int | None = None,
+    ) -> AsyncGenerator[ApiTypes]:
+        """Call `list` method and return full `result`.
+
+        Fastest (batched, no count) list gathering for methods with `filter` parameter (e.g. `crm.lead.list`).
+        """
+        list_size = list_size or self.settings.list_size
+        batch_size = batch_size or self.settings.batch_size
+
+        batched_helper = BatchedNoCountHelper(request, id_key, list_size, batch_size)
+
+        boundary_requests = batched_helper.head_request(), batched_helper.tail_request()
+        head_result, tail_result = await self.retry(self._batch, boundary_requests)
+        for item in head_result.list_result:
+            yield item
+
+        body_requests = batched_helper.body_requests(head_result, tail_result)
+        body_results = self.batch(body_requests, batch_size=batch_size, list_method=True)
+        async for item in achain.from_iterable(body_results):
+            yield item
+
+        for item in batched_helper.tail_results(head_result, tail_result):
+            yield item
+
+    async def reference_batched_no_count(  # noqa: PLR0913
+        self,
+        request: ListRequest | dict,
+        updates: Iterable[dict | tuple[dict, Any]] | AsyncIterable[dict | tuple[dict, Any]],
+        *,
+        id_key: str = "ID",
+        list_size: int | None = None,
+        batch_size: int | None = None,
+        with_payload: bool = False,
+    ) -> AsyncGenerator[ApiTypes | tuple[ApiTypes, Any]]:
+        """Call `list` method with reference `updates` for `filter` and return full `result`.
+
+        Fastest (batched, no count) list gathering for methods with `filter` parameter and required `reference`
+        (e.g. `crm.timeline.comment.list`).
+        """
+        list_size = list_size or self.settings.list_size
+        batch_size = batch_size or self.settings.batch_size
+
+        reference_helper = ReferenceNoCountHelper(request, updates, id_key, list_size, batch_size, with_payload)
+
+        if isinstance(updates, AsyncIterable):
+            async for item in self._reference_batched_no_count_async_updates(reference_helper):
+                yield item
+        else:
+            async for item in self._reference_batched_no_count_sync_updates(reference_helper):
+                yield item
+
+    async def _reference_batched_no_count_async_updates(
+        self,
+        reference_helper: ReferenceNoCountHelper,
+    ) -> AsyncGenerator[ApiTypes | tuple[ApiTypes, Any]]:
+        head_requests, body_requests = (), []
+        async for tail_request in reference_helper.atail_requests():
+            body_requests.append(tail_request)
+            if len(head_requests) + len(body_requests) < reference_helper.batch_size:
+                continue
+
+            body_results, head_requests = await self._reference_batched_no_count_async_updates_batch(
+                reference_helper,
+                body_requests,
+                head_requests,
+            )
+            body_requests = []
+            for item in reference_helper.body_results(body_results):
+                yield item
+
+        while head_requests or body_requests:
+            body_results, head_requests = await self._reference_batched_no_count_async_updates_batch(
+                reference_helper,
+                body_requests,
+                head_requests,
+            )
+            body_requests = []
+            for item in reference_helper.body_results(body_results):
+                yield item
+
+    async def _reference_batched_no_count_async_updates_batch(
+        self,
+        reference_helper: ReferenceNoCountHelper,
+        body_requests: list[ListRequest],
+        head_requests: tuple[ListRequest, ...],
+    ) -> tuple[list[ApiTypes], tuple[ListRequest, ...]]:
+        body_requests = head_requests + tuple(body_requests)
+        body_results = [
+            r
+            async for r in self.batch(
+                body_requests,
+                batch_size=reference_helper.batch_size,
+                list_method=True,
+                with_payload=reference_helper.with_payload,
+            )
+        ]
+        head_requests = reference_helper.head_requests(body_requests, body_results)
+
+        return body_results, head_requests
+
+    async def _reference_batched_no_count_sync_updates(
+        self,
+        reference_helper: ReferenceNoCountHelper,
+    ) -> AsyncGenerator[ApiTypes | tuple[ApiTypes, Any]]:
+        head_requests = ()
+        tail_requests = iter(reference_helper.tail_requests())
+        while body_requests := head_requests + tuple(
+            islice(tail_requests, reference_helper.batch_size - len(head_requests)),
+        ):
+            body_results = [
+                r
+                async for r in self.batch(
+                    body_requests,
+                    batch_size=reference_helper.batch_size,
+                    list_method=True,
+                    with_payload=reference_helper.with_payload,
+                )
+            ]
+            head_requests = reference_helper.head_requests(body_requests, body_results)
+            for item in reference_helper.body_results(body_results):
+                yield item