b24pysdk 0.1.0a1__tar.gz

b24pysdk-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bitrix24
+
+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.

b24pysdk-0.1.0a1/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.1
+Name: b24pysdk
+Version: 0.1.0a1
+Summary: An official Python library for the Bitrix24 REST API
+Author-email: Bitrix24 <pypi@bitrixsoft.com>
+License: MIT License
+        
+        Copyright (c) 2025 Bitrix24
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/bitrix24/b24pysdk
+Keywords: bitrix24,rest,api
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3,>=2.32.4
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# Introduction
+
+---
+
+B24PySDK is the official library for working with the Bitrix24 REST API in Python.
+
+It offers following advantages:
+1. Supports authorization via tokens and webhooks;
+2. Allows to pass arguments and retreive response data as native Python types;
+3. Utilizes type hints to show possible method arguments and their types;
+4. Checks that passed arguments have valid types.
+
+# Documentation
+
+---
+
+The REST API documentation can be found on [Bitrix24 REST API](https://apidocs.bitrix24.com/).
+
+# Quickstart
+
+---
+
+This section provides a short guide to help you get started with B24PySDK.
+
+The following examples illustrate common scenarios when using the library.
+## Calling an API method
+
+---
+
+To call Bitrix API, import Client and BitrixWebhook or BitrixToken classes from the library and create class objects.
+There are two ways of calling API methods via library.
+1. Using a permanent incoming local webhook code: https://apidocs.bitrix24.com/local-integrations/local-webhooks.html
+
+```python
+from b24pysdk import BitrixWebhook, Client
+
+bitrix_token = BitrixWebhook(domain="your_bitrix_portal", auth_token="key_of_your_webhook")
+client = Client(bitrix_token)
+```
+
+2. Using a temporary OAuth 2.0 authorization token: https://apidocs.bitrix24.com/api-reference/oauth/index.html
+
+```python
+from b24pysdk import BitrixToken, Client, BitrixApp
+
+bitrix_app = BitrixApp(client_id="app_code", client_secret="app_key")
+bitrix_token = BitrixToken(
+    domain="your_bitrix_portal", 
+    auth_token="key_of_your_webhook", 
+    refresh_token="refresh_token_of_the_app", # optional parameter
+    bitrix_app=bitrix_app,
+)
+client = Client(bitrix_token)
+```
+
+Client class is your access point to the API. All supported methods can be called using properties of created instance.
+
+For example, to get a description of deal fields we can use REST method crm.deal.fields like so:
+```python
+response = client.crm.deal.fields()
+```
+
+## Passing parameters in API calls
+
+---
+
+Most of Bitrix REST API methods allow you to pass some arguments to them. In order to send them using SDK, simply pass these arguments as positional or named arguments to the corresponding Python function.
+
+To illustrate, we can update a deal by calling: 
+```python
+response = client.crm.deal.get(bitrix_id=2)
+```
+
+## Retrieving results of the call
+
+---
+
+B24PySDK uses deferred method calls. To invoke a method and obtain its result, access the corresponding property. 
+The JSON response retrieved from the server is automatically parsed and stored in an object: 
+response.result contains the value returned by the API method, while response.time provides the execution time of the request.
+```python
+from b24pysdk import BitrixWebhook, Client
+
+bitrix_token = BitrixWebhook(domain="your_bitrix_portal", auth_token="key_of_your_webhook")
+client = Client(bitrix_token)
+
+response = client.crm.deal.update(bitrix_id=10, fields={'TITLE': 'New title'})
+print(f'Updated successfully: {response.result}')
+print(f'Call took {response.time.duration} seconds')
+```
+```
+Updated successfully: True
+Call took 0.40396690368652344 seconds
+```
+
+### Retrieving records with list methods
+
+For list methods, you can use .as_list() and .as_list_fast() to explicitly retrieve all records.
+> Documentation: https://apidocs.bitrix24.com/api-reference/performance/huge-data.html
+
+By default, calling .list() returns up to 50 records only.
+```python
+response = client.crm.deal.list()
+deals = response.result  # up to 50 records
+```
+
+The .as_list() method retrieves all records by automatically.
+```python
+response = client.crm.deal.list()
+deals = response.as_list().result  # full list of records
+```
+
+The .as_list_fast() method is optimized for large datasets. 
+It uses a more efficient algorithm and is recommended when receiving many records.
+```python
+response = client.crm.deal.list()
+deals = response.as_list_fast().result  # generator
+for deal in deals:  # requests are made lazily during iteration
+    print(deal)
+```
+
+## Library use via abstract classes
+
+Instead of BitrixApp and BitrixToken, you can use their abstract class versions with frameworks and ORM libraries.
+When using these abstract classes, the programmer is responsible for declaring the instance attributes and storing them.
+
+Examples of the available abstract classes are AbstractBitrixApp, AbstractBitrixAppLocal, AbstractBitrixToken and AbstractBitrixTokenLocal.

b24pysdk-0.1.0a1/README.md

@@ -0,0 +1,127 @@
+# Introduction
+
+---
+
+B24PySDK is the official library for working with the Bitrix24 REST API in Python.
+
+It offers following advantages:
+1. Supports authorization via tokens and webhooks;
+2. Allows to pass arguments and retreive response data as native Python types;
+3. Utilizes type hints to show possible method arguments and their types;
+4. Checks that passed arguments have valid types.
+
+# Documentation
+
+---
+
+The REST API documentation can be found on [Bitrix24 REST API](https://apidocs.bitrix24.com/).
+
+# Quickstart
+
+---
+
+This section provides a short guide to help you get started with B24PySDK.
+
+The following examples illustrate common scenarios when using the library.
+## Calling an API method
+
+---
+
+To call Bitrix API, import Client and BitrixWebhook or BitrixToken classes from the library and create class objects.
+There are two ways of calling API methods via library.
+1. Using a permanent incoming local webhook code: https://apidocs.bitrix24.com/local-integrations/local-webhooks.html
+
+```python
+from b24pysdk import BitrixWebhook, Client
+
+bitrix_token = BitrixWebhook(domain="your_bitrix_portal", auth_token="key_of_your_webhook")
+client = Client(bitrix_token)
+```
+
+2. Using a temporary OAuth 2.0 authorization token: https://apidocs.bitrix24.com/api-reference/oauth/index.html
+
+```python
+from b24pysdk import BitrixToken, Client, BitrixApp
+
+bitrix_app = BitrixApp(client_id="app_code", client_secret="app_key")
+bitrix_token = BitrixToken(
+    domain="your_bitrix_portal", 
+    auth_token="key_of_your_webhook", 
+    refresh_token="refresh_token_of_the_app", # optional parameter
+    bitrix_app=bitrix_app,
+)
+client = Client(bitrix_token)
+```
+
+Client class is your access point to the API. All supported methods can be called using properties of created instance.
+
+For example, to get a description of deal fields we can use REST method crm.deal.fields like so:
+```python
+response = client.crm.deal.fields()
+```
+
+## Passing parameters in API calls
+
+---
+
+Most of Bitrix REST API methods allow you to pass some arguments to them. In order to send them using SDK, simply pass these arguments as positional or named arguments to the corresponding Python function.
+
+To illustrate, we can update a deal by calling: 
+```python
+response = client.crm.deal.get(bitrix_id=2)
+```
+
+## Retrieving results of the call
+
+---
+
+B24PySDK uses deferred method calls. To invoke a method and obtain its result, access the corresponding property. 
+The JSON response retrieved from the server is automatically parsed and stored in an object: 
+response.result contains the value returned by the API method, while response.time provides the execution time of the request.
+```python
+from b24pysdk import BitrixWebhook, Client
+
+bitrix_token = BitrixWebhook(domain="your_bitrix_portal", auth_token="key_of_your_webhook")
+client = Client(bitrix_token)
+
+response = client.crm.deal.update(bitrix_id=10, fields={'TITLE': 'New title'})
+print(f'Updated successfully: {response.result}')
+print(f'Call took {response.time.duration} seconds')
+```
+```
+Updated successfully: True
+Call took 0.40396690368652344 seconds
+```
+
+### Retrieving records with list methods
+
+For list methods, you can use .as_list() and .as_list_fast() to explicitly retrieve all records.
+> Documentation: https://apidocs.bitrix24.com/api-reference/performance/huge-data.html
+
+By default, calling .list() returns up to 50 records only.
+```python
+response = client.crm.deal.list()
+deals = response.result  # up to 50 records
+```
+
+The .as_list() method retrieves all records by automatically.
+```python
+response = client.crm.deal.list()
+deals = response.as_list().result  # full list of records
+```
+
+The .as_list_fast() method is optimized for large datasets. 
+It uses a more efficient algorithm and is recommended when receiving many records.
+```python
+response = client.crm.deal.list()
+deals = response.as_list_fast().result  # generator
+for deal in deals:  # requests are made lazily during iteration
+    print(deal)
+```
+
+## Library use via abstract classes
+
+Instead of BitrixApp and BitrixToken, you can use their abstract class versions with frameworks and ORM libraries.
+When using these abstract classes, the programmer is responsible for declaring the instance attributes and storing them.
+
+Examples of the available abstract classes are AbstractBitrixApp, AbstractBitrixAppLocal, AbstractBitrixToken and AbstractBitrixTokenLocal.

b24pysdk-0.1.0a1/b24pysdk/__init__.py

@@ -0,0 +1,32 @@
+from ._client import Client
+from ._config import Config
+from ._version import __title__, __version__
+from .bitrix_api import (
+    AbstractBitrixApp,
+    AbstractBitrixAppLocal,
+    AbstractBitrixToken,
+    AbstractBitrixTokenLocal,
+    BitrixApp,
+    BitrixAppLocal,
+    BitrixToken,
+    BitrixTokenLocal,
+    BitrixWebhook,
+)
+from .version import SDK_VERSION
+
+__all__ = [
+    "SDK_VERSION",
+    "AbstractBitrixApp",
+    "AbstractBitrixAppLocal",
+    "AbstractBitrixToken",
+    "AbstractBitrixTokenLocal",
+    "BitrixApp",
+    "BitrixAppLocal",
+    "BitrixToken",
+    "BitrixTokenLocal",
+    "BitrixWebhook",
+    "Client",
+    "Config",
+    "__title__",
+    "__version__",
+]

b24pysdk-0.1.0a1/b24pysdk/__main__.py

@@ -0,0 +1,10 @@
+from b24pysdk.version import SDK_VERSION
+
+
+def main():
+    """Prints version information for python-telegram-bot, the Bot API and Python."""
+    print(f"b24pysdk version {SDK_VERSION}")
+
+
+if __name__ == "__main__":
+    main()

b24pysdk-0.1.0a1/b24pysdk/_client.py

@@ -0,0 +1,110 @@
+from typing import Dict, Mapping, Sequence, Union, overload
+
+from . import scopes
+from .bitrix_api.bitrix_token import AbstractBitrixToken
+from .bitrix_api.classes import BitrixAPIBatchesRequest, BitrixAPIBatchRequest, BitrixAPIRequest
+from .utils.types import Key, Timeout
+
+
+class Client:
+    """"""
+
+    __slots__ = (
+        "_bitrix_token",
+        "_kwargs",
+        "crm",
+        "department",
+        "socialnetwork",
+        "user",
+    )
+
+    _bitrix_token: AbstractBitrixToken
+    _kwargs: Dict
+    crm: scopes.CRM
+    department: scopes.Department
+    socialnetwork: scopes.Socialnetwork
+    user: scopes.User
+
+    def __init__(
+            self,
+            bitrix_token: AbstractBitrixToken,
+            **kwargs,
+    ):
+        self._bitrix_token = bitrix_token
+        self._kwargs = kwargs
+        self.crm = scopes.CRM(self)
+        self.department = scopes.Department(self)
+        self.socialnetwork = scopes.Socialnetwork(self)
+        self.user = scopes.User(self)
+
+    def __str__(self):
+        return f"<Client of portal {self._bitrix_token.domain}>"
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}(bitrix_token={self._bitrix_token})"
+
+    @overload
+    def call_batch(
+            self,
+            bitrix_api_requests: Mapping[Key, BitrixAPIRequest],
+            halt: bool = False,
+            ignore_size_limit: bool = False,
+            timeout: Timeout = None,
+    ) -> BitrixAPIBatchRequest: ...
+
+    @overload
+    def call_batch(
+            self,
+            bitrix_api_requests: Sequence[BitrixAPIRequest],
+            halt: bool = False,
+            ignore_size_limit: bool = False,
+            timeout: Timeout = None,
+    ) -> BitrixAPIBatchRequest: ...
+
+    def call_batch(
+            self,
+            bitrix_api_requests: Union[Mapping[Key, BitrixAPIRequest], Sequence[BitrixAPIRequest]],
+            halt: bool = False,
+            ignore_size_limit: bool = False,
+            timeout: Timeout = None,
+    ) -> BitrixAPIBatchRequest:
+        """"""
+        return BitrixAPIBatchRequest(
+            bitrix_token=self._bitrix_token,
+            bitrix_api_requests=bitrix_api_requests,
+            halt=halt,
+            ignore_size_limit=ignore_size_limit,
+            timeout=timeout,
+            **self._kwargs,
+        )
+
+    @overload
+    def call_batches(
+            self,
+            bitrix_api_requests: Mapping[Key, BitrixAPIRequest],
+            halt: bool = False,
+            timeout: Timeout = None,
+    ) -> BitrixAPIBatchRequest: ...
+
+    @overload
+    def call_batches(
+            self,
+            bitrix_api_requests: Sequence[BitrixAPIRequest],
+            halt: bool = False,
+            timeout: Timeout = None,
+    ) -> BitrixAPIBatchRequest: ...
+
+    def call_batches(
+            self,
+            bitrix_api_requests: Union[Mapping[Key, BitrixAPIRequest], Sequence[BitrixAPIRequest]],
+            halt: bool = False,
+            timeout: Timeout = None,
+    ) -> BitrixAPIBatchesRequest:
+        """"""
+        return BitrixAPIBatchesRequest(
+            bitrix_token=self._bitrix_token,
+            bitrix_api_requests=bitrix_api_requests,
+            halt=halt,
+            timeout=timeout,
+            **self._kwargs,
+        )

b24pysdk-0.1.0a1/b24pysdk/_config.py

@@ -0,0 +1,96 @@
+import threading
+
+from ._constants import DEFAULT_TIMEOUT, INITIAL_RETRY_DELAY, MAX_RETRIES, RETRY_DELAY_INCREMENT
+from .utils.types import DefaultTimeout, Number
+
+
+class _LocalConfig:
+    """"""
+
+    __slots__ = (
+        "default_timeout",
+        "initial_retry_delay",
+        "max_retries",
+        "retry_delay_increment",
+    )
+
+    initial_retry_delay: Number
+    default_timeout: DefaultTimeout
+    max_retries: int
+    retry_delay_increment: Number
+
+    def __init__(self):
+        self.default_timeout: DefaultTimeout = DEFAULT_TIMEOUT
+        self.initial_retry_delay: Number = INITIAL_RETRY_DELAY
+        self.max_retries: int = MAX_RETRIES
+        self.retry_delay_increment: Number = RETRY_DELAY_INCREMENT
+
+
+class Config:
+    """Thread-local configuration for SDK behavior"""
+
+    _local_thread = threading.local()
+
+    def __init__(self):
+        local_thread = type(self)._local_thread
+
+        if not hasattr(local_thread, "config"):
+            local_thread.config = _LocalConfig()
+
+        self._config = local_thread.config
+
+    @property
+    def default_timeout(self) -> DefaultTimeout:
+        """Default timeout for API calls"""
+        return self._config.default_timeout
+
+    @default_timeout.setter
+    def default_timeout(self, value: DefaultTimeout):
+        """"""
+
+        if not (isinstance(value, (int, float)) and value > 0):
+            raise ValueError("Default_timeout must be a positive number or a tuple of two positive numbers (connect_timeout, read_timeout)")
+
+        self._config.default_timeout = value
+
+    @property
+    def max_retries(self) -> int:
+        """Maximum number retries that will occur when server is not responding"""
+        return self._config.max_retries
+
+    @max_retries.setter
+    def max_retries(self, value: int):
+        """"""
+
+        if not (isinstance(value, int) and value >= 1):
+            raise ValueError("Max_retries must be a positive integer (>= 1)")
+
+        self._config.max_retries = value
+
+    @property
+    def initial_retry_delay(self) -> Number:
+        """Initial delay between retries in seconds"""
+        return self._config.initial_retry_delay
+
+    @initial_retry_delay.setter
+    def initial_retry_delay(self, value: Number):
+        """"""
+
+        if not (isinstance(value, (int, float)) and value > 0):
+            raise ValueError("Initial_retry_delay must be a positive number")
+
+        self._config.initial_retry_delay = value
+
+    @property
+    def retry_delay_increment(self) -> Number:
+        """Amount by which delay between retries will increment after each retry"""
+        return self._config.retry_delay_increment
+
+    @retry_delay_increment.setter
+    def retry_delay_increment(self, value: Number):
+        """"""
+
+        if not (isinstance(value, (int, float)) and value >= 0):
+            raise ValueError("Retry_delay_increment must be a positive number")
+
+        self._config.retry_delay_increment = value

b24pysdk-0.1.0a1/b24pysdk/_constants.py

@@ -0,0 +1,25 @@
+import sys
+from typing import Final, Tuple
+
+from .utils.types import DefaultTimeout, Number
+
+PYTHON_VERSION: Final[Tuple] = sys.version_info
+""""""
+
+TEXT_PYTHON_VERSION = f"{PYTHON_VERSION[0]}.{PYTHON_VERSION[1]}"
+""""""
+
+DEFAULT_TIMEOUT: Final[DefaultTimeout] = 10
+""""""
+
+INITIAL_RETRY_DELAY: Final[Number] = 1
+""""""
+
+MAX_BATCH_SIZE: Final[int] = 50
+""""""
+
+MAX_RETRIES: Final[int] = 3
+""""""
+
+RETRY_DELAY_INCREMENT: Final[Number] = 0
+""""""

b24pysdk-0.1.0a1/b24pysdk/_version.py

@@ -0,0 +1,4 @@
+from typing import Final, Text
+
+__title__: Final[Text] = "b24pysdk"
+__version__: Final[Text] = "0.1.0a1"

b24pysdk-0.1.0a1/b24pysdk/bitrix_api/__init__.py

@@ -0,0 +1,14 @@
+from .bitrix_app import AbstractBitrixApp, AbstractBitrixAppLocal, BitrixApp, BitrixAppLocal
+from .bitrix_token import AbstractBitrixToken, AbstractBitrixTokenLocal, BitrixToken, BitrixTokenLocal, BitrixWebhook
+
+__all__ = [
+    "AbstractBitrixApp",
+    "AbstractBitrixAppLocal",
+    "AbstractBitrixToken",
+    "AbstractBitrixTokenLocal",
+    "BitrixApp",
+    "BitrixAppLocal",
+    "BitrixToken",
+    "BitrixTokenLocal",
+    "BitrixWebhook",
+]

b24pysdk-0.1.0a1/b24pysdk/bitrix_api/bitrix_app.py

@@ -0,0 +1,51 @@
+from abc import ABC, abstractmethod
+from typing import Text
+
+
+class AbstractBitrixApp(ABC):
+    """"""
+
+    client_id: Text = NotImplemented
+    """"""
+
+    client_secret: Text = NotImplemented
+    """"""
+
+    @abstractmethod
+    def __init__(self, *args, **kwargs):
+        """"""
+        super().__init__(*args, **kwargs)
+
+
+class AbstractBitrixAppLocal(AbstractBitrixApp, ABC):
+    """"""
+
+    domain: Text
+    """"""
+
+
+class BitrixApp(AbstractBitrixApp):
+    """Local or market bitrix application"""
+
+    def __init__(
+            self,
+            *,
+            client_id: Text,
+            client_secret: Text,
+    ):
+        self.client_id = client_id
+        self.client_secret = client_secret
+
+
+class BitrixAppLocal(AbstractBitrixAppLocal):
+    """"""
+
+    def __init__(
+            self,
+            *,
+            domain: Text,
+            client_id: Text,
+            client_secret: Text,
+    ):
+        super().__init__(client_id, client_secret)
+        self.domian = domain