iots package

Submodules

iots.api module

class iots.api.API(host: str = 'https://api.swx.altairone.com', security_strategy: Optional[Union[AccessToken, OAuth2ClientCredentials]] = None, verify: bool = True)

Bases: _SpacesMethods

Creates a new API instance.

Parameters:

host – (optional) Host name of the Altair IoT Studio API.
security_strategy – (optional) The security strategy for the API client.
verify – (optional) Whether to verify the server’s TLS certificate.

make_request(method: str, url: str, body=None, params=None, headers: Optional[dict] = None, timeout: float = 3, auth: bool = True, verify=None) → Response

Makes a request to the API server.

Parameters:

method – HTTP request method used (GET, OPTIONS, HEAD, POST, PUT, PATCH, or DELETE).
url – Request URL. It can be a relative path or a full URL (the host used must be the same as the host in this API instance).
body – (optional) Dictionary, list of tuples, bytes, or file-like object to send in the body of the request.
params – (optional) Dictionary, list of tuples or bytes to send in the query string for the Request.
headers – (optional) Dictionary of HTTP headers to send.
timeout – (optional) How many seconds to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) tuple.
auth – (optional) If True (default), the authentication token will be sent in the request. An exception will be raised if no token is set.
verify – (optional) If set as a boolean, it will override the API verify value.

Returns:

An instance of request.Response.

revoke_token(): Revokes the access token.

set_credentials(client_id: str, client_secret: str, scopes: List[str], token_url: str = '/oauth2/token', revoke_token_url: str = '/oauth2/revoke', refresh_threshold: int = 10)

Configure an OAuth2 security strategy using the Client Credentials flow.

Parameters:

client_id – The client ID for OAuth2 client credentials authentication.
client_secret – The client secret for OAuth2 client credentials authentication.
scopes – The list of scopes to be requested during token exchange.
token_url – The URL for token exchange.
revoke_token_url – The URL for revoking access tokens (optional).
refresh_threshold – The number of seconds before token expiration to trigger token refresh.

Returns:

The modified API client.

set_token(token: str)

Sets an already exchanged access token as a bearer token security strategy.

Returns:: The modified API client.

with_security(security_strategy: Union[AccessToken, OAuth2ClientCredentials])

Sets the security strategy for the API client. If the provided security strategy requires token exchange and retrieval, the method will retrieve the access token automatically.

Parameters:: security_strategy (Union[AccessToken, OAuth2ClientCredentials]) – The security strategy to be set for the API client.
Returns:: The modified API client with the specified security strategy.

iots.apis.spaces module

class iots.apis.spaces.Spaces1(space: str)

Bases: APIResource, _CategoriesMethods, _ThingsMethods, _CommunicationsMethods

space: str

iots.apis.categories module

class iots.apis.categories.Categories1(category_name: str)

Bases: APIResource, _ThingsMethods

category_name: str

delete(**kwargs) → NoResponse

Deletes a Category.

📘 Information: The Things inside the Category will not be removed. They simply no longer belong to the deleted Category.

Returns:: The API response to the request.
Return type:: primitives.NoResponse

get(**kwargs) → Union[Category, ErrorResponse]

Returns the Category information.

Returns:: The API response to the request.
Return type:: Union[models.Category, models.ErrorResponse]

update(req: CategoryUpdate, **kwargs) → Union[Category, ErrorResponse]

Updates a Category.

🚧 Limitations: A Category cannot currently be renamed.

Parameters:: req (models.CategoryUpdate) – Request payload.
Returns:: The API response to the request.
Return type:: Union[models.Category, models.ErrorResponse]

class iots.apis.categories.Categories2

Bases: APIResource

create(req: CategoryCreate, **kwargs) → Union[Category, ErrorResponse]

Creates a new Category in the Space.

🚧 Limitations: A Category cannot currently be renamed.

Parameters:: req (models.CategoryCreate) – Request payload.
Returns:: The API response to the request.
Return type:: Union[models.Category, models.ErrorResponse]

get(**kwargs) → Union[CategoryList, ErrorResponse]

Returns the list of Categories in a Space.

🚧 Limitations: A maximum of 1000 Categories will be returned per page (50 by default).

Query parameters:

next_cursor (str): Cursor used to get the next page of results.
previous_cursor (str): Cursor used to get the previous page of results.
limit (int): The numbers of items to return.

Returns:: The API response to the request.
Return type:: Union[models.CategoryList, models.ErrorResponse]

iots.apis.things module

class iots.apis.things.Things1(thing_id: str)

Bases: APIResource, _ActionsMethods, _EventsMethods, _PropertiesMethods

delete(**kwargs) → NoResponse

Deletes the Thing with the given ID and all its related information (Properties history, graph relationships…).

Returns:: The API response to the request.
Return type:: primitives.NoResponse

get(**kwargs) → Union[Thing, ErrorResponse]

Returns the Thing with the given ID.

Returns:: The API response to the request.
Return type:: Union[models.Thing, models.ErrorResponse]

patch(req: Union[ThingPatch, list], **kwargs) → Union[Thing, ErrorResponse]

Partially updates a Thing with the given ID.

Parameters:: req (Union[models.ThingPatch, list]) – Request payload.
Returns:: The API response to the request.
Return type:: Union[models.Thing, models.ErrorResponse]

thing_id: str

update(req: ThingUpdate, **kwargs) → Union[Thing, ErrorResponse]

Updates the Thing with the given ID.

Parameters:: req (models.ThingUpdate) – Request payload.
Returns:: The API response to the request.
Return type:: Union[models.Thing, models.ErrorResponse]

class iots.apis.things.Things2

Bases: APIResource

create(req: ThingCreate, **kwargs) → Union[Thing, ErrorResponse]

Creates a new Thing inside a Space according to the WoT specification.

Parameters:: req (models.ThingCreate) – Request payload.
Returns:: The API response to the request.
Return type:: Union[models.Thing, models.ErrorResponse]

delete(**kwargs) → Union[ThingsDeleted, ErrorResponse]

Deletes all the existing information (Things and history) from all the Things matching the given filters.

📘 Information: To prevent accidental deletions, the operation will fail if no filters are provided.

⚠️ Warning: This operation can remove lots of Things in one go and without asking for confirmation, so make sure you know what you are doing!

Query parameters:

@type (str): Filter by @type.
thingID[] (list): Filter by multiple Thing IDs.
category[] (list): Filter by multiple Category names.
property (dict): This parameter adds a condition on the value of a Thing Property. Only the Things that meet this criteria will satisfy this filter.

Example: given the query parameters ?property:temp=gt:20&property:dim=80, a Thing will only match it if it has a temp Property with a value greater than 20 and a dim Property with a value equal to 80.

The format of this query parameter is:
```
property:<property_name>=<operator>:<value>
```
Multiple parameters following the previous format can be used in the same request to set multiple conditions. Note that a Thing must meet all the given conditions to match.

Supported value operators:
- eq → Equal (==). This is the default operator.
- neq → Not equal (!=)
- gt → Greater than (>)
- gte → Greater than or equal to (>=)
- lt → Less than (<)
- lte → Less than or equal to (<=)
Supported functions:
- contains → Check whether the value is contained in the Property value (the Property must be an array, string or object).
  
  Notes:
  - The string matching performed is case-sensitive.
  - If the Property type is string, the >, >=, < and <= operators will compare the values alphabetically.
  - If the Property type is not an array, string or object, the Thing will not satisfy the condition.
  - If the Property type is an object, it will check whether an attribute with the given name is present in it.

Returns:: The API response to the request.
Return type:: Union[models.ThingsDeleted, models.ErrorResponse]

get(**kwargs) → Union[ThingList, ErrorResponse]

Returns the list of Things.

Filters can be applied to return only the Things that match some criteria.

🚧 Limitations: A maximum of 1000 Things will be returned per page (50 by default).

Query parameters:

title (str): Filter by title.
@type (str): Filter by @type.
model (str): Filter by Model name.
version (int): Filter by Version number. model query parameter must be also present.
thingID[] (list): Filter by multiple Thing IDs.
category[] (list): Filter by multiple Category names.
in_category (bool): If true, only Things within some Category will be listed. If false, only Things not associated to any Category will be listed. If omitted, all Things will be listed.
sort (list): Sort items by one or more fields in any order.

Example: Using sort=uid,+title,-created will return the results ordered by ascending uid, ascending title and descending created (having uid the highest priority and created the lowest).

Any Thing Description attribute can be used for sorting, even if it is specific to a Thing or deeply nested.

Example: To get all the Things sorted by the value of the temperature Property in descending order, you can use sort=-status.temperature. The result won’t filter out the Things that don’t have the temperature Property, but they will be placed at the end of the list.
property (dict): This parameter adds a condition on the value of a Thing Property. Only the Things that meet this criteria will satisfy this filter.

Example: given the query parameters ?property:temp=gt:20&property:dim=80, a Thing will only match it if it has a temp Property with a value greater than 20 and a dim Property with a value equal to 80.

The format of this query parameter is:
```
property:<property_name>=<operator>:<value>
```
Multiple parameters following the previous format can be used in the same request to set multiple conditions. Note that a Thing must meet all the given conditions to match.

Supported value operators:
- eq → Equal (==). This is the default operator.
- neq → Not equal (!=)
- gt → Greater than (>)
- gte → Greater than or equal to (>=)
- lt → Less than (<)
- lte → Less than or equal to (<=)
Supported functions:
- contains → Check whether the value is contained in the Property value (the Property must be an array, string or object).
  
  Notes:
  - The string matching performed is case-sensitive.
  - If the Property type is string, the >, >=, < and <= operators will compare the values alphabetically.
  - If the Property type is not an array, string or object, the Thing will not satisfy the condition.
  - If the Property type is an object, it will check whether an attribute with the given name is present in it.
links.rel (str): Filter by type of link relationship (rel).
links.href (str): Filter by link href.
next_cursor (str): Cursor used to get the next page of results.
previous_cursor (str): Cursor used to get the previous page of results.
limit (int): The numbers of items to return.

Returns:: The API response to the request.
Return type:: Union[models.ThingList, models.ErrorResponse]

patch(req: Union[ThingsPatch, list], **kwargs) → Union[ThingsPatchMultiStatus, ErrorResponse]

Partially updates Things with the given IDs.

Parameters:: req (Union[models.ThingsPatch, list]) – Request payload.
Returns:: The API response to the request.
Return type:: Union[models.ThingsPatchMultiStatus, models.ErrorResponse]

iots.apis.actions module

class iots.apis.actions.Actions1(action_name: str, action_id: str)

Bases: APIResource

action_id: str

action_name: str

delete(**kwargs) → NoResponse

Deletes a Thing Action resource.

Returns:: The API response to the request.
Return type:: primitives.NoResponse

get(**kwargs) → Union[ActionResponse, ErrorResponse]

Returns a Thing Action resource.

Returns:: The API response to the request.
Return type:: Union[models.ActionResponse, models.ErrorResponse]

update(req: Union[ActionUpdateRequest, dict], **kwargs) → Union[ActionResponse, ErrorResponse]

Updates a Thing Action resource.

Parameters:: req (Union[models.ActionUpdateRequest, dict]) – Request payload.
Returns:: The API response to the request.
Return type:: Union[models.ActionResponse, models.ErrorResponse]

class iots.apis.actions.Actions2(action_name: str)

Bases: APIResource

action_name: str

create(req: Union[ActionCreateRequest, dict], **kwargs) → Union[ActionResponse, ErrorResponse]

Creates a new Action resource for the given Thing’s Action.

🚧 Limitations: A maximum of 100 Action resources will be stored.

Parameters:: req (Union[models.ActionCreateRequest, dict]) – Request payload.
Returns:: The API response to the request.
Return type:: Union[models.ActionResponse, models.ErrorResponse]

get(**kwargs) → Union[ActionListResponse, ErrorResponse]

Returns the list of Action resources of the given Thing’s Action.

🚧 Limitations: A maximum of 100 Action resources will be stored and returned (50 by default per page).

Query parameters:

next_cursor (str): Cursor used to get the next page of results.
previous_cursor (str): Cursor used to get the previous page of results.
limit (int): The numbers of items to return.

Returns:: The API response to the request.
Return type:: Union[models.ActionListResponse, models.ErrorResponse]

class iots.apis.actions.Actions3

Bases: APIResource

get(**kwargs) → Union[ActionListResponse, ErrorResponse]

Returns the list of Action resources of the given Thing.

🚧 Limitations: A maximum of 100 Action resources per Action will be stored and returned (50 by default per page).

Query parameters:

next_cursor (str): Cursor used to get the next page of results.
previous_cursor (str): Cursor used to get the previous page of results.
limit (int): The numbers of items to return.

Returns:: The API response to the request.
Return type:: Union[models.ActionListResponse, models.ErrorResponse]

iots.apis.events module

class iots.apis.events.Events1(event_name: str, event_id: str)

Bases: APIResource

delete(**kwargs) → NoResponse

Deletes a Thing Event resource.

Returns:: The API response to the request.
Return type:: primitives.NoResponse

event_id: str

event_name: str

get(**kwargs) → Union[EventResponse, ErrorResponse]

Returns a Thing Event resource.

Returns:: The API response to the request.
Return type:: Union[models.EventResponse, models.ErrorResponse]

class iots.apis.events.Events2(event_name: str)

Bases: APIResource

create(req: Union[EventCreateRequest, dict], **kwargs) → Union[EventResponse, ErrorResponse]

Creates a new Event resource for the given Thing’s Event.

🚧 Limitations: A maximum of 100 Event resources will be stored.

🚧 Limitations: This operation will only work in the scope of the given Category.

Parameters:: req (Union[models.EventCreateRequest, dict]) – Request payload.
Returns:: The API response to the request.
Return type:: Union[models.EventResponse, models.ErrorResponse]

event_name: str

get(**kwargs) → Union[EventListResponse, ErrorResponse]

Returns the list of Event resources of the given Thing’s Event.

🚧 Limitations: A maximum of 100 Event resources will be stored and returned (50 by default per page).

Query parameters:

next_cursor (str): Cursor used to get the next page of results.
previous_cursor (str): Cursor used to get the previous page of results.
limit (int): The numbers of items to return.

Returns:: The API response to the request.
Return type:: Union[models.EventListResponse, models.ErrorResponse]

class iots.apis.events.Events3

Bases: APIResource

get(**kwargs) → Union[EventListResponse, ErrorResponse]

Returns the list of Event resources of the given Thing.

🚧 Limitations: A maximum of 100 Event resources per Event will be stored and returned (50 by default per page).

Query parameters:

next_cursor (str): Cursor used to get the next page of results.
previous_cursor (str): Cursor used to get the previous page of results.
limit (int): The numbers of items to return.

Returns:: The API response to the request.
Return type:: Union[models.EventListResponse, models.ErrorResponse]

iots.apis.properties module

class iots.apis.properties.Properties1(property: str)

Bases: APIResource

get(**kwargs) → Union[Property, ErrorResponse]

Returns the value of a Thing Property.

Returns:: The API response to the request.
Return type:: Union[models.Property, models.ErrorResponse]

property: str

update(value, **kwargs) → Union[Properties, ErrorResponse]

Updates the value of a Thing Property.

Query parameters:

update_history (bool): Indicates whether the values should be stored in the Properties history. By default, the values will be added to the history so that they can be retrieved later using the Properties History API.

Parameters:: value – The new value of the Property.
Returns:: The API response to the request.
Return type:: Union[models.Properties, models.ErrorResponse]

class iots.apis.properties.Properties2

Bases: APIResource

get(**kwargs) → Union[Properties, ErrorResponse]

Returns all the Property values of a Thing.

Returns:: The API response to the request.
Return type:: Union[models.Properties, models.ErrorResponse]

update(req: Union[Properties, dict], **kwargs) → Union[Properties, ErrorResponse]

Updates the values of one or more Properties of a Thing.

Query parameters:

update_history (bool): Indicates whether the values should be stored in the Properties history. By default, the values will be added to the history so that they can be retrieved later using the Properties History API.

Parameters:: req (Union[models.Properties, dict]) – Request payload.
Returns:: The API response to the request.
Return type:: Union[models.Properties, models.ErrorResponse]

iots.apis.communications module

class iots.apis.communications.Communications1: Bases: APIResource, _EmailMethods

iots.apis.email module

class iots.apis.email.Email1

Bases: APIResource

send(req: Union[Email, dict], **kwargs) → NoResponse

Sends a new e-mail to one or more recipients.

🚧 Limitations: Including links, styles, images and other potentially dangerous information in the message content is not allowed. The message will be sanitized and these items will be removed before the email is sent.

Parameters:: req (Union[models.Email, dict]) – Request payload.
Returns:: The API response to the request.
Return type:: primitives.NoResponse

iots.security module

class iots.security.AccessToken(token: str)

Bases: SecurityStrategy

Security strategy for handling Bearer token authentication.

This class is a concrete implementation of SecurityStrategy, specifically designed to handle authentication using a Bearer token. It applies the Bearer token to the Authorization header of the request.

Methods:

apply(request): Apply security measures to the given request.
clean(): Clean sensitive information from the security strategy.

Parameters:: token (str) – The Bearer token used for authentication.

apply(request: Request)

Apply security measures by adding the Bearer token to the request header.

Parameters:: request – The request object to which security measures will be applied.

clean()

Clean sensitive information from the security strategy.

This method clears the stored Bearer token, ensuring sensitive information is removed from memory.

class iots.security.OAuth2ClientCredentials(client_id: str, client_secret: str, scopes: List[str], token_url: str = 'https://api.swx.altairone.com/oauth2/token', revoke_token_url: str = '', refresh_threshold: int = 10, verify: bool = True)

Bases: SecurityStrategyWithTokenExchange

Security strategy for handling OAuth2 client credentials authentication.

This class is a concrete implementation of SecurityStrategyWithTokenExchange, specifically designed to handle authentication using OAuth2 client credentials. It exchanges client credentials for an access token and applies it to the Authorization header of the request.

Methods:

apply_security(request): Apply security measures to the given request.
clean(): Clean sensitive information from the security strategy.
set_token_url_host(token_url_host): Set the host URL for token exchange.
set_verify_tls_certificate(verify): Set whether to verify the authentication server’s TLS certificate.
get_token(): Exchange and retrieve an access token from the token server.
revoke_token(): Revoke the currently held access token, if supported.

Parameters:

client_id (str) – The client ID for OAuth2 client credentials authentication.
client_secret (str) – The client secret for OAuth2 client credentials authentication.
scopes (List[str]) – The list of scopes to be requested during token exchange.
token_url (str) – The URL for token exchange.
revoke_token_url (str) – The URL for revoking access tokens (optional).
refresh_threshold (int) – The number of seconds before token expiration to trigger token refresh.

apply(request: Request)

Apply security measures by adding the OAuth2 access token to the request header.

If the access token is not present or close to expiration, it is refreshed before applying.

Parameters:: request – The request object to which security measures will be applied.

clean()

Clean sensitive information from the security strategy.

This method revokes the currently held access token, if supported, ensuring sensitive information is removed from memory.

get_token()

Exchange and retrieve an access token from the token server.

This method exchanges client credentials for an access token with the token server and stores the token for subsequent use.

revoke_token()

Revoke the currently held access token, if supported.

This method revokes the currently held access token from the token server, if a token revocation URL is provided and the token is still valid.

set_token_url_host(token_url_host: str)

Set the host URL for token exchange.

Parameters:: token_url_host – The host URL for token exchange.

set_verify_tls_certificate(verify: bool)

Set whether to verify the authentication server’s TLS certificate.

Parameters:: verify – Whether to verify the server’s TLS certificate.

class iots.security.SecurityStrategy

Bases: ABC

Abstract base class for defining security strategies in an API client.

Subclasses of SecurityStrategy are responsible for applying security measures such as authentication and authorization to API requests.

Methods:

apply(request): Apply security measures to the given request.
clean(): Clean sensitive information from the security strategy.

This class serves as a template for implementing different security strategies, allowing flexibility in handling various authentication mechanisms such as Bearer tokens, Basic authentication, OAuth2, etc.

The apply() method should be implemented by subclasses to apply the specific security measures required for the given request. It may involve adding headers, parameters, or performing other actions necessary to authenticate and authorize the request.

The clean() method should be implemented by subclasses to perform any necessary cleanup tasks such as revoking tokens or cleaning sensitive data from the security strategy when it is no longer needed.

abstract apply(request: Request)

Apply security measures to the given request.

Parameters:: request (Request) – The request object to which security measures will be applied.

This method is implemented by subclasses to apply the specific security measures required for the given request. It may involve adding headers, parameters, or performing other actions necessary to authenticate and authorize the request.

abstract clean()

Clean sensitive information from the security strategy.

This method should be implemented by subclasses to perform any necessary cleanup tasks such as revoking tokens or cleaning sensitive data from the security strategy when it is no longer needed.

class iots.security.SecurityStrategyWithTokenExchange

Bases: SecurityStrategy

Abstract base class for defining security strategies in an API client that require token exchange and revocation logic with a server.

Subclasses of SecurityStrategyWithTokenExchange extend SecurityStrategy and provide additional methods for token exchange and revocation with a token server.

Methods:

apply(request): Apply security measures to the given request.
clean(): Clean sensitive information from the security strategy.
set_token_url_host(token_url_host): Set the host URL for token exchange.
set_verify_tls_certificate(verify): Set whether to verify the authentication server’s TLS certificate.
get_token(): Exchange and retrieve a token from the server.
revoke_token(): Revoke the currently held token.

This class serves as a template for implementing security strategies that involve exchanging tokens with a token server, such as OAuth2 or other token-based authentication mechanisms.

abstract get_token()

Exchange and retrieve a token from the server.

This method should be implemented by subclasses to exchange credentials with the token server and retrieve a token.

Returns:: The retrieved token.

abstract revoke_token()

Revoke the currently held token.

This method should be implemented by subclasses to revoke the currently held token from the token server, if supported by the security strategy.

abstract set_token_url_host(token_url_host: str)

Set the host URL for token exchange.

This method should be implemented by subclasses to set the host URL where tokens can be exchanged with the server.

Parameters:: token_url_host – The host URL for token exchange.

abstract set_verify_tls_certificate(verify: bool)

Set whether to verify the authentication server’s TLS certificate.

This method should be implemented by subclasses to set the host URL where tokens can be exchanged with the server.

Parameters:: verify – Whether to verify the server’s TLS certificate.

iots.models.exceptions module

exception iots.models.exceptions.APIException: Bases: Exception

exception iots.models.exceptions.ExceptionList(msg: str, exceptions: List[Exception], *attr): Bases: APIException

exception iots.models.exceptions.ResponseError(error, *attr)

Bases: APIException

Client or server error response.

http_response() → Response

iots package

Submodules

iots.api module

iots.apis.spaces module

iots.apis.categories module

iots.apis.things module

iots.apis.actions module

iots.apis.events module

iots.apis.properties module

iots.apis.communications module

iots.apis.email module

iots.security module

iots.models.exceptions module

Module contents

Subpackages