b24api 0.1.2__py3-none-any.whl

b24api/__init__.py

@@ -0,0 +1 @@
+from b24api.api import Bitrix24

b24api/api.py

@@ -0,0 +1,273 @@
+import contextlib
+from collections.abc import Generator, Iterable
+from itertools import chain
+from operator import itemgetter
+
+import httpx
+from fast_depends import inject
+from pydantic import ValidationError
+from retry.api import retry_call
+
+from b24api.entity import ApiTypes, BatchResult, ErrorResponse, ListRequest, Request, ResultResponse
+from b24api.error import RetryApiResponseError, RetryHTTPStatusError
+from b24api.future import batched
+from b24api.http import HttpxClient
+from b24api.settings import ApiSettings
+
+
+class Bitrix24:
+    @inject
+    def __init__(self, client: HttpxClient, settings: ApiSettings) -> None:
+        self.client = client
+        self.settings = settings
+
+    def call(self, request: Request) -> ApiTypes:
+        """Call any method (with retries) and return just `result`."""
+        response = retry_call(
+            self._call,
+            fargs=[request],
+            exceptions=(RetryHTTPStatusError, RetryApiResponseError),
+            tries=self.settings.retry_tries,
+            delay=self.settings.retry_delay,
+            backoff=self.settings.retry_backoff,
+        )
+
+        return response.result
+
+    def _call(self, request: Request) -> ResultResponse:
+        """Call any method and return full response."""
+        http_response = self.client.post(
+            f"{self.settings.webhook_url}{request.method}",
+            headers={"Content-Type": "application/json"},
+            json=request.model_dump()["parameters"],
+        )
+
+        try:
+            json_response = http_response.raise_for_status().json()
+        except httpx.HTTPStatusError as error:
+            if http_response.status_code in self.settings.retry_statuses:
+                raise RetryHTTPStatusError(
+                    str(error),
+                    request=error.request,
+                    response=error.response,
+                ) from error
+            raise
+
+        with contextlib.suppress(ValidationError):
+            ErrorResponse.model_validate(json_response).raise_error(self.settings.retry_errors)
+
+        return ResultResponse.model_validate(json_response)
+
+    def batch(
+        self,
+        requests: Iterable[Request],
+        batch_size: int | None = None,
+    ) -> Generator[ApiTypes, None, None]:
+        """Call infinite sequence of methods within batches and return just `result`s."""
+        batch_size = batch_size or self.settings.batch_size
+
+        for batched_requests in batched(requests, batch_size):
+            for response in self._batch(batched_requests):
+                yield response.result
+
+    def _batch(self, requests: Iterable[Request]) -> Generator[ResultResponse, None, None]:
+        """Call batch of methods and return full responses."""
+        commands = {f"_{i}": request for i, request in enumerate(requests)}
+        request = Request(
+            method="batch",
+            parameters={
+                "halt": True,
+                "cmd": {key: request.query for key, request in commands.items()},
+            },
+        )
+
+        result = self.call(request)
+
+        for fix_key in ["result_error", "result_total", "result_next"]:
+            if isinstance(result[fix_key], list) and not result[fix_key]:
+                result[fix_key] = dict(result[fix_key])
+
+        result = BatchResult.model_validate(result)
+
+        for i in range(len(commands)):
+            key = f"_{i}"
+
+            if key in result.result_error:
+                ErrorResponse.model_validate(result.result_error[key]).raise_error(self.settings.retry_errors)
+
+            command = commands[key]
+            if key not in result.result:
+                raise ValueError(
+                    f"Expecting `result` to contain result for command {{`{key}`: {command}}}. Got: {result}",
+                )
+            if key not in result.result_time:
+                raise ValueError(
+                    f"Expecting `result_time` to contain result for command {{`{key}`: {command}}}. Got: {result}",
+                )
+
+            yield ResultResponse(
+                result=result.result[key],
+                time=result.result_time[key],
+                total=result.result_total.get(key, None),
+                next=result.result_next.get(key, None),
+            )
+
+    def list_sequential(
+        self,
+        head_request: Request,
+        list_size: int | None = None,
+    ) -> Generator[ApiTypes, None, None]:
+        """Call `list` method and return full `result`.
+
+        Slow (sequential tail) list gathering for methods without `filter` parameter (e.g. `department.get`).
+        """
+        list_size = list_size or self.settings.list_size
+
+        head_response = self._call(head_request)
+        yield from self._normalize_list(head_response.result)
+
+        if head_response.next and head_response.next != list_size:
+            raise ValueError(f"Expecting list chunk size to be {list_size}. Got: {head_response.next}")
+
+        total = head_response.total or 0
+        for start in range(list_size, total, list_size):
+            tail_request = head_request.model_copy(deep=True)
+            tail_request.parameters |= {"start": start}
+            tail_response = self._call(tail_request)
+
+            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}",
+                )
+
+            yield from self._normalize_list(tail_response.result)
+
+    def list_batched(
+        self,
+        head_request: Request,
+        list_size: int | None = None,
+        batch_size: int | None = None,
+    ) -> Generator[ApiTypes, None, None]:
+        """Call `list` method and return full `result`.
+
+        Faster (batched tail) list gathering for methods without `filter` parameter (e.g. `department.get`).
+        """
+        list_size = list_size or self.settings.list_size
+        batch_size = batch_size or self.settings.batch_size
+
+        head_response = self._call(head_request)
+        yield from self._normalize_list(head_response.result)
+
+        if head_response.next and head_response.next != list_size:
+            raise ValueError(f"Expecting chunk size to be {list_size}. Got: {head_response.next}")
+
+        def _tail_requests() -> Generator[Request, None, None]:
+            total = head_response.total or 0
+            for start in range(list_size, total, list_size):
+                tail_request = head_request.model_copy(deep=True)
+                tail_request.parameters |= {"start": start}
+                yield tail_request
+
+        tail_responses = self.batch(_tail_requests(), batch_size)
+        tail_responses = map(self._normalize_list, tail_responses)
+        tail_responses = chain.from_iterable(tail_responses)
+
+        yield from tail_responses
+
+    def list_batched_no_count(
+        self,
+        request: ListRequest,
+        id_key: str = "ID",
+        list_size: int | None = None,
+        batch_size: int | None = None,
+    ) -> Generator[ApiTypes, None, None]:
+        """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
+
+        select_ = request.parameters.select
+        if "*" not in select_ and id_key not in select_:
+            request.select.append(id_key)
+
+        id_from, id_to = f">={id_key}", f"<{id_key}"
+
+        filter_ = request.parameters.filter
+        if filter_ and (id_from in filter_ or id_to in filter_):
+            raise ValueError(
+                f"Filter parameters `{id_from}` and `{id_to}` are reserved in `list_batched_no_count`",
+            )
+
+        if request.parameters.order:
+            raise ValueError("Ordering parameters are reserved `order`in `list_batched_no_count`")
+
+        head_request = request.model_copy(deep=True)
+        head_request.parameters.start = -1
+        head_request.parameters.order = {"ID": "ASC"}
+
+        tail_request = request.model_copy(deep=True)
+        tail_request.parameters.start = -1
+        tail_request.parameters.order = {"ID": "DESC"}
+
+        head_tail = self.batch([head_request, tail_request])
+        head, tail = tuple(map(self._normalize_list, head_tail))
+
+        get_id = itemgetter(id_key)
+        max_head = max(map(int, map(get_id, head)), default=None)
+        min_tail = min(map(int, map(get_id, tail)), default=None)
+
+        yield from head
+
+        if max_head < min_tail:
+
+            def _body_requests() -> Generator[Request, None, None]:
+                for start in range(max_head + 1, min_tail, list_size):
+                    body_request = request.model_copy(deep=True)
+                    body_request.parameters.start = -1
+                    body_request.parameters.filter[id_from] = start
+                    body_request.parameters.filter[id_to] = min(start + list_size, min_tail)
+                    body_request.parameters.order = {"ID": "ASC"}
+                    yield body_request
+
+            body = self.batch(_body_requests(), batch_size)
+            body = map(self._normalize_list, body)
+            body = chain.from_iterable(body)
+
+            yield from body
+
+        for item in reversed(tail):
+            if int(get_id(item)) > max_head:
+                yield item
+
+    @staticmethod
+    def _normalize_list(result: list | dict[str, list]) -> list:
+        """Normalize `list` method result to `list of items` structure.
+
+        There are two kinds of what `list` method `result` may contain:
+        - a list of items (e.g. `department-get` and `disk.folder.getchildren`),
+        - a dictionary with single item that contains the desired list of items
+            (e.g. `tasks` in `tasks.task.list`).
+        """
+        if not isinstance(result, list | dict):
+            raise TypeError(f"Expecting `result` to be a `list` or a `dict`. Got: {result}")
+
+        if not result:
+            return []
+
+        if isinstance(result, list):
+            return result
+
+        if len(result) != 1:
+            raise TypeError(
+                f"If `result` is a `dict`, expecting single item. Got: {result}",
+            )
+
+        key = next(iter(result))
+        value = result[key]
+
+        if not isinstance(value, list):
+            raise TypeError(f"If `result` is a `dict`, expecting single `list` item. Got: {result}")
+
+        return value

b24api/entity.py

@@ -0,0 +1,91 @@
+from datetime import datetime
+from typing import Self
+
+from pydantic import BaseModel
+
+from b24api.error import ApiResponseError, RetryApiResponseError
+from b24api.query import build_query
+from b24api.type import ApiTypes
+
+
+class Request(BaseModel):
+    """Common request structure."""
+
+    method: str
+    parameters: dict[str, ApiTypes] = {}
+
+    @property
+    def query(self) -> str:
+        if not self.parameters:
+            return self.method
+
+        parameters = self.parameters
+        if isinstance(self.parameters, BaseModel):
+            parameters = self.parameters.model_dump()
+        query = build_query(parameters)
+
+        return f"{self.method}?{query}"
+
+
+class ListRequestParameters(BaseModel):
+    """Parameters of `*.list` requests."""
+
+    select: list[str]
+    filter: dict[str, ApiTypes] | None = None
+    order: dict[str, str] | None = None
+    limit: int | None = None
+    start: int | None = None
+
+
+class ListRequest(Request):
+    """List request structure."""
+
+    parameters: ListRequestParameters = None
+
+
+class ErrorResponse(BaseModel):
+    """API error response."""
+
+    error: str
+    error_description: str | None = None
+
+    def raise_error(self, retry_errors: list[str]) -> Self:
+        if self.error in retry_errors:
+            raise RetryApiResponseError(
+                code=self.error,
+                description=self.error_description,
+            )
+        raise ApiResponseError(
+            code=self.error,
+            description=self.error_description,
+        )
+
+
+class ResponseTime(BaseModel):
+    """Time structure of response."""
+
+    start: float
+    finish: float
+    duration: float
+    processing: float
+    date_start: datetime
+    date_finish: datetime
+    operating_reset_at: float
+    operating: float
+
+
+class ResultResponse(BaseModel):
+    """API data response."""
+
+    result: ApiTypes
+    time: ResponseTime
+    total: int | None = None
+    next: int | None = None
+
+
+class BatchResult(BaseModel):
+    result: dict[str, ApiTypes]
+    result_time: dict[str, ResponseTime]
+    result_error: dict[str, ErrorResponse]
+    result_total: dict[str, int]
+    result_next: dict[str, int]

b24api/error.py

@@ -0,0 +1,22 @@
+import httpx
+
+
+class RetryHTTPStatusError(httpx.HTTPStatusError):
+    """HTTP error that may be retried."""
+
+
+class ApiResponseError(Exception):
+    """API error with description."""
+
+    def __init__(
+        self,
+        *,
+        code: str,
+        description: str | None,
+    ) -> None:
+        message = f"API error [{code}]: {description}"
+        super().__init__(message)
+
+
+class RetryApiResponseError(ApiResponseError):
+    """API error that may be retried."""

b24api/future.py

@@ -0,0 +1,12 @@
+try:
+    from itertools import batched  # python 3.12+
+except ImportError:
+    from collections.abc import Generator, Iterable
+    from itertools import islice
+
+    def batched(iterable: Iterable, n: int) -> Generator[tuple, None, None]:
+        if n < 1:
+            raise ValueError("n must be at least one")
+        iterator = iter(iterable)
+        while batch := tuple(islice(iterator, n)):
+            yield batch

b24api/http.py

@@ -0,0 +1,13 @@
+from collections.abc import Generator
+from typing import Annotated
+
+from fast_depends import Depends
+from httpx import Client
+
+
+def httpx_client() -> Generator[Client, None, None]:
+    client = Client(http2=True)
+    yield client
+
+
+HttpxClient = Annotated[Client, Depends(httpx_client)]

b24api/query.py

@@ -0,0 +1,31 @@
+from datetime import datetime
+from urllib.parse import quote_plus
+
+from b24api.type import ApiTypes
+
+
+def build_query(parameters: dict[int | str, ApiTypes], convention: str = "%s") -> str:
+    query = []
+
+    if parameters is None:
+        return ""
+
+    for key, value in parameters.items():
+        if value is None:
+            continue
+
+        if isinstance(value, list | tuple):
+            value = dict(enumerate(value))  # noqa: PLW2901
+
+        if isinstance(value, dict):
+            subquery = build_query(value, convention % key + "[%s]")
+        else:
+            key_ = quote_plus(convention % key)
+            value_ = value.isoformat() if isinstance(value, datetime) else value
+            # TODO: check date filtering [with .replace(microsecond=0).astimezone()]
+            value_ = quote_plus(str(value_))
+            subquery = f"{key_}={value_}"
+
+        query.append(subquery)
+
+    return "&".join(query)

b24api/settings.py

@@ -0,0 +1,43 @@
+from collections.abc import Generator
+from typing import Annotated
+
+from fast_depends import Depends
+from httpx import codes
+from pydantic import HttpUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="bitrix_24_api_",
+        env_file=".env",
+        extra="ignore",
+    )
+
+    webhook_url: HttpUrl
+
+    retry_statuses: list[int] = (
+        codes.LOCKED,
+        codes.TOO_EARLY,
+        codes.TOO_MANY_REQUESTS,
+        codes.INTERNAL_SERVER_ERROR,
+        codes.BAD_GATEWAY,
+        codes.SERVICE_UNAVAILABLE,
+        codes.INSUFFICIENT_STORAGE,
+    )
+    retry_errors: list[str] = ["query_limit_exceeded", "operation_time_limit"]
+
+    retry_tries: int = 5
+    retry_delay: float = 5
+    retry_backoff: float = 2
+
+    list_size: int = 50
+    batch_size: int = 50
+
+
+def api_settings() -> Generator[Settings, None, None]:
+    settings = Settings()
+    yield settings
+
+
+ApiSettings = Annotated[Settings, Depends(api_settings)]

b24api/type.py

@@ -0,0 +1,5 @@
+from datetime import datetime
+from typing import TypeAlias
+
+# Types allowed in response and request
+ApiTypes: TypeAlias = bool | str | int | float | dict | list | datetime | None

b24api-0.1.2.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shkarupa Alex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

b24api-0.1.2.dist-info/METADATA

@@ -0,0 +1,16 @@
+Metadata-Version: 2.2
+Name: b24api
+Version: 0.1.2
+Summary: Bitrix24 API
+Requires-Python: >=3.11
+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: retry>=0.9.2
+
+# API client for Bitrix24
+
+Low-level API client with multiple strategies for lists gathering. 

b24api-0.1.2.dist-info/RECORD

@@ -0,0 +1,14 @@
+b24api/__init__.py,sha256=EITmZQavNFXCJPFd53sF3imOBajCJnV9bjDrnL-oQdU,31
+b24api/api.py,sha256=QZ1p0vzGf8AFNnbd0irxo2FoBtvX-pTPd2Sb9hQLGJQ,10483
+b24api/entity.py,sha256=3G1EQgxOsmmlXzwVvlNENBKVX-R8nHWb_-gpfyFva6s,2146
+b24api/error.py,sha256=1-3uLKYxYnJyg140vAl-861_SMWr1fh1jbJYN3-HyKY,473
+b24api/future.py,sha256=BJdIfHXDX1IEJCk9X9mcDXGiLXIs-SK5G2RNDMXTL2I,420
+b24api/http.py,sha256=kAhbbgw3LeQqQ7vYjL8WicHBejPDJJzzmVOhb5aTAY4,287
+b24api/query.py,sha256=0M_zjfapNyCdeEOQsy9iA1kUgX2BxH0egnq8dV9kjoQ,926
+b24api/settings.py,sha256=v7IlEXAYmLkVM1zRAw8mp5raNQ88s5HM3AlzuxhkY9Q,1034
+b24api/type.py,sha256=fRhONZS9DCLjuHF6KkqsEtY7tLvzN-vtgY9TnghCw3c,179
+b24api-0.1.2.dist-info/LICENSE,sha256=ssnbHJpzi6Jw6vLkOfnUnF9fLjKIRWGRD3zWBCWYj9k,1070
+b24api-0.1.2.dist-info/METADATA,sha256=OkNLTgf24-DBqFvFO55QCZXWhpS-n38emxs2Pya_WL8,426
+b24api-0.1.2.dist-info/WHEEL,sha256=52BFRY2Up02UkjOa29eZOS2VxUrpPORXg1pkohGGUS8,91
+b24api-0.1.2.dist-info/top_level.txt,sha256=mN7BLg3tL8GQgfBzSoJhjGgXqwKaflyMHCt3XDWIWiI,7
+b24api-0.1.2.dist-info/RECORD,,

b24api-0.1.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (76.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

b24api-0.1.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+b24api