# novaposhta-python-client
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.
[](https://opensource.org/licenses/MIT)
## Description
This client is compatible with `python = "^3.9"` and aims to mirror the Nova Poshta API's endpoints, offering a 1:1
mapping where possible. However, users should be aware of the inconsistencies and occasional ambiguities present in the
API. This can affect the signatures of some methods, and special attention is needed when working with endpoints like
the `save` method from some models which can create different items based on the provided input.
Efforts to enhance the consistency and robustness of the client are ongoing, and future releases will focus on thorough
testing and refinement of all possible parameter combinations.
## Installation
```bash
pip install novaposhta-python-client
```
## Usage
Here's a basic example of how to use the client:
```python
from novaposhta.client import NovaPoshtaApi
# Instantiate the client
client = NovaPoshtaApi('my-api-token', timeout=30)
# Example usage of different models
settlements = client.address.search_settlements(city_name='Київ', limit=5)
my_pack_list = client.common.get_pack_list(length=1, width=5)
return_reason = client.additional_service.get_return_reasons()
# Print results
print(settlements, my_pack_list, return_reason)
client.close_sync()
```
Please, close the client whenever you are done with it to avoid resource leaks.
You can also use async client:
```python
import asyncio
from novaposhta.client import NovaPoshtaApi
async def use_api_async():
async_client = NovaPoshtaApi('your_api_key', timeout=30, async_mode=True, raise_for_errors=True)
address = async_client.address
settlements = await address.search_settlements(city_name='Київ', limit=5)
print(settlements)
await async_client.close_async()
asyncio.run(use_api_async())
```
You can use context manager to automatically close the client:
```python
from novaposhta.client import NovaPoshtaApi
def use_api_sync():
with NovaPoshtaApi(api_key='your_api_key', async_mode=False) as api:
# Do something with the API
pass
async def use_api_async():
async with NovaPoshtaApi(api_key='your_api_key', async_mode=True) as api:
# Do something with the API
pass
```
## Error handling
```python
import httpx
from novaposhta.client import NovaPoshtaApi, InvalidAPIKeyError, APIRequestError
# Instantiate the client
client = NovaPoshtaApi('your_api_key', timeout=30, raise_for_errors=True)
try:
client.common.get_cargo_types()
except httpx.HTTPError as error:
print(f"HTTP error: {error}")
except InvalidAPIKeyError as error:
print(f"API key expired or otherwise invalid: {error}")
except APIRequestError as error:
print(f"Something else is wrong with API request: {error}")
```
## Extending the Client
### Custom HTTP Client
While `httpx` is the default HTTP library, you can easily substitute it with requests or another library, provided it
follows the same interface:
```python
from novaposhta.client import NovaPoshtaApi
import my_http_client
client = NovaPoshtaApi('your_api_key', http_client=my_http_client.Client)
```
### Adding New Methods
If a method isn’t implemented, or you prefer a custom implementation, extend the model as shown below:
```python
from novaposhta.models.base import BaseModel, api_method
class MyCustomModel(BaseModel):
@api_method('MissingMethod')
def missing_method(self, some_param: str):
return self._call_with_props(SomeParam=some_param)
```
The client caches all model instances. To reset and create a new model instance, use the new method:
```python
from novaposhta.client import NovaPoshtaApi
from novaposhta.models.address import Address
client = NovaPoshtaApi('my-api-token')
address = client.new(Address)
```
To get your custom model instance, use the get method:
```python
my_custom_model = client.get(MyCustomModel.name)
```
## Testing and linting
```bash
poetry run black novaposhta
poetry run mypy novaposhta/
poetry run pytest tests/
```
## Contributing
We welcome contributions that can help in enhancing the functionality and improving the consistency of the client. For
bugs or feature requests, please open an issue on the GitHub repository.
Please, use `black` and `mypy` as your instrument for code formatting and type checking.
Raw data
{
"_id": null,
"home_page": "https://github.com/semolex/novaposhta-python-client",
"name": "novaposhta-python-client",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "api, nova-poshta, novaposhta, nova-poshta-api, novaposhta-api",
"author": "Oleksii",
"author_email": "semolex@live.com",
"download_url": "https://files.pythonhosted.org/packages/5e/81/2481748b04ae952d87541f796254361e13d4178809d59f8a571e9a437877/novaposhta_python_client-0.1.7.tar.gz",
"platform": null,
"description": "# novaposhta-python-client\n\nA Python client for interfacing with the Nova Poshta API. Designed to provide easy access to all API functionalities\nwith emphasis on consistency and usability.\n\n[](https://opensource.org/licenses/MIT)\n\n\n## Description\n\nThis client is compatible with `python = \"^3.9\"` and aims to mirror the Nova Poshta API's endpoints, offering a 1:1\nmapping where possible. However, users should be aware of the inconsistencies and occasional ambiguities present in the\nAPI. This can affect the signatures of some methods, and special attention is needed when working with endpoints like\nthe `save` method from some models which can create different items based on the provided input.\n\nEfforts to enhance the consistency and robustness of the client are ongoing, and future releases will focus on thorough\ntesting and refinement of all possible parameter combinations.\n\n## Installation\n\n```bash\npip install novaposhta-python-client\n```\n\n## Usage\n\nHere's a basic example of how to use the client:\n\n```python\nfrom novaposhta.client import NovaPoshtaApi\n\n# Instantiate the client\nclient = NovaPoshtaApi('my-api-token', timeout=30)\n\n# Example usage of different models\nsettlements = client.address.search_settlements(city_name='\u041a\u0438\u0457\u0432', limit=5)\nmy_pack_list = client.common.get_pack_list(length=1, width=5)\nreturn_reason = client.additional_service.get_return_reasons()\n\n# Print results\nprint(settlements, my_pack_list, return_reason)\nclient.close_sync()\n```\nPlease, close the client whenever you are done with it to avoid resource leaks.\n\nYou can also use async client:\n\n```python\nimport asyncio\nfrom novaposhta.client import NovaPoshtaApi\n\nasync def use_api_async():\n async_client = NovaPoshtaApi('your_api_key', timeout=30, async_mode=True, raise_for_errors=True)\n address = async_client.address\n settlements = await address.search_settlements(city_name='\u041a\u0438\u0457\u0432', limit=5)\n print(settlements)\n await async_client.close_async()\nasyncio.run(use_api_async())\n```\n\nYou can use context manager to automatically close the client:\n\n```python\nfrom novaposhta.client import NovaPoshtaApi\ndef use_api_sync():\n with NovaPoshtaApi(api_key='your_api_key', async_mode=False) as api:\n # Do something with the API\n pass\n\nasync def use_api_async():\n async with NovaPoshtaApi(api_key='your_api_key', async_mode=True) as api:\n # Do something with the API\n pass\n```\n\n## Error handling\n\n```python\nimport httpx\nfrom novaposhta.client import NovaPoshtaApi, InvalidAPIKeyError, APIRequestError\n\n# Instantiate the client\nclient = NovaPoshtaApi('your_api_key', timeout=30, raise_for_errors=True)\n\ntry:\n client.common.get_cargo_types()\nexcept httpx.HTTPError as error:\n print(f\"HTTP error: {error}\")\nexcept InvalidAPIKeyError as error:\n print(f\"API key expired or otherwise invalid: {error}\")\nexcept APIRequestError as error:\n print(f\"Something else is wrong with API request: {error}\")\n```\n\n## Extending the Client\n\n### Custom HTTP Client\n\nWhile `httpx` is the default HTTP library, you can easily substitute it with requests or another library, provided it\nfollows the same interface:\n\n```python\nfrom novaposhta.client import NovaPoshtaApi\nimport my_http_client\n\nclient = NovaPoshtaApi('your_api_key', http_client=my_http_client.Client)\n```\n\n### Adding New Methods\n\nIf a method isn\u2019t implemented, or you prefer a custom implementation, extend the model as shown below:\n\n```python\nfrom novaposhta.models.base import BaseModel, api_method\n\n\nclass MyCustomModel(BaseModel):\n @api_method('MissingMethod')\n def missing_method(self, some_param: str):\n return self._call_with_props(SomeParam=some_param)\n```\n\nThe client caches all model instances. To reset and create a new model instance, use the new method:\n\n```python\nfrom novaposhta.client import NovaPoshtaApi\nfrom novaposhta.models.address import Address\n\nclient = NovaPoshtaApi('my-api-token')\naddress = client.new(Address)\n```\n\nTo get your custom model instance, use the get method:\n\n```python\nmy_custom_model = client.get(MyCustomModel.name)\n```\n\n## Testing and linting\n\n```bash\npoetry run black novaposhta\npoetry run mypy novaposhta/\npoetry run pytest tests/\n```\n\n## Contributing\n\nWe welcome contributions that can help in enhancing the functionality and improving the consistency of the client. For\nbugs or feature requests, please open an issue on the GitHub repository.\nPlease, use `black` and `mypy` as your instrument for code formatting and type checking.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python client for Nova Poshta API",
"version": "0.1.7",
"project_urls": {
"Homepage": "https://github.com/semolex/novaposhta-python-client",
"Repository": "https://github.com/semolex/novaposhta-python-client"
},
"split_keywords": [
"api",
" nova-poshta",
" novaposhta",
" nova-poshta-api",
" novaposhta-api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e33136c183be6f9985a4e64d081fb6aa5332da59a8f90c774d47683323d82a62",
"md5": "e69124a2f04db6e7f00c04fb7d2afe55",
"sha256": "0d4796af53c2f2426f56ed43e874596a9c8af5167ca050ee256ccd888e2c9731"
},
"downloads": -1,
"filename": "novaposhta_python_client-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e69124a2f04db6e7f00c04fb7d2afe55",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 16514,
"upload_time": "2024-05-03T10:34:16",
"upload_time_iso_8601": "2024-05-03T10:34:16.702318Z",
"url": "https://files.pythonhosted.org/packages/e3/31/36c183be6f9985a4e64d081fb6aa5332da59a8f90c774d47683323d82a62/novaposhta_python_client-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5e812481748b04ae952d87541f796254361e13d4178809d59f8a571e9a437877",
"md5": "ccd2a0227202d32d7846ccc7f9e3fc77",
"sha256": "2eaee6bae836f734bef4bd5a73609156f0036f270d8d5d472754bee867fd53bf"
},
"downloads": -1,
"filename": "novaposhta_python_client-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "ccd2a0227202d32d7846ccc7f9e3fc77",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 13562,
"upload_time": "2024-05-03T10:34:17",
"upload_time_iso_8601": "2024-05-03T10:34:17.923463Z",
"url": "https://files.pythonhosted.org/packages/5e/81/2481748b04ae952d87541f796254361e13d4178809d59f8a571e9a437877/novaposhta_python_client-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-03 10:34:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "semolex",
"github_project": "novaposhta-python-client",
"travis_ci": false,
"coveralls": true,
"github_actions": false,
"lcname": "novaposhta-python-client"
}
JSON
