b24api 0.4.0__tar.gz → 0.5.0__tar.gz

{b24api-0.4.0/b24api.egg-info → b24api-0.5.0}/PKG-INFO

@@ -1,14 +1,15 @@
 Metadata-Version: 2.4
 Name: b24api
-Version: 0.4.0
+Version: 0.5.0
 Summary: Bitrix24 API
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE
 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 +19,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 +55,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 +65,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 +78,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 +93,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.0 → b24api-0.5.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.5.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.5.0/b24api/async_api.py

@@ -0,0 +1,221 @@
+from collections.abc import AsyncGenerator, Iterable
+from itertools import batched, islice
+from operator import itemgetter
+from typing import Any
+
+from httpx import AsyncClient
+from tenacity import AsyncRetrying
+
+from b24api.base_api import BaseBitrix24
+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) -> ApiTypes:
+        """Call any method (with retries) and return `result` from response."""
+        return (await self.retry(self._call, request)).result
+
+    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._estimate_call_response(request, response)
+        self.logger.debug("Received response: %s", response)
+
+        return response
+
+    async def batch(
+        self,
+        requests: Iterable[Request | dict | tuple[Request | dict, Any]],
+        *,
+        batch_size: int | None = None,
+        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):
+                if with_payload:
+                    yield response.result, batched_payloads[i]
+                else:
+                    yield response.result
+
+    async def _batch(self, requests: Iterable[Request | dict]) -> list[Response]:
+        """Call limited batch of methods and return full responses."""
+        commands, request = self._estimate_batch_requests(requests)
+
+        result = (await self._call(request)).result
+
+        return self._estimate_batch_responses(commands, 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 self._fix_list_result(head_response.result):
+            yield item
+
+        tail_requests = self._estimate_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 self._fix_list_result(tail_response.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 self._fix_list_result(head_response.result):
+            yield item
+
+        tail_requests = self._estimate_list_tail_requests(head_request, head_response, list_size=list_size)
+        async for tail_response in self.batch(tail_requests, batch_size=batch_size):
+            for item in self._fix_list_result(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
+
+        head_request, tail_request = self._estimate_list_batched_no_count_boundary_requests(request, id_key)
+
+        boundary_results = [r async for r in self.batch([head_request, tail_request], batch_size=batch_size)]
+        head_result, tail_result = tuple(map(self._fix_list_result, boundary_results))
+        for item in head_result:
+            yield item
+
+        body_requests = self._estimate_list_batched_no_count_body_requests(
+            head_request,
+            head_result,
+            tail_result,
+            id_key,
+            list_size,
+        )
+        async for body_result in self.batch(body_requests, batch_size=batch_size):
+            body_result = self._fix_list_result(body_result)
+            for item in body_result:
+                yield item
+
+        get_id = itemgetter(id_key)
+        max_head_id = max(map(int, map(get_id, head_result)), default=None)
+        for item in reversed(tail_result):
+            if int(get_id(item)) > max_head_id:
+                yield item
+
+    async def reference_batched_no_count(
+        self,
+        request: ListRequest | dict,
+        updates: Iterable[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
+
+        head_requests = []
+        tail_requests = iter(
+            self._estimate_reference_batched_no_count_tail_requests(
+                request,
+                updates,
+                id_key,
+                with_payload,
+            ),
+        )
+        while body_requests := head_requests + list(islice(tail_requests, batch_size - len(head_requests))):
+            if with_payload:
+                body_requests, body_payloads = zip(*body_requests, strict=True)
+            else:
+                body_payloads = None
+
+            head_requests = []
+
+            i = 0
+            async for body_result in self.batch(body_requests, batch_size=batch_size):
+                body_request = body_requests[i]
+                body_payload = body_payloads[i] if with_payload else None
+                head_requests, body_result = self._estimate_reference_batched_no_count_result_next(
+                    body_request,
+                    body_result,
+                    body_payload,
+                    id_key,
+                    list_size,
+                    with_payload,
+                )
+                for item in body_result:
+                    yield item
+                i += 1