| Name | polarion-rest-api-client JSON |
| Version |
1.2.2
JSON |
| download |
| home_page | None |
| Summary | An API Client for the Polarion REST API |
| upload_time | 2024-10-29 16:08:10 |
| maintainer | None |
| docs_url | None |
| author | DB InfraGO AG |
| requires_python | <3.13,>=3.10 |
| license | Apache-2.0 |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<!--
~ Copyright DB InfraGO AG and contributors
~ SPDX-License-Identifier: Apache-2.0
-->
# polarion-rest-api-client
<!-- prettier-ignore -->
A client library for accessing Polarion REST API. This project consists of multiple layers. There is a high level, still incomplete
version of the client and a feature complete low level API client, which was generated using an [OpenAPI generator](https://github.com/openapi-generators/openapi-python-client).
Therefor the OpenAPI Specification of Polarion was used.
## Usage of the High Level Client
The high level client is an abstraction of the fine-grained, auto-generated client. It is non project specific, however, for most operations, you need to create a project specific one from the generic one. All created created project clients share the client session of the generic client.
To get started, create a client and check, if the project exists. In the end, to get all Work Items of a project with an empty query, you can simply run the following code and our client will automatically take care of the paging:
```python
import polarion_rest_api_client as polarion_api
client = polarion_api.PolarionClient(
polarion_api_endpoint="http://127.0.0.1/api",
polarion_access_token="PAT123",
)
project_client = client.generate_project_client("PROJ")
project_exists = project_client.exists() # Should be True
work_items = project_client.work_items.get_all()
```
During the initialization of the client you can define additional settings like the page size when getting items or the maximum content size when bulk creating new items.
In addition, you can define your own Work Item class with custom fields, which become available as attributes on object level instead of being part of the `additional_attributes` dictionary only.
To use this feature, inherit from our Work Item class and pass your extended class when requesting Work Items:
```python
import polarion_rest_api_client as polarion_api
import dataclasses
@dataclasses.dataclass
class CustomWorkItem(polarion_api.WorkItem):
capella_uuid: str | None = None
client = polarion_api.PolarionClient(
polarion_api_endpoint="http://127.0.0.1/api",
polarion_access_token="PAT123",
)
project_client = client.generate_project_client("PROJ")
work_items = project_client.work_items.get_all(work_item_cls=CustomWorkItem)
uuid = work_items[0].capella_uuid # the value of the custom field capella_uuid can be accessed this way
```
## Usage of the autogenerated OpenAPI Client
First, create a client:
```python
from polarion_rest_api_client.open_api_client import Client
client = Client(base_url="https://api.example.com")
```
If the endpoints you're going to hit require authentication, use `AuthenticatedClient` instead:
```python
from polarion_rest_api_client.open_api_client import AuthenticatedClient
client = AuthenticatedClient(base_url="https://api.example.com", token="SuperSecretToken")
```
Now call your endpoint and use your models:
```python
from polarion_rest_api_client.open_api_client.models import MyDataModel
from polarion_rest_api_client.open_api_client.api.my_tag import get_my_data_model
from polarion_rest_api_client.open_api_client.types import Response
my_data: MyDataModel = get_my_data_model.sync(client=client)
# or if you need more info (e.g. status_code)
response: Response[MyDataModel] = get_my_data_model.sync_detailed(client=client)
```
Or do the same thing with an async version:
```python
from polarion_rest_api_client.open_api_client.models import MyDataModel
from polarion_rest_api_client.open_api_client.api.my_tag import get_my_data_model
from polarion_rest_api_client.open_api_client.types import Response
my_data: MyDataModel = await get_my_data_model.asyncio(client=client)
response: Response[MyDataModel] = await get_my_data_model.asyncio_detailed(client=client)
```
By default, when you're calling an HTTPS API it will attempt to verify that SSL is working correctly. Using certificate verification is highly recommended most of the time, but sometimes you may need to authenticate to a server (especially an internal server) using a custom certificate bundle.
```python
client = AuthenticatedClient(
base_url="https://internal_api.example.com",
token="SuperSecretToken",
verify_ssl="/path/to/certificate_bundle.pem",
)
```
You can also disable certificate validation altogether, but beware that **this is a security risk**.
```python
client = AuthenticatedClient(
base_url="https://internal_api.example.com",
token="SuperSecretToken",
verify_ssl=False
)
```
There are more settings on the generated `Client` class which let you control more runtime behavior, check out the docstring on that class for more info.
Things to know:
1. Every path/method combo becomes a Python module with four functions:
1. `sync`: Blocking request that returns parsed data (if successful) or `None`
1. `sync_detailed`: Blocking request that always returns a `Request`, optionally with `parsed` set if the request was successful.
1. `asyncio`: Like `sync` but async instead of blocking
1. `asyncio_detailed`: Like `sync_detailed` but async instead of blocking
1. All path/query params, and bodies become method arguments.
1. If your endpoint had any tags on it, the first tag will be used as a module name for the function (my_tag above)
1. Any endpoint which did not have a tag will be in `polarion_rest_api_client.open_api_client.api.default`
# Documentation
<!-- prettier-ignore -->
Read the [full documentation on Github pages](https://dsd-dbs.github.io/polarion-rest-api-client).
# Installation
You can install the latest released version directly from PyPI (**Not yet**).
```zsh
pip install polarion-rest-api-client
```
To set up a development environment, clone the project and install it into a
virtual environment.
```zsh
git clone https://github.com/DSD-DBS/polarion-rest-api-client
cd polarion-rest-api-client
python -m venv .venv
source .venv/bin/activate.sh # for Linux / Mac
.venv\Scripts\activate # for Windows
pip install -U pip pre-commit
pip install -e '.[docs,test]'
pre-commit install
```
## Updating the auto generated part
To update the auto generated part of the code, execute the `open_api_client_build/build_client.py` script with `path` or `url` as first
arg and the path to the OpenAPI-Specification as second arg from the project root directory. The publicly available [specification](https://developer.siemens.com/polarion/polarion-rest-apispec.json)
from the Polarion developer Portal was used.
# Contributing
We'd love to see your bug reports and improvement suggestions! Please take a
look at our [guidelines for contributors](CONTRIBUTING.md) for details.
# Licenses
This project is compliant with the
[REUSE Specification Version 3.0](https://git.fsfe.org/reuse/docs/src/commit/d173a27231a36e1a2a3af07421f5e557ae0fec46/spec.md).
Copyright DB InfraGO AG, licensed under Apache 2.0 (see full text in
[LICENSES/Apache-2.0.txt](LICENSES/Apache-2.0.txt))
Dot-files are licensed under CC0-1.0 (see full text in
[LICENSES/CC0-1.0.txt](LICENSES/CC0-1.0.txt))
Raw data
{
"_id": null,
"home_page": null,
"name": "polarion-rest-api-client",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "DB InfraGO AG",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/2d/e2/540ba2b0201b315c8dfda24c624b2c630a3067e4e7da92a8fd35166a5343/polarion_rest_api_client-1.2.2.tar.gz",
"platform": "any",
"description": "<!--\n ~ Copyright DB InfraGO AG and contributors\n ~ SPDX-License-Identifier: Apache-2.0\n -->\n\n# polarion-rest-api-client\n\n<!-- prettier-ignore -->\n\n\n\nA client library for accessing Polarion REST API. This project consists of multiple layers. There is a high level, still incomplete\nversion of the client and a feature complete low level API client, which was generated using an [OpenAPI generator](https://github.com/openapi-generators/openapi-python-client).\nTherefor the OpenAPI Specification of Polarion was used.\n\n## Usage of the High Level Client\nThe high level client is an abstraction of the fine-grained, auto-generated client. It is non project specific, however, for most operations, you need to create a project specific one from the generic one. All created created project clients share the client session of the generic client.\nTo get started, create a client and check, if the project exists. In the end, to get all Work Items of a project with an empty query, you can simply run the following code and our client will automatically take care of the paging:\n\n```python\nimport polarion_rest_api_client as polarion_api\n\nclient = polarion_api.PolarionClient(\n polarion_api_endpoint=\"http://127.0.0.1/api\",\n polarion_access_token=\"PAT123\",\n)\nproject_client = client.generate_project_client(\"PROJ\")\nproject_exists = project_client.exists() # Should be True\nwork_items = project_client.work_items.get_all()\n```\nDuring the initialization of the client you can define additional settings like the page size when getting items or the maximum content size when bulk creating new items.\nIn addition, you can define your own Work Item class with custom fields, which become available as attributes on object level instead of being part of the `additional_attributes` dictionary only.\nTo use this feature, inherit from our Work Item class and pass your extended class when requesting Work Items:\n```python\nimport polarion_rest_api_client as polarion_api\nimport dataclasses\n\n@dataclasses.dataclass\nclass CustomWorkItem(polarion_api.WorkItem):\n capella_uuid: str | None = None\n\nclient = polarion_api.PolarionClient(\n polarion_api_endpoint=\"http://127.0.0.1/api\",\n polarion_access_token=\"PAT123\",\n)\nproject_client = client.generate_project_client(\"PROJ\")\nwork_items = project_client.work_items.get_all(work_item_cls=CustomWorkItem)\nuuid = work_items[0].capella_uuid # the value of the custom field capella_uuid can be accessed this way\n```\n## Usage of the autogenerated OpenAPI Client\nFirst, create a client:\n\n```python\nfrom polarion_rest_api_client.open_api_client import Client\n\nclient = Client(base_url=\"https://api.example.com\")\n```\n\nIf the endpoints you're going to hit require authentication, use `AuthenticatedClient` instead:\n\n```python\nfrom polarion_rest_api_client.open_api_client import AuthenticatedClient\n\nclient = AuthenticatedClient(base_url=\"https://api.example.com\", token=\"SuperSecretToken\")\n```\n\nNow call your endpoint and use your models:\n\n```python\nfrom polarion_rest_api_client.open_api_client.models import MyDataModel\nfrom polarion_rest_api_client.open_api_client.api.my_tag import get_my_data_model\nfrom polarion_rest_api_client.open_api_client.types import Response\n\nmy_data: MyDataModel = get_my_data_model.sync(client=client)\n# or if you need more info (e.g. status_code)\nresponse: Response[MyDataModel] = get_my_data_model.sync_detailed(client=client)\n```\n\nOr do the same thing with an async version:\n\n```python\nfrom polarion_rest_api_client.open_api_client.models import MyDataModel\nfrom polarion_rest_api_client.open_api_client.api.my_tag import get_my_data_model\nfrom polarion_rest_api_client.open_api_client.types import Response\n\nmy_data: MyDataModel = await get_my_data_model.asyncio(client=client)\nresponse: Response[MyDataModel] = await get_my_data_model.asyncio_detailed(client=client)\n```\n\nBy default, when you're calling an HTTPS API it will attempt to verify that SSL is working correctly. Using certificate verification is highly recommended most of the time, but sometimes you may need to authenticate to a server (especially an internal server) using a custom certificate bundle.\n\n```python\nclient = AuthenticatedClient(\n base_url=\"https://internal_api.example.com\",\n token=\"SuperSecretToken\",\n verify_ssl=\"/path/to/certificate_bundle.pem\",\n)\n```\n\nYou can also disable certificate validation altogether, but beware that **this is a security risk**.\n\n```python\nclient = AuthenticatedClient(\n base_url=\"https://internal_api.example.com\",\n token=\"SuperSecretToken\",\n verify_ssl=False\n)\n```\n\nThere are more settings on the generated `Client` class which let you control more runtime behavior, check out the docstring on that class for more info.\n\nThings to know:\n1. Every path/method combo becomes a Python module with four functions:\n 1. `sync`: Blocking request that returns parsed data (if successful) or `None`\n 1. `sync_detailed`: Blocking request that always returns a `Request`, optionally with `parsed` set if the request was successful.\n 1. `asyncio`: Like `sync` but async instead of blocking\n 1. `asyncio_detailed`: Like `sync_detailed` but async instead of blocking\n\n1. All path/query params, and bodies become method arguments.\n1. If your endpoint had any tags on it, the first tag will be used as a module name for the function (my_tag above)\n1. Any endpoint which did not have a tag will be in `polarion_rest_api_client.open_api_client.api.default`\n\n# Documentation\n\n<!-- prettier-ignore -->\nRead the [full documentation on Github pages](https://dsd-dbs.github.io/polarion-rest-api-client).\n\n# Installation\n\nYou can install the latest released version directly from PyPI (**Not yet**).\n\n```zsh\npip install polarion-rest-api-client\n```\n\nTo set up a development environment, clone the project and install it into a\nvirtual environment.\n\n```zsh\ngit clone https://github.com/DSD-DBS/polarion-rest-api-client\ncd polarion-rest-api-client\npython -m venv .venv\n\nsource .venv/bin/activate.sh # for Linux / Mac\n.venv\\Scripts\\activate # for Windows\n\npip install -U pip pre-commit\npip install -e '.[docs,test]'\npre-commit install\n```\n\n## Updating the auto generated part\nTo update the auto generated part of the code, execute the `open_api_client_build/build_client.py` script with `path` or `url` as first\narg and the path to the OpenAPI-Specification as second arg from the project root directory. The publicly available [specification](https://developer.siemens.com/polarion/polarion-rest-apispec.json)\nfrom the Polarion developer Portal was used.\n\n# Contributing\n\nWe'd love to see your bug reports and improvement suggestions! Please take a\nlook at our [guidelines for contributors](CONTRIBUTING.md) for details.\n\n# Licenses\n\nThis project is compliant with the\n[REUSE Specification Version 3.0](https://git.fsfe.org/reuse/docs/src/commit/d173a27231a36e1a2a3af07421f5e557ae0fec46/spec.md).\n\nCopyright DB InfraGO AG, licensed under Apache 2.0 (see full text in\n[LICENSES/Apache-2.0.txt](LICENSES/Apache-2.0.txt))\n\nDot-files are licensed under CC0-1.0 (see full text in\n[LICENSES/CC0-1.0.txt](LICENSES/CC0-1.0.txt))\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "An API Client for the Polarion REST API",
"version": "1.2.2",
"project_urls": {
"Documentation": "https://dsd-dbs.github.io/polarion-rest-api-client",
"Homepage": "https://github.com/DSD-DBS/polarion-rest-api-client"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c985e078ec953ee3b7c580a41533392afd6dc50c8f16108ebf3043e4c8138c24",
"md5": "fa904fd0ecb6c72533ec47b09849de41",
"sha256": "e8361585a9000c88368f09d3e7af6059b573cdaea0d766e4d084ab05b888dafe"
},
"downloads": -1,
"filename": "polarion_rest_api_client-1.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fa904fd0ecb6c72533ec47b09849de41",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.10",
"size": 2738969,
"upload_time": "2024-10-29T16:08:08",
"upload_time_iso_8601": "2024-10-29T16:08:08.251718Z",
"url": "https://files.pythonhosted.org/packages/c9/85/e078ec953ee3b7c580a41533392afd6dc50c8f16108ebf3043e4c8138c24/polarion_rest_api_client-1.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2de2540ba2b0201b315c8dfda24c624b2c630a3067e4e7da92a8fd35166a5343",
"md5": "ee4e16d516863ea7e2d589fcdda5e85b",
"sha256": "6553940ba9a040f3e67afe74ecc05a4b894e5f2abbb71ecd55202bb40f339b5b"
},
"downloads": -1,
"filename": "polarion_rest_api_client-1.2.2.tar.gz",
"has_sig": false,
"md5_digest": "ee4e16d516863ea7e2d589fcdda5e85b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.10",
"size": 624266,
"upload_time": "2024-10-29T16:08:10",
"upload_time_iso_8601": "2024-10-29T16:08:10.254017Z",
"url": "https://files.pythonhosted.org/packages/2d/e2/540ba2b0201b315c8dfda24c624b2c630a3067e4e7da92a8fd35166a5343/polarion_rest_api_client-1.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-29 16:08:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DSD-DBS",
"github_project": "polarion-rest-api-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "polarion-rest-api-client"
}
