# Altair IoT Studio API Client <!-- NODOC -->
**A Python client for the Altair® IoT Studio™ API** <!-- NODOC -->
[](https://pypi.org/project/iots)
[](https://pypi.org/project/iots)
[](https://iots.readthedocs.io/en/latest/) <!-- NODOC -->
## Introduction
This library allows you to interact with the Altair® IoT Studio™ API using
Python. The current implementation has support for the following APIs:
- [AnythingDB](https://openapi.swx.altairone.com/cloud/anything-db):
- [Categories API](https://openapi.swx.altairone.com/cloud/anything-db#/Categories)
- [Things API](https://openapi.swx.altairone.com/cloud/anything-db#/Things)
- [Properties API](https://openapi.swx.altairone.com/cloud/anything-db#/Properties)
- [Actions API](https://openapi.swx.altairone.com/cloud/anything-db#/Actions)
- [Events API](https://openapi.swx.altairone.com/cloud/anything-db#/Events)
- Communications API
## Install
From PyPI:
```shell
pip install iots
```
This library officially supports Python 3.8+.
## The API class
All the requests are made using an instance of the `API` class.
```python
from iots import API
api = API()
```
By default, the API class will use the host `https://api.swx.altairone.com`.
You can also specify a different host:
```python
from iots import API
api = API(host="https://api.my-iot-studio.com")
```
### Authentication
There are multiple ways to deal with authentication:
- Setting an already-exchanged access token:
```python
api = API().set_token("my-access-token")
```
- Using an OAuth2 client credentials with manual token revocation:
```python
my_client_id = "my-client-id"
my_client_secret = "my-client-secret"
my_scopes = ["category", "thing"]
api = API().set_credentials(my_client_id, my_client_secret, my_scopes)
# ...
api.revoke_token()
```
- Using an OAuth2 client credentials with automatic token revocation:
```python
with API().set_credentials(my_client_id, my_client_secret, my_scopes) as api:
# ...
# The token will be revoked when the 'with' block ends
# or if the code returns or raises an exception
```
**Tokens are automatically refreshed** using OAuth2 client credentials, so you
don't need to care about manually refreshing them.
## Using the API
The `API` class uses a nested syntax to allow accessing the API resources,
setting the request information with the same structure order that the one used
by the API endpoints. Some examples:
```python
# Get an instance of a Space that will be used to access resources later.
# Creating this instance will NOT make any request to the API.
space = api.spaces("my-iot-project")
# Get all the Categories in the Space
categories = space.categories().get()
# Get a specific Thing
thing = space.things("01GQ2E9M2Y45BX9EW0F2BM032Q").get()
# Get all the Things inside a Category
things = space.categories("Sensors").things().get()
# Get all the Things with some query parameters
things = space.things().get(params={"property:temperature": "gt:20"})
# Get all the Property values of a Thing
thing_properties = space.things("01GQ2E9M2Y45BX9EW0F2BM032Q").properties().get()
# ... and access to the 'temperature' Property
temperature = thing_properties['temperature']
# Get a specific Property value
thing_property = space.things("01GQ2E9M2Y45BX9EW0F2BM032Q").properties("temperature").get()
temperature = thing_properties['temperature']
# Update a Property value
thing_property = space.things("01GQ2E9M2Y45BX9EW0F2BM032Q").properties("temperature").update(17.3)
# Create a new Action value
action = space.things("01GQ2E9M2Y45BX9EW0F2BM032Q").actions("updateFirmware").create({"updateFirmware": {"input": "v2.0.0"}})
```
The models used by the API for request and response data can be found in the
`iots.models.models` module.
> 💡 **Note:** The API resources use type hints that should help to understand
> how to use the API and the data models to define input data or access
> response data. It should also help your IDE with code completion and
> displaying documentation.
### Query parameters
To add any query parameter to a request, use the `param` argument with a
dictionary of parameters:
```python
# Return up to 100 Things that have a "temperature" Property with value >= 20
things = space.things().get(params={
'property:temperature': 'gte:20',
'limit': 100,
})
```
### Pagination
Some resource listing operations support pagination. You can iterate the
response instances to retrieve all the results. If additional API calls are
needed to fetch the remaining results, they will be made behind the scenes.
```python
# Get all the Things in a Space
things = space.things().get()
for t in things:
print(t.uid)
```
### Get raw HTTP response
Making an API request returns an instance of an object that represents the
response content. However, you can also access the original response using the
`http_response()` method.
```python
things = api.spaces("my-iot-project").things().get()
# Get the raw response as an instance of requests.Response
raw_response = things.http_response()
status_code = raw_response.status_code
content = raw_response.content
body = raw_response.json()
# ...
```
This method is also available in the raised exceptions, provided that a response
has been returned from the server.
```python
from iots.models.exceptions import ResponseError
try:
things = api.spaces("my-iot-project").things().get()
except ResponseError as e:
raw_response = e.http_response()
```
### TLS certificate verification
If you need to skip the TLS certificate verification, you can use the `verify`
argument when creating the `API` instance:
```python
api = API(verify=False)
```
## 🔮 Future features
- Add more API resource components.
- Support for asynchronous requests.
Raw data
{
"_id": null,
"home_page": "https://github.com/altairengineering/iots-python",
"name": "iots",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": "iot, altair, smartcore, smartworks, api, client, library",
"author": "Daniel S\u00e1nchez Gallego",
"author_email": "dsanchez@altair.com",
"download_url": "https://files.pythonhosted.org/packages/2f/31/f0adb3fe723992171df484a855ca289d47f8185bd87e74db82e512a24f9e/iots-0.4.0.tar.gz",
"platform": null,
"description": "# Altair IoT Studio API Client <!-- NODOC -->\n\n**A Python client for the Altair\u00ae IoT Studio\u2122 API** <!-- NODOC -->\n\n[](https://pypi.org/project/iots)\n[](https://pypi.org/project/iots)\n[](https://iots.readthedocs.io/en/latest/) <!-- NODOC -->\n\n## Introduction\n\nThis library allows you to interact with the Altair\u00ae IoT Studio\u2122 API using\nPython. The current implementation has support for the following APIs:\n\n- [AnythingDB](https://openapi.swx.altairone.com/cloud/anything-db):\n - [Categories API](https://openapi.swx.altairone.com/cloud/anything-db#/Categories)\n - [Things API](https://openapi.swx.altairone.com/cloud/anything-db#/Things)\n - [Properties API](https://openapi.swx.altairone.com/cloud/anything-db#/Properties)\n - [Actions API](https://openapi.swx.altairone.com/cloud/anything-db#/Actions)\n - [Events API](https://openapi.swx.altairone.com/cloud/anything-db#/Events)\n- Communications API\n\n## Install\n\nFrom PyPI:\n\n```shell\npip install iots\n```\n\nThis library officially supports Python 3.8+.\n\n## The API class\n\nAll the requests are made using an instance of the `API` class.\n```python\nfrom iots import API\n\napi = API()\n ```\n\nBy default, the API class will use the host `https://api.swx.altairone.com`.\nYou can also specify a different host:\n```python\nfrom iots import API\n\napi = API(host=\"https://api.my-iot-studio.com\")\n```\n\n### Authentication\n\nThere are multiple ways to deal with authentication:\n\n- Setting an already-exchanged access token:\n \n ```python\n api = API().set_token(\"my-access-token\")\n ```\n\n- Using an OAuth2 client credentials with manual token revocation:\n \n ```python\n my_client_id = \"my-client-id\"\n my_client_secret = \"my-client-secret\"\n my_scopes = [\"category\", \"thing\"]\n api = API().set_credentials(my_client_id, my_client_secret, my_scopes)\n \n # ...\n \n api.revoke_token()\n ```\n\n- Using an OAuth2 client credentials with automatic token revocation:\n \n ```python\n with API().set_credentials(my_client_id, my_client_secret, my_scopes) as api:\n # ...\n # The token will be revoked when the 'with' block ends\n # or if the code returns or raises an exception\n ```\n\n**Tokens are automatically refreshed** using OAuth2 client credentials, so you\ndon't need to care about manually refreshing them.\n\n## Using the API\n\nThe `API` class uses a nested syntax to allow accessing the API resources,\nsetting the request information with the same structure order that the one used\nby the API endpoints. Some examples:\n\n```python\n# Get an instance of a Space that will be used to access resources later.\n# Creating this instance will NOT make any request to the API.\nspace = api.spaces(\"my-iot-project\")\n\n# Get all the Categories in the Space\ncategories = space.categories().get()\n\n# Get a specific Thing\nthing = space.things(\"01GQ2E9M2Y45BX9EW0F2BM032Q\").get()\n\n# Get all the Things inside a Category\nthings = space.categories(\"Sensors\").things().get()\n\n# Get all the Things with some query parameters\nthings = space.things().get(params={\"property:temperature\": \"gt:20\"})\n\n# Get all the Property values of a Thing\nthing_properties = space.things(\"01GQ2E9M2Y45BX9EW0F2BM032Q\").properties().get()\n# ... and access to the 'temperature' Property\ntemperature = thing_properties['temperature']\n\n# Get a specific Property value\nthing_property = space.things(\"01GQ2E9M2Y45BX9EW0F2BM032Q\").properties(\"temperature\").get()\ntemperature = thing_properties['temperature']\n\n# Update a Property value\nthing_property = space.things(\"01GQ2E9M2Y45BX9EW0F2BM032Q\").properties(\"temperature\").update(17.3)\n\n# Create a new Action value\naction = space.things(\"01GQ2E9M2Y45BX9EW0F2BM032Q\").actions(\"updateFirmware\").create({\"updateFirmware\": {\"input\": \"v2.0.0\"}})\n```\n\nThe models used by the API for request and response data can be found in the\n`iots.models.models` module.\n\n> \ud83d\udca1 **Note:** The API resources use type hints that should help to understand\n> how to use the API and the data models to define input data or access\n> response data. It should also help your IDE with code completion and\n> displaying documentation.\n\n### Query parameters\n\nTo add any query parameter to a request, use the `param` argument with a\ndictionary of parameters:\n\n```python\n# Return up to 100 Things that have a \"temperature\" Property with value >= 20\nthings = space.things().get(params={\n 'property:temperature': 'gte:20',\n 'limit': 100,\n})\n```\n\n### Pagination\n\nSome resource listing operations support pagination. You can iterate the\nresponse instances to retrieve all the results. If additional API calls are\nneeded to fetch the remaining results, they will be made behind the scenes.\n\n```python\n# Get all the Things in a Space\nthings = space.things().get()\n\nfor t in things:\n print(t.uid)\n```\n\n### Get raw HTTP response\n\nMaking an API request returns an instance of an object that represents the\nresponse content. However, you can also access the original response using the\n`http_response()` method.\n\n```python\nthings = api.spaces(\"my-iot-project\").things().get()\n# Get the raw response as an instance of requests.Response\nraw_response = things.http_response()\n\nstatus_code = raw_response.status_code\ncontent = raw_response.content\nbody = raw_response.json()\n# ...\n```\n\nThis method is also available in the raised exceptions, provided that a response\nhas been returned from the server.\n\n```python\nfrom iots.models.exceptions import ResponseError\n\ntry:\n things = api.spaces(\"my-iot-project\").things().get()\nexcept ResponseError as e:\n raw_response = e.http_response()\n```\n\n### TLS certificate verification\n\nIf you need to skip the TLS certificate verification, you can use the `verify`\nargument when creating the `API` instance:\n\n```python\napi = API(verify=False)\n```\n\n\n## \ud83d\udd2e Future features\n- Add more API resource components.\n- Support for asynchronous requests.\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python client for the Altair IoT Studio API",
"version": "0.4.0",
"project_urls": {
"Documentation": "https://iots.readthedocs.io/",
"Homepage": "https://github.com/altairengineering/iots-python",
"Repository": "https://github.com/altairengineering/iots-python"
},
"split_keywords": [
"iot",
" altair",
" smartcore",
" smartworks",
" api",
" client",
" library"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4ba6cdf34c02112cb3aab76dce9fd61fd57fcdba1132ce7a3d4d992890a7c1d9",
"md5": "1e1cbec6807d6aa533d4c02478be2782",
"sha256": "f60693944e65ad9e003ebd193ba53b801cf2226bd1158f287a3a56b64af8d7e6"
},
"downloads": -1,
"filename": "iots-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1e1cbec6807d6aa533d4c02478be2782",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 50753,
"upload_time": "2024-09-05T10:25:30",
"upload_time_iso_8601": "2024-09-05T10:25:30.190437Z",
"url": "https://files.pythonhosted.org/packages/4b/a6/cdf34c02112cb3aab76dce9fd61fd57fcdba1132ce7a3d4d992890a7c1d9/iots-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2f31f0adb3fe723992171df484a855ca289d47f8185bd87e74db82e512a24f9e",
"md5": "ebafad1ca094ffadd0a970a01a0c2111",
"sha256": "161dc521fd39b06bab5979be07411d4081f10fa84f94e289dfb674982014096c"
},
"downloads": -1,
"filename": "iots-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "ebafad1ca094ffadd0a970a01a0c2111",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 41992,
"upload_time": "2024-09-05T10:25:34",
"upload_time_iso_8601": "2024-09-05T10:25:34.963603Z",
"url": "https://files.pythonhosted.org/packages/2f/31/f0adb3fe723992171df484a855ca289d47f8185bd87e74db82e512a24f9e/iots-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-05 10:25:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "altairengineering",
"github_project": "iots-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "iots"
}
JSON
