novaposhta-python-client 0.1.10__tar.gz → 0.1.12__tar.gz

{novaposhta_python_client-0.1.10 → novaposhta_python_client-0.1.12}/PKG-INFO

@@ -1,25 +1,33 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: novaposhta-python-client
-Version: 0.1.10
+Version: 0.1.12
 Summary: Python client for Nova Poshta API
-Home-page: https://github.com/semolex/novaposhta-python-client
 License: MIT
+License-File: LICENSE.md
 Keywords: api,nova-poshta,novaposhta,nova-poshta-api,novaposhta-api
 Author: Oleksii
 Author-email: semolex@live.com
 Requires-Python: >=3.9,<4.0
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Software Development :: Build Tools
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: h11 (>=0.16.0,<0.17.0)
 Requires-Dist: httpx (>=0.24.0)
+Project-URL: Homepage, https://github.com/semolex/novaposhta-python-client
 Project-URL: Repository, https://github.com/semolex/novaposhta-python-client
 Description-Content-Type: text/markdown
 
@@ -28,8 +36,14 @@ Description-Content-Type: text/markdown
 A Python client for interfacing with the Nova Poshta API. Designed to provide easy access to all API functionalities
 with emphasis on consistency and usability.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
+[![Tests](https://github.com/semolex/novaposhta-python-client/actions/workflows/tests.yml/badge.svg)](https://github.com/semolex/novaposhta-python-client/actions/workflows/tests.yml)
+[![License](https://img.shields.io/github/license/semolex/novaposhta-python-client)](https://github.com/semolex/novaposhta-python-client/blob/master/LICENSE.md)
+[![PyPI](https://img.shields.io/pypi/v/novaposhta-python-client)](https://pypi.org/project/novaposhta-python-client/)
+[![Downloads](https://pepy.tech/badge/novaposhta-python-client)](https://pepy.tech/project/novaposhta-python-client)
+[![Downloads](https://pepy.tech/badge/novaposhta-python-client/month)](https://pepy.tech/project/novaposhta-python-client)
+[![Python Versions](https://img.shields.io/pypi/pyversions/novaposhta-python-client.svg)](https://pypi.org/project/novaposhta-python-client/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1)](https://pycqa.github.io/isort/)
 
 ## Description
 
@@ -161,13 +175,93 @@ To get your custom model instance, use the get method:
 my_custom_model = client.get(MyCustomModel.name)
 ```
 
-## Testing and linting
+## Experimental: Chain Operations
+
+The chain functionality allows you to sequence multiple API operations, where each operation's output can be transformed and passed to the next operation. This is particularly useful for scenarios that require multiple dependent API calls, like searching for addresses or creating shipments.
+Each result of `prepare_next` is passed to the next operation as updated `kwargs`.
+> ⚠️ **Note**: This feature is experimental and currently optimized for async usage.
+
+### Basic Usage
+
+```python
+from novaposhta.client import NovaPoshtaApi
+from novaposhta.chains import Chain 
+
+# Initialize client in async mode
+client = NovaPoshtaApi("API_KEY", async_mode=True)
+
+# Create a chain of operations
+chain = (
+    Chain(
+        client.address.get_areas,
+        prepare_next=lambda x: {'ref': x['data'][0]['AreasCenter']}
+    ) |
+    Chain(
+        client.address.get_cities,
+        prepare_next=lambda x: {'city_ref': x['data'][0]['Ref']}
+    ) |
+    Chain(
+        client.address.get_street,
+        kwargs={'find_by_string': 'Street Name'}
+    )
+)
+
+# Execute chain
+results = await chain.execute_async()
+```
+
+### Features
+
+- Chain multiple API operations using the `|` operator
+- Transform operation results for next operation using `prepare_next`
+- Automatic error handling and chain interruption on failure
+- Preserve both original API responses and transformed data
+- Initial parameters via `kwargs`
+
+### Common Patterns
 
+```python
+# Address search chain
+from novaposhta.client import NovaPoshtaApi
+
+client = NovaPoshtaApi("API_KEY", async_mode=True)
+from novaposhta.chains import Chain
+address = client.address
+chain = (
+    Chain(
+        address.search_settlements,
+        kwargs={'city_name': 'Київ'},
+        prepare_next=lambda x: {'settlement_ref': x['data'][0]['Ref']}
+    ) |
+    Chain(
+        address.search_settlement_streets,
+        kwargs={'street_name': 'Main'}
+    )
+)
+
+# Execute and process results
+results = await chain.execute_async()
+for result in results:
+    print(f"Success: {result.success}")
+    print(f"Data: {result.data}")
+    print(f"Next kwargs: {result.next_kwargs}")
+```
+
+### Limitations
+
+- Currently optimized for async usage
+- Experimental API that may change
+- Sequential execution only (no parallel operations)
+
+
+
+## Testing and linting
+Note: install dev dependencies first
 ```bash
 poetry run black novaposhta/
 poetry run isort novaposhta/
 poetry run mypy novaposhta/
-poetry run pytest tests/
+poetry run pytest --cov=novaposhta tests/
 ```
 
 ## Contributing

{novaposhta_python_client-0.1.10 → novaposhta_python_client-0.1.12}/README.md

@@ -3,8 +3,14 @@
 A Python client for interfacing with the Nova Poshta API. Designed to provide easy access to all API functionalities
 with emphasis on consistency and usability.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
+[![Tests](https://github.com/semolex/novaposhta-python-client/actions/workflows/tests.yml/badge.svg)](https://github.com/semolex/novaposhta-python-client/actions/workflows/tests.yml)
+[![License](https://img.shields.io/github/license/semolex/novaposhta-python-client)](https://github.com/semolex/novaposhta-python-client/blob/master/LICENSE.md)
+[![PyPI](https://img.shields.io/pypi/v/novaposhta-python-client)](https://pypi.org/project/novaposhta-python-client/)
+[![Downloads](https://pepy.tech/badge/novaposhta-python-client)](https://pepy.tech/project/novaposhta-python-client)
+[![Downloads](https://pepy.tech/badge/novaposhta-python-client/month)](https://pepy.tech/project/novaposhta-python-client)
+[![Python Versions](https://img.shields.io/pypi/pyversions/novaposhta-python-client.svg)](https://pypi.org/project/novaposhta-python-client/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![Imports: isort](https://img.shields.io/badge/%20imports-isort-%231674b1)](https://pycqa.github.io/isort/)
 
 ## Description
 
@@ -136,13 +142,93 @@ To get your custom model instance, use the get method:
 my_custom_model = client.get(MyCustomModel.name)
 ```
 
-## Testing and linting
+## Experimental: Chain Operations
+
+The chain functionality allows you to sequence multiple API operations, where each operation's output can be transformed and passed to the next operation. This is particularly useful for scenarios that require multiple dependent API calls, like searching for addresses or creating shipments.
+Each result of `prepare_next` is passed to the next operation as updated `kwargs`.
+> ⚠️ **Note**: This feature is experimental and currently optimized for async usage.
+
+### Basic Usage
+
+```python
+from novaposhta.client import NovaPoshtaApi
+from novaposhta.chains import Chain 
+
+# Initialize client in async mode
+client = NovaPoshtaApi("API_KEY", async_mode=True)
+
+# Create a chain of operations
+chain = (
+    Chain(
+        client.address.get_areas,
+        prepare_next=lambda x: {'ref': x['data'][0]['AreasCenter']}
+    ) |
+    Chain(
+        client.address.get_cities,
+        prepare_next=lambda x: {'city_ref': x['data'][0]['Ref']}
+    ) |
+    Chain(
+        client.address.get_street,
+        kwargs={'find_by_string': 'Street Name'}
+    )
+)
+
+# Execute chain
+results = await chain.execute_async()
+```
+
+### Features
+
+- Chain multiple API operations using the `|` operator
+- Transform operation results for next operation using `prepare_next`
+- Automatic error handling and chain interruption on failure
+- Preserve both original API responses and transformed data
+- Initial parameters via `kwargs`
+
+### Common Patterns
 
+```python
+# Address search chain
+from novaposhta.client import NovaPoshtaApi
+
+client = NovaPoshtaApi("API_KEY", async_mode=True)
+from novaposhta.chains import Chain
+address = client.address
+chain = (
+    Chain(
+        address.search_settlements,
+        kwargs={'city_name': 'Київ'},
+        prepare_next=lambda x: {'settlement_ref': x['data'][0]['Ref']}
+    ) |
+    Chain(
+        address.search_settlement_streets,
+        kwargs={'street_name': 'Main'}
+    )
+)
+
+# Execute and process results
+results = await chain.execute_async()
+for result in results:
+    print(f"Success: {result.success}")
+    print(f"Data: {result.data}")
+    print(f"Next kwargs: {result.next_kwargs}")
+```
+
+### Limitations
+
+- Currently optimized for async usage
+- Experimental API that may change
+- Sequential execution only (no parallel operations)
+
+
+
+## Testing and linting
+Note: install dev dependencies first
 ```bash
 poetry run black novaposhta/
 poetry run isort novaposhta/
 poetry run mypy novaposhta/
-poetry run pytest tests/
+poetry run pytest --cov=novaposhta tests/
 ```
 
 ## Contributing

novaposhta_python_client-0.1.12/novaposhta/chains.py

@@ -0,0 +1,104 @@
+"""Chain of calls with error handling and data passing between calls. """
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, List, Optional, TypeVar, Union
+
+T = TypeVar("T")
+
+
+@dataclass
+class ChainResult:
+    """
+    Result of a single chain execution.
+    """
+
+    success: bool
+    data: Optional[Any]
+    error: Optional[str]
+    next_kwargs: Optional[Dict[str, Any]] = None
+
+
+@dataclass
+class Chain:
+    """
+    Chain object that represents a single call in the chain.
+    """
+
+    method: Callable
+    kwargs: Optional[Dict[str, Any]] = None
+    prepare_next: Optional[Callable[[Any], Dict[str, Any]]] = None
+
+    async def execute(self, prev_result: Optional[ChainResult] = None) -> ChainResult:
+        """
+        Execute the chain.
+
+        :param prev_result: result of the previous chain.
+        :return: result of the current chain.
+        """
+        try:
+            execution_kwargs = {**(self.kwargs or {})}
+            if prev_result and prev_result.next_kwargs:
+                execution_kwargs.update(prev_result.next_kwargs)
+
+            result = self.method(**execution_kwargs)
+            if asyncio.iscoroutine(result):
+                result = await result
+
+            next_kwargs = self.prepare_next(result) if self.prepare_next else {}
+
+            return ChainResult(
+                success=result.get("success", False),
+                data=result.get("data"),
+                error=None,
+                next_kwargs=next_kwargs,
+            )
+        except Exception as e:
+            return ChainResult(success=False, data=None, error=str(e), next_kwargs=None)
+
+    def __or__(self, other: "Chain") -> "ChainExecutor":
+        """
+        Create a chain executor with the current chain and another chain.
+        Allows chaining multiple chains together via the `|` operator.
+
+        :param other: another chain.
+        :return ChainExecutor: chain executor with the current chain and another chain.
+        """
+        return ChainExecutor([self, other])
+
+
+class ChainExecutor:
+    """
+    Chain executor that executes multiple chains in a sequence.
+    """
+
+    def __init__(self, chains: Optional[List[Chain]] = None):
+        self.chains = chains or []
+
+    def __or__(self, chain: Chain) -> "ChainExecutor":
+        """
+        Add a chain to the chain executor.
+
+        :param chain: chain to add.
+        :return ChainExecutor: chain executor with the added chain.
+        """
+        self.chains.append(chain)
+        return self
+
+    async def execute_async(self) -> List[ChainResult]:
+        """
+        Execute all chains in the chain executor asynchronously.
+
+        :return: list of results of each chain execution
+        """
+        results = []
+        prev_result = None
+
+        for chain in self.chains:
+            result = await chain.execute(prev_result)
+            results.append(result)
+            if not result.success:
+                break
+            prev_result = result
+
+        return results

{novaposhta_python_client-0.1.10 → novaposhta_python_client-0.1.12}/novaposhta/client.py

@@ -1,6 +1,6 @@
 """Client for Nova Poshta API. """
 
-from typing import Callable, Final, Optional, Type, TypeVar
+from typing import Final, Optional, Type, TypeVar
 
 import httpx
 

{novaposhta_python_client-0.1.10 → novaposhta_python_client-0.1.12}/novaposhta/models/internet_document.py

@@ -133,6 +133,8 @@ class InternetDocument(BaseModel):
         red_box_barcode: OptStr = None,
         backward_delivery_data: OptListOfDicts = None,
         recipient_address_note: OptStr = None,
+        additional_information: OptStr = None,
+        info_reg_client_barcodes: OptStr = None,
     ):
         """
         Create document (delivery).
@@ -219,6 +221,8 @@ class InternetDocument(BaseModel):
             RedBoxBarcode=red_box_barcode,
             BackwardDeliveryData=backward_delivery_data,
             RecipientAddressNote=recipient_address_note,
+            AdditionalInformation=additional_information,
+            InfoRegClientBarcodes=info_reg_client_barcodes,
         )
 
     @api_method("update")

{novaposhta_python_client-0.1.10 → novaposhta_python_client-0.1.12}/novaposhta/types.py

@@ -7,6 +7,7 @@ class RequestData(TypedDict):
     """
     Request data for Nova Poshta API.
     """
+
     apiKey: str
     modelName: str
     calledMethod: str
@@ -17,6 +18,7 @@ class HttpRequest(TypedDict):
     """
     Request data for HTTP client.
     """
+
     url: str
     headers: Dict[str, str]
     json: RequestData

{novaposhta_python_client-0.1.10 → novaposhta_python_client-0.1.12}/pyproject.toml

@@ -3,7 +3,7 @@ name = "novaposhta-python-client"
 packages = [
     { include = "novaposhta"}
 ]
-version = "0.1.10"
+version = "0.1.12"
 description = "Python client for Nova Poshta API"
 authors = ["Oleksii <semolex@live.com>"]
 license = "MIT"
@@ -12,19 +12,31 @@ homepage = "https://github.com/semolex/novaposhta-python-client"
 repository = "https://github.com/semolex/novaposhta-python-client"
 keywords = [ "api", "nova-poshta", "novaposhta", "nova-poshta-api", "novaposhta-api"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
     "Topic :: Software Development :: Build Tools",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3 :: Only",
     "Programming Language :: Python :: 3.9",
-    "License :: OSI Approved :: MIT License"
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Typing :: Typed"
+]
+
+exclude = [
+    "tests/*",
+    "tests/**/*",
+    "**/tests/*",
 ]
 
 [tool.poetry.dependencies]
 python = "^3.9"
 httpx = ">=0.24.0"
-
+h11 = "^0.16.0"
 
 [tool.poetry.group.dev.dependencies]
 mypy = "^1.5.1"
@@ -34,6 +46,7 @@ pytest-httpx = "^0.26.0"
 coverage = "^7.3.2"
 pytest-asyncio = "^0.21.1"
 isort = "^5.13.2"
+pytest-cov = "^6.0.0"
 
 [build-system]
 requires = ["poetry-core"]