Python Reference

AI Models

opengate_data.ai_models.ai_models

AIModelsBuilder

AIModelsBuilder Objects

class AIModelsBuilder()

AI Model Builder

with_organization_name

def with_organization_name(organization_name: str) -> "AIModelsBuilder"

Specify the organization name.

Arguments:

organization_name str - The name of the organization.

Returns:

AIModelsBuilder - Returns self for chaining.

Example:

builder.with_organization_name('organization_name')

with_identifier

def with_identifier(identifier: str) -> "AIModelsBuilder"

Specify the identifier for the pipeline.

Arguments:

identifier str - The identifier for the pipeline.

Returns:

AIModelsBuilder - Returns self for chaining.

Example:

builder.with_identifier('identifier')

with_env

def with_env(data_env: str) -> "AIModelsBuilder"

Specify the environment variable.

Arguments:

data_env str - The environment variable.

Returns:

AIModelsBuilder - Returns self for chaining.

Example:

builder.with_env('MODEL_ID')

with_find_by_name

def with_find_by_name(find_name: str) -> "AIModelsBuilder"

Specify the name to find.

Arguments:

find_name str - The name of the model.

Returns:

AIModelsBuilder - Returns self for chaining.

Example:

builder.with_find_by_name('model_name.onnx')

with_config_file

def with_config_file(config_file: str, section: str,
                     config_key: str) -> "AIModelsBuilder"

Sets up the configuration file (.ini).

This method allows specifying a configuration file, a section within that file, and a key to retrieve a specific value from the section.

Arguments:

config_file str - The path to the.ini configuration file.
section str - The section name within the.ini file where the desired configuration is located.
config_key str - The key within the specified section whose value will be retrieved.

Raises:

TypeError - If the provided config_file is not a string.
TypeError - If the provided section is not a string.
TypeError - If the provided config_key is not a string.

Returns:

AIModelsBuilder - Returns itself to allow for method chaining.

Example:

[id]
model_id = afe07216-14ec-4134-97ae-c483b11d965a
builder.with_config_file('model_config.ini', 'id', 'model_id')

add_file

def add_file(file: str) -> "AIModelsBuilder"

Attaches the model file to upload, in PMML or ONNX format.

Arguments:

file str - The path to the file to be added.

Returns:

AIModelsBuilder - Returns itself to allow for method chaining.

Raises:

TypeError - If the provided file path is not a string.

Example:

builder.add_file('file.onnx')

with_prediction

def with_prediction(data_prediction: dict) -> "AIModelsBuilder"

Prediction with a model

Arguments:

data_prediction dict - Prediction

Raises:

TypeError - If the prediction is not a dict.

Returns:

AIModelsBuilder - Returns itself to allow for method chaining.

Example:

prediction = {
- `"X"` - [
{
- `"input_8"` - [
[
-0.5391107438074961,
-0.15950019784171535,
]
]
}
]
}
builder.with_prediction(prediction)

with_output_file_path

def with_output_file_path(output_file_path: str) -> "AIModelsBuilder"

Sets the output file path for the model.

This method allows you to specify the path where the output file will be saved. It is particularly useful for operations that involve downloading or saving files.

Arguments:

output_file_path str - The path where the output file will be saved.

Returns:

AIModelsBuilder - The instance of the AIModelsBuilder class.

Example:

builder.with_output_file_path("rute/prueba.onnx")

create

def create() -> "AIModelsBuilder"

Initiates the creation process of a new model.

This method prepares the AIModelsBuilder instance to create a new model by setting up the necessary parameters such as the organization name and the file to be associated with the model.

Returns:

AIModelsBuilder - The instance of the AIModelsBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name("MyOrganization").add_file("example.onnx").create()

find_one

def find_one() -> "AIModelsBuilder"

Retrieve a single model.

This method sets up the AIModelsBuilder instance to retrieve a specific model associated with the specified organization and identifier.

Returns:

AIModelsBuilder - The instance of the AIModelsBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name("organization_name").with_identifier("model_identifier").find_one()

find_all

def find_all() -> "AIModelsBuilder"

Retrieve all models.

This method sets up the AIModelsBuilder instance to retrieve all models associated with the specified organization.

Returns:

AIModelsBuilder - The instance of the AIModelsBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name("MyOrganization").find_all()

update

def update() -> "AIModelsBuilder"

Update an existing model.

This method sets up the AIModelsBuilder instance to update a specific model associated with the specified organization and identifier.

Returns:

AIModelsBuilder - The instance of the AIModelsBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name("MyOrganization").with_identifier("model_identifier").add_file("updated_model.onnx").update()
builder.with_organization_name("MyOrganization").with_find_by_name("model_name.onnx").add_file("updated_model.onnx").update()
builder.with_organization_name("MyOrganization").with_config_file('model_config.ini', 'id', 'model').add_file("updated_model.onnx").update()

delete

def delete() -> "AIModelsBuilder"

Delete an existing model within the organization.

This method sets up the AIModelsBuilder instance to delete a specific model associated with the specified organization and identifier.

Returns:

AIModelsBuilder - The instance of the AIModelsBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name("MyOrganization").with_identifier("model_identifier").delete()
builder.with_organization_name("MyOrganization").with_find_by_name("model_name.onnx").delete()
builder.with_organization_name("MyOrganization").with_config_file('model_config.ini', 'id', 'model').delete()

validate

def validate() -> "AIModelsBuilder"

Validate the model configuration.

This method sets up the AIModelsBuilder instance to validate the configuration of a model associated with the specified organization.

Returns:

AIModelsBuilder - The instance of the AIModelsBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name("MyOrganization").add_file("model.onnx").validate()

download

def download() -> "AIModelsBuilder"

Download the model file.

This method sets up the AIModelsBuilder instance to download the file of a specific model associated with the specified organization and identifier.

Returns:

AIModelsBuilder - The instance of the AIModelsBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name("MyOrganization").with_identifier("model_identifier").with_output_file_path("model.onnx").download()
builder.with_organization_name("MyOrganization").with_find_by_name("model_name.onnx").with_output_file_path("model.onnx").download()
builder.with_organization_name("MyOrganization").with_config_file('model_config.ini', 'id', 'model').with_output_file_path("model.onnx").download()

prediction

def prediction() -> "AIModelsBuilder"

Make a prediction using the model.

This method sets up the AIModelsBuilder instance to make a prediction using a specific model associated with the specified organization and identifier.

Returns:

AIModelsBuilder - The instance of the AIModelsBuilder class itself, allowing for method chaining.

Example:

prediction_data = {
- `"X"` - [
{
- `"input_8"` - [
[
-0.5391107438074961,
-0.15950019784171535,
]
]
}
]
}
builder.with_organization_name("MyOrganization").with_identifier("model_identifier").with_prediction(prediction_data).prediction()
builder.with_organization_name("MyOrganization").with_find_by_name("model_name.onnx").with_prediction(prediction_data).prediction()
builder.with_organization_name("MyOrganization").with_config_file('model_config.ini', 'id', 'model').with_prediction(prediction_data).prediction()

save

def save() -> "AIModelsBuilder"

Save the model configuration.

This method sets up the AIModelsBuilder instance to save the configuration of a model associated with the specified organization.

Returns:

AIModelsBuilder - The instance of the AIModelsBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name("MyOrganization").with_env("env_var").save()
builder.with_organization_name("MyOrganization").with_config_file('model_config.ini', 'id', 'model').save()

set_config_file_identifier

def set_config_file_identifier() -> "AIModelsBuilder"

Selects the operation that writes the model identifier into a configuration file.

It stores the identifier given to with_identifier() under the section and key named with with_config_file(), so a later run can pick the model up from the file instead of carrying its identifier in the code. The key must already exist in the file.

Returns:

AIModelsBuilder - Returns itself to allow for method chaining.

Example:

builder.with_identifier("model_identifier").with_config_file(
'model_config.ini', 'id', 'model_id'
).set_config_file_identifier().build().execute()

set_env_identifier

def set_env_identifier() -> "AIModelsBuilder"

Selects the operation that writes the model identifier into the .env file.

It stores the identifier given to with_identifier() under the variable named with with_env(), so a later run can pick the model up from the environment. The variable must already exist in the .env file.

Returns:

AIModelsBuilder - Returns itself to allow for method chaining.

Raises:

ValueError - If the variable is not in the .env file.

Example:

builder.with_identifier("model_identifier").with_env(
"MODEL_ID"
).set_env_identifier().build().execute()

build

def build() -> "AIModelsBuilder"

Finalizes the construction of the IoT collection configuration.

This method prepares the builder to execute the collection by ensuring all necessary configurations are set and validates the overall integrity of the build. It should be called before executing the collection to ensure that the configuration is complete and valid.

The build process involves checking that mandatory fields such as the device identifier are set. It also ensures that method calls that are incompatible with each other (like build and build_execute) are not both used.

Returns:

AIModelsBuilder - Returns itself to allow for method chaining, enabling further actions like execute.

Raises:

ValueError - If required configurations are missing or if incompatible methods are used together.

Example:

builder.build()

build_execute

def build_execute()

Executes the data sets search immediately after building the configuration.

This method is a shortcut that combines building and executing in a single step.

Returns:

dict - A dictionary containing the execution response which includes the status code and potentially other metadata about the execution.

Raises:

ValueError - If build has already been called on this builder instance.

Example:

builder.build_execute()

execute

def execute() -> Response

Execute the configured operation and return the response.

This method executes the operation that has been configured using the builder pattern. It ensures that the build method has been called and that it is the last method invoked before execute. Depending on the configured method (e.g., create, find, update, delete), it calls the appropriate internal execution method.

Returns:

requests.Response - The response object from the executed request.

Raises:

Exception - If the build method has not been called or if it is not the last method invoked before execute.
ValueError - If the configured method is unsupported.

Example:

builder.execute()

opengate_data.ai_models

AI Pipelines

opengate_data.ai_pipelines.ai_pipelines

AIPipelinesBuilder

AIPipelinesBuilder Objects

class AIPipelinesBuilder()

Builder pipelines

with_organization_name

def with_organization_name(organization_name: str) -> "AIPipelinesBuilder"

Specify the organization name.

Arguments:

organization_name str - The name of the organization.

Returns:

AIPipelinesBuilder - Returns self for chaining.

Example:

builder.with_organization_name('organization_name')

with_identifier

def with_identifier(identifier: str) -> "AIPipelinesBuilder"

Specify the identifier for the pipeline.

Arguments:

identifier str - The identifier for the pipeline.

Returns:

AIPipelinesBuilder - Returns self for chaining.

Example:

builder.with_identifier('identifier')

with_env

def with_env(data_env: str) -> "AIPipelinesBuilder"

Specify the environment variable.

Arguments:

data_env str - The environment variable.

Returns:

AIPipelinesBuilder - Returns self for chaining.

Example:

builder.with_env('PIPELINE_ID')

with_find_by_name

def with_find_by_name(find_name: str) -> "AIPipelinesBuilder"

Specify the name to find.

Arguments:

find_name str - The name of the pipeline.

Returns:

AIPipelinesBuilder - Returns self for chaining.

Example:

builder.with_find_by_name('pipeline_name')

with_config_file

def with_config_file(config_file: str, section: str,
                     config_key: str) -> "AIPipelinesBuilder"

Sets up the configuration file (.ini).

This method allows specifying a configuration file, a section within that file, and a key to retrieve a specific value from the section.

Arguments:

config_file str - The path to the.ini configuration file.
section str - The section name within the.ini file where the desired configuration is located.
config_key str - The key within the specified section whose value will be retrieved.

Raises:

TypeError - If the provided config_file is not a string.
TypeError - If the provided section is not a string.
TypeError - If the provided config_key is not a string.

Example:

[id]
pipeline_id = afe07216-14ec-4134-97ae-c483b11d965a
config_file_path = os.path.join(os.path.dirname(__file__), 'config_test.ini')
builder.with_config_file(config_file_path, 'id', 'pipeline_id')

Returns:

AIPipelinesBuilder - Returns itself to allow for method chaining.

with_prediction

def with_prediction(data_prediction: dict) -> "AIPipelinesBuilder"

Prediction with a model

Arguments:

data_prediction dict - Prediction

Raises:

TypeError - If the prediction is not a dict.

Returns:

AIPipelinesBuilder - Returns itself to allow for method chaining.

Example:

{
- `"input"` - {},
- `"collect"` - {
- `"deviceId"` - "123456",
- `"datastream"` - "PredictionDatastream"
}
}
builder.with_prediction(prediction)

with_name

def with_name(name: str) -> "AIPipelinesBuilder"

Name a new pipeline

Arguments:

name str - Name a new pipeline

Raises:

TypeError - If the name is not a string.

Returns:

AIPipelinesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_name(name_prediction)

add_action

def add_action(file_name: str,
               type_action: str | None = None) -> "AIPipelinesBuilder"

Add action name and type of model or transform exist.

Arguments:

file_name str - The name of the file representing the action.
type_action str | None - The type of the action, either ‘MODEL’ or ‘TRANSFORMER’. If None, it will be inferred from the file extension.

Raises:

TypeError - If file_name is not a string.
TypeError - If type_action is not a string or None.

Returns:

AIPipelinesBuilder - Returns itself to allow for method chaining.

Example:

builder.add_action('transform.py', 'TRANSFORMER')
builder.add_action('test/file_create.onnx', 'MODEL')
builder.add_action('test/file_update.onnx')

build

def build() -> "AIPipelinesBuilder"

Returns:

AIPipelinesBuilder - Returns itself to allow for method chaining, enabling further actions like execute.

Raises:

ValueError - If required configurations are missing or if incompatible methods are used together.

Notes:

This method should be used as a final step before execute to prepare the operations search configuration. It does not modify the state but ensures that the builder’s state is ready for execution.

Example:

builder.build()

build_execute

def build_execute()

Executes the data sets search immediately after building the configuration.

This method is a shortcut that combines building and executing in a single step.

Returns:

dict - A dictionary containing the execution response which includes the status code and potentially other metadata about the execution.

Raises:

ValueError - If build has already been called on this builder instance.

Example:

builder.build_execute()

create

def create() -> "AIPipelinesBuilder"

Creates a new pipeline.

This method prepares the request to create a new pipeline using the specified configuration in the object. It is necessary to define the name (with_name) and actions (add_action) before calling this method.

Returns:

AIPipelinesBuilder - Returns the same object to allow method chaining.

Example:

builder.with_organization_name(organization)
.with_name('MyPipeline').add_action('transform.py', 'TRANSFORMER')
.add_action('test/file_create.onnx', 'MODEL')
.create()

find_all

def find_all() -> "AIPipelinesBuilder"

Retrieves all available pipelines.

Returns:

AIPipelinesBuilder - Returns the same object to allow method chaining.

Example:

builder.with_organization_name('MyOrganization').find_all()

find_one

def find_one() -> "AIPipelinesBuilder"

Finds a specific pipeline by its identifier.

This method prepares the request to find a specific pipeline based on its identifier. The identifier is obtained automatically if not explicitly defined or can be obtained from a configuration file or environment variables.

Returns:

AIPipelinesBuilder - Returns the same object to allow method chaining.

Example:

builder.with_organization_name('my_organization').with_identifier('identifier').find_one()

update

def update() -> "AIPipelinesBuilder"

Updates an existing pipeline.

This method prepares the request to update an existing pipeline. It is necessary to define the organization’s name (with_organization_name) and the pipeline’s name (with_name) before calling this method.

Returns:

AIPipelinesBuilder - Returns the same object to allow method chaining.

Example:

builder.with_organization_name('MyOrganization').with_identifier("pipeline_identifier").with_name('MyPipeline').update()
config_file_path = os.path.join(os.path.dirname(__file__), 'config_test.ini')
builder.with_organization_name('MyOrganization').with_find_by_name("pipeline_name").with_config_file(config_file_path, 'id', 'model').with_name('MyPipeline').update()
builder.with_organization_name('MyOrganization').with_name('MyPipeline').update()

delete

def delete() -> "AIPipelinesBuilder"

Deletes an existing pipeline.

This method prepares the request to delete an existing pipeline. It is necessary to define the organization’s name (with_organization_name) and the pipeline’s identifier (with_identifier) before calling this method.

Returns:

AIPipelinesBuilder - Returns the same object to allow method chaining.

Example:

builder.with_organization_name('MyOrganization').with_identifier('pipeline_identifier').delete()

prediction

def prediction() -> "AIPipelinesBuilder"

Performs a prediction with a model.

This method prepares the request to perform a prediction using the model associated with the specified pipeline. It is necessary to define the organization’s name (with_organization_name), the pipeline’s identifier (with_identifier), and provide prediction data (with_prediction) before calling this method.

Returns:

AIPipelinesBuilder - Returns the same object to allow method chaining.

Example:

- `builder.with_organization_name('MyOrganization').with_identifier('pipeline_identifier').with_prediction({'input'` - {}, 'collect': {'deviceId': '123456', 'datastream': 'PredictionDatastream'}}).prediction()

save

def save() -> "AIPipelinesBuilder"

Save the model configuration.

This method sets up the AIPipelinesBuilder instance to save the configuration of a model associated with the specified organization. It configures the URL endpoint for the save operation and sets the operation type to ‘save’.

Returns:

AIPipelinesBuilder - The instance of the AIModelsBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name("MyOrganization").with_env("MODEL_ENV_VAR").save().build().execute()
config_file_path = os.path.join(os.path.dirname(__file__), 'config_test.ini')
builder.with_organization_name("MyOrganization").with_config_file(config_file_path, 'id', 'model').save().build().execute()

set_config_file_identifier

def set_config_file_identifier() -> "AIPipelinesBuilder"

Selects the operation that writes the pipeline identifier into a configuration file.

It stores the identifier given to with_identifier() under the section and key named with with_config_file(), so a later run can pick the pipeline up from the file instead of carrying its identifier in the code. The key must already exist in the file.

Returns:

AIPipelinesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_identifier("pipeline_identifier").with_config_file(
'pipeline_config.ini', 'id', 'pipeline_id'
).set_config_file_identifier().build().execute()

set_env_identifier

def set_env_identifier() -> "AIPipelinesBuilder"

Selects the operation that writes the pipeline identifier into the .env file.

It stores the identifier given to with_identifier() under the variable named with with_env(), so a later run can pick the pipeline up from the environment. The variable must already exist in the .env file.

Returns:

AIPipelinesBuilder - Returns itself to allow for method chaining.

Raises:

ValueError - If the variable is not in the .env file.

Example:

builder.with_identifier("pipeline_identifier").with_env(
"PIPELINE_ID"
).set_env_identifier().build().execute()

execute

def execute()

Execute the configured operation and return the response.

Returns:

requests.Response - The response object from the executed request.

Raises:

Exception - If the build method has not been called or if it is not the last method invoked before execute.
ValueError - If the configured method is unsupported.

Example:

builder.execute()

opengate_data.ai_pipelines

AI Transformers

opengate_data.ai_transformers.ai_transformers

AITransformersBuilder

AITransformersBuilder Objects

class AITransformersBuilder()

Class transformer builder

with_organization_name

def with_organization_name(organization_name: str) -> "AITransformersBuilder"

Specify the organization name.

Arguments:

organization_name str - The name of the organization.

Returns:

AITransformersBuilder - Returns self for chaining.

Example:

builder.with_organization_name('organization_name')

with_identifier

def with_identifier(identifier: str) -> "AITransformersBuilder"

Specify the identifier for the pipeline.

Arguments:

identifier str - The identifier for the pipeline.

Returns:

AITransformersBuilder - Returns self for chaining.

Example:

builder.with_identifier('identifier')

with_env

def with_env(data_env: str) -> "AITransformersBuilder"

Specify the environment variable.

Arguments:

data_env str - The environment variable.

Returns:

AITransformersBuilder - Returns self for chaining.

Example:

builder.with_env('TRANSFORMER_ID')

with_config_file

def with_config_file(config_file: str, section: str,
                     config_key: str) -> "AITransformersBuilder"

This method allows specifying a configuration file, a section within that file, and a key to retrieve a specific value from the section.

Arguments:

config_file str - The path to the.ini configuration file.
section str - The section name within the.ini file where the desired configuration is located.
config_key str - The key within the specified section whose value will be retrieved.

Raises:

TypeError - If the provided config_file is not a string.
TypeError - If the provided section is not a string.
TypeError - If the provided config_key is not a string.

Returns:

AITransformersBuilder

Example:

[id]
model_id = afe07216-14ec-4134-97ae-c483b11d965a

config_file_path = os.path.join(os.path.dirname(__file__), 'config_test.ini')
builder.with_config_file(config_file_path, 'id', 'model_id')

add_file

def add_file(file_path: str, filetype: str = None)

Adds a file to the transformer resource.

This method allows specifying one or more files to be included in the transformer resource being created. The content type for each file can be specified if needed.

Arguments:

file_path str - Full path to the file to add.
filetype str, optional - Content type of the file. Defaults to None, meaning the content type will be automatically inferred.

Returns:

AITransformersBuilder - Returns the current instance to allow method chaining.

Example:

ai_transformer_create = client.new_ai_transformers_builder().with_organization_name('organization')
.add_file('exittransformer.py', 'text/python')
.add_file('pkl_encoder.pkl')

with_find_by_name

def with_find_by_name(find_name: str) -> "AITransformersBuilder"

Specify the name to find.

Arguments:

find_name str - The name of the transformer.

Returns:

AITransformersBuilder - Returns self for chaining.

Example:

builder.with_find_by_name('transformer_name')

with_evaluate

def with_evaluate(data_evaluate: dict) -> "AITransformersBuilder"

Evaluate with transformer

Arguments:

data_evaluate dict - Evaluate

Raises:

TypeError - If to evaluate is not a dict.

Returns:

AITransformersBuilder - Returns itself to allow for method chaining.

Example:

evaluate_data = {
- `"data"` - {
- `"PPLast12H"` - 0,
- `"PPLast24H"` - 0,
- `"PPLast72H"` - 1,
- `"currentTemp"` - -2,
- `"changeTemp"` - -2
},
- `"date"` - "2022-06-13T13:59:34.779+02:00"
}
builder.with_evaluate(evaluate_data)

with_output_file_path

def with_output_file_path(output_file_path: str) -> "AITransformersBuilder"

Sets the output file path for the transformer.

This method allows you to specify the path where the output file will be saved. It is particularly useful for operations that involve downloading or saving files.

Arguments:

output_file_path str - The path where the output file will be saved.

Returns:

AITransformersBuilder - The instance of the AIModelsBuilder class.

Example:

builder.with_output_file_path("rute/prueba.onnx")

with_file_name

def with_file_name(file_name: str) -> "AITransformersBuilder"

Specifies the name of the file to be processed.

This method allows you to specify the name of the file that will be used in operations such as download or evaluation. It is particularly useful when working with specific files that require unique identifiers or names for processing.

Arguments:

file_name str - The name of the file to be processed.

Returns:

AITransformersBuilder - Returns self for chaining.

Example:

builder.with_file_name('pkl_encoder.pkl')

create

def create() -> "AITransformersBuilder"

Prepares the creation of the transformer resource.

Returns:

AITransformersBuilder - Returns the current instance to allow method chaining.

Example:

builder.with_organization_name('organization').add_file(
'exittransformer.py', 'text/python'
).add_file('pkl_encoder.pkl').create().build().execute()

find_all

def find_all() -> "AITransformersBuilder"

Searches for all available transformer resources.

Returns:

AITransformersBuilder - Returns the current instance to allow method chaining.

Example:

builder.with_organization_name('my_organization').find_all()

find_one

def find_one() -> "AITransformersBuilder"

Searches for a single transformer resource by its identifier.

This method prepares the request to find a specific transformer based on its identifier. The identifier is obtained automatically if not explicitly defined or can be obtained from a configuration file or environment variables.

Returns:

AITransformersBuilder - Returns the current instance to allow method chaining.

Example:

builder.with_organization_name('my_organization').with_identifier('identifier').find_one()

update

def update() -> "AITransformersBuilder"

Updates an existing transformer resource.

This method prepares the URL and HTTP method necessary to send a PUT request to the API to update an existing transformer. It is necessary to configure the relevant attributes of the AITransformersBuilder instance, including the identifier of the transformer to update, before calling this method.

Returns:

AITransformersBuilder - Returns the current instance to allow method chaining.

Example:

builder.with_organization_name('my_organization').with_identifier('identifier').update()

delete

def delete() -> "AITransformersBuilder"

Deletes an existing transformer resource.

This method prepares the URL and HTTP method necessary to send a DELETE request to the API to delete an existing transformer. It is necessary to configure the identifier attribute of the AITransformersBuilder instance before calling this method.

Returns:

AITransformersBuilder - Returns the current instance to allow method chaining.

Example:

builder.with_organization_name('my_organization').with_identifier('identifier').delete()

download

def download() -> "AITransformersBuilder"

Download the model file.

This method sets up the AIModelsBuilder instance to download the file of a specific model associated with the specified organization and identifier. It configures the URL endpoint for the download operation and sets the operation type to ‘download’.

Returns:

AITransformersBuilder - The instance of the AIModelsBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name("MyOrganization").with_identifier("model_identifier").with_output_file_path("model.onnx").download().build().execute()
builder.with_organization_name("MyOrganization").with_find_by_name("model_name.onnx").with_output_file_path("model.onnx").download().build().execute()
config_file_path = os.path.join(os.path.dirname(__file__), 'config_test.ini')
builder.with_organization_name("MyOrganization").with_config_file(config_file_path, 'id', 'model').with_output_file_path("model.onnx").download().build().execute()

evaluate

def evaluate() -> "AITransformersBuilder"

Prepares the evaluation of the transformer with provided data.

This method sets up the URL and method for evaluating the transformer using the provided data. The evaluation data should be set using the with_evaluate method before calling this method.

Returns:

AITransformersBuilder - Returns the current instance to allow method chaining.

Example:

builder.with_organization_name('my_organization').with_identifier('identifier').with_evaluate(evaluate_data).evaluate()

save

def save() -> "AITransformersBuilder"

Saves the transformer configuration.

This method prepares the URL and method for saving the transformer configuration. It checks if the identifier is set from the environment or configuration file and then either updates or creates the transformer accordingly.

Returns:

AITransformersBuilder - Returns the current instance to allow method chaining.

Example:

builder.with_organization_name('my_organization').with_env('TRANSFORMER_ID').save()

set_config_file_identifier

def set_config_file_identifier() -> "AITransformersBuilder"

Sets the transformer identifier in the configuration file.

This method sets the transformer identifier in the specified configuration file. It reads the configuration file, updates the identifier, and writes the changes back to the file.

Returns:

AITransformersBuilder - Returns the current instance to allow method chaining.

Example:

config_file_path = os.path.join(os.path.dirname(__file__), 'config_test.ini')
builder.with_config_file(config_file_path, 'id', 'transformer_id').set_config_file_identifier()

set_env_identifier

def set_env_identifier() -> "AITransformersBuilder"

Selects the operation that writes the transformer identifier into the .env file.

It stores the identifier held by the builder under the variable named with with_env(), so a later run can pick the transformer up from the environment. The variable must already exist in the .env file.

Returns:

AITransformersBuilder - Returns itself to allow for method chaining.

Raises:

ValueError - If the variable is not in the .env file.

Example:

builder.with_identifier("transformer_identifier").with_env(
"TRANSFORMER_ID"
).set_env_identifier().build().execute()

build

def build() -> "AITransformersBuilder"

Finalizes the construction of the IoT collection configuration.

Returns:

AITransformersBuilder - Returns itself to allow for method chaining, enabling further actions like execute.

Raises:

ValueError - If required configurations are missing or if incompatible methods are used together.

Example:

builder.build()

build_execute

def build_execute()

Executes the data sets search immediately after building the configuration.

This method is a shortcut that combines building and executing in a single step.

Returns:

dict - A dictionary containing the execution response which includes the status code and potentially other metadata about the execution.

Raises:

ValueError - If build has already been called on this builder instance.

Example:

builder.build_execute()

execute

def execute() -> requests.Response

Sends the selected operation to the platform.

Which request goes out depends on the operation chosen in the chain: create, find, update, delete, download, evaluate, save, or resolving the identifier from a configuration file or from the environment.

Returns:

requests.Response | dict | str: Whatever the selected operation produces — the transformer payload, the contents of a downloaded file, or a dict carrying status_code and either data or error.

Raises:

ValueError - If no operation was selected in the chain.

Example:

builder.with_organization_name("organization").find_all().build().execute()

opengate_data.ai_transformers

Collection

opengate_data.collection.iot_bulk_collection

IotBulkCollectionBuilder Objects

class IotBulkCollectionBuilder()

Collection Bulk Builder

add_device_datastream_datapoints

def add_device_datastream_datapoints(
        device_id: str,
        datastream_id: str,
        datapoints: list[tuple[
            int | float | bool | dict | list | str,
            None | datetime | int,
            None | str,
            None | str,
        ]],
        feed: str | None = None) -> "IotBulkCollectionBuilder"

Add the datastream identifier and a list of datapoints with their value and at for data collection.

add_device_datastream_datapoints(“device_id”, “datastream_identifier”, [(value, at, source, source_info)])

Multiple datastreams can be grouped under a single identifier

Arguments:

device_id str - The identifier of the device the datapoints belong to.
datastream_id str - The identifier for the datastream to which the datapoints will be added.
datapoints list[tuple[int | float | bool | dict | list, None | datetime | int, None | datetime | int]] - A list of tuples where each tuple represents a datapoint. Each tuple contains the datapoint value and an optional timestamp (‘at’):
value - Collected value
at - Number with the time in miliseconds from epoch of the measurement. If this field is None, the platform will assign the server current time to the datapoint whe data is received.
feed str | None - The feed to collect the datapoints under. Optional.

Returns:

IotBulkCollectionBuilder - Returns itself to allow for method chaining.

Example:

builder.add_datastream_datapoints("datastream_identifier_1", [(value1, datetime.now()), (value2, None, "HTTP-Basic", "OK")])
builder.add_datastream_datapoints("datastream_identifier_2", [(value3, None), (value4, 1431602523123)])

add_device_datastream_datapoints_with_from

def add_device_datastream_datapoints_with_from(
        device_id: str,
        datastream_id: str,
        datapoints: list[tuple[
            int | float | bool | dict | list | str,
            None | datetime | int,
            None | datetime | int,
            None | str,
            None | str,
        ]],
        feed: str | None = None) -> "IotBulkCollectionBuilder"

Add the datastream identifier and a list of datapoints with their value, at and from for data collection.

add_datastream_datapoints_with_from(“datastream_identifier”, [(value, at, from, Source, SourceInfo)])

Multiple datastreams can be grouped under a single identifier

Arguments:

device_id str - The identifier of the device the datapoints belong to.
datastream_id str - The identifier for the datastream to which the datapoints will be added.
datapoints list[tuple[int | float | bool | dict, None | datetime | int, None | datetime | int]] - A list of tuples where each tuple represents a datapoint. Each tuple contains the datapoint value and an optional timestamp (‘at’) (‘from):
value - Collected value
at - Number with the time in miliseconds from epoch of the measurement. If this field is None, the platform will assign the server current time to the datapoint whe data is received.
from - Number with the time in miliseconds from epoch of the start period of measurement. This indicates that value is the same within this time interval (from, at).
feed str | None - The feed to collect the datapoints under. Optional.

Returns:

IotBulkCollectionBuilder - Returns itself to allow for method chaining.

Example:

builder.add_datastream_datapoints_with_from("datastream_identifier_1", [(value, 1431602523123, None), (value, None, None, "HTTP-Basic", "OK")])
builder.add_datastream_datapoints_with_from("datastream_identifier_2", [(value, None, datetime.now()), (value, 1431602523123, datetime.now())])

from_dataframe

def from_dataframe(df: pd.DataFrame) -> "IotBulkCollectionBuilder"

Processes a DataFrame to extract device, data and datapoints, and adds them to the payload.

Arguments:

df pd.DataFrame - The DataFrame containing the device data and datapoints. The DataFrame is expected to have columns that match the expected structure for device datastreams and datapoints.

Returns:

IotBulkCollectionBuilder - Returns itself to allow for method chaining.

Example:

import pandas as pd

df = pd.DataFrame({
- `'device_id'` - ['device'], ['device2'],
- `'datastream'` - ['1'],['2'],
- `'value'` - [value, value2],
- `'at'` - [datetime.now(), 2000]
})
builder.from_dataframe(df)

from_spreadsheet

def from_spreadsheet(
        path: str, sheet_name_index: int | str) -> "IotBulkCollectionBuilder"

Loads data from a spreadsheet, processes it, and adds the resulting device data and datapoints to the payload. This method is particularly useful for bulk data operations where data is stored in spreadsheet format.

Arguments:

path str - The file path to the spreadsheet to load.
sheet_name_index int | str - The sheet name or index to load from the spreadsheet.

Returns:

IotBulkCollectionBuilder - Returns itself to allow for method chaining.

Example:

builder.from_spreadsheet("file.xslx", "sheet_name)
builder.from_spreadsheet("file.xslx", 1)

build

def build() -> "IotBulkCollectionBuilder"

Finalizes the construction of the entities search configuration.

Returns:

IotBulkCollectionBuilder - Returns itself to allow for method chaining, enabling further actions like execute.

Raises:

ValueError - If required configurations are missing or if incompatible methods are used together.

Example:

builder.build()

build_execute

def build_execute(include_payload=False)

This method is a shortcut that combines building and executing in a single step.

Arguments:

include_payload bool - Whether the response should carry the payload that was sent. Defaults to False.

Returns:

dict - A dictionary containing the execution response which includes the status code and potentially other metadata about the execution.

Raises:

ValueError - If build has already been called on this builder instance.

Example:

import pandas as pd
from datetime import datetime

data = {
- `"device_id"` - ['entity'],
- `"data_stream_id"` - ["device.temperature.value"],
- `"origin_device_identifier"` - ['entity2'],
- `"value"` - [40],
- `"version"` - ["4.0.0"],
- `"path"` - ["entityTesting3"],
- `"at"` - [datetime.now()],
- `"from"` - [datetime.now()],
}
new_iot_bulk_collection_builder().from_dataframe(df).from_spreadsheet("collect.xslx",0).add_device_datastream_datapoints_with_from("device_identifier", "device.temperature.value", [(300, datetime.now(), datetime.now())])
.add_device_datastream_datapoints("entity", "device.temperature.value", [(300, datetime.now())])
.build_execute()

to_dict

def to_dict() -> dict

This method is used to retrieve the entire payload that has been constructed by the builder. The payload includes all devices, their respective datastreams, and the datapoints that have been added to each datastream. This is particularly useful for inspecting the current state of the payload after all configurations and additions have been made, but before any execution actions (like sending data to a server) are taken.

Returns:

dict - A dictionary representing the current state of the payload within the IotBulkCollectionBuilder. This dictionary includes all devices, datastreams, and datapoints that have been configured.

Raises:

Exception - If the build method was not called before this method.

Example:

builder.to_dict()

execute

def execute(include_payload=False)

Executes the IoT collection based on the current configuration of the builder.

Arguments:

include_payload bool - Determine if the payload should be included in the response.

Returns:

dict - A dictionary containing the results of the execution, including success messages for each device ID if the data was successfully sent, or error messages detailing what went wrong.

Raises:

Exception - If build() has not been called before execute(), or if it was not the last method invoked prior to execute().

Example:

import pandas as pd
from datetime import datetime

data = {
- `"device_id"` - ['entity', entity2],
- `"data_stream_id"` - ["device.temperature.value", "device.name"],
- `"origin_device_identifier"` - ['entity2', None],
- `"value"` - [40, "Name"],
- `"version"` - ["4.0.0", "2.0.0],
- `"path"` - ["entityTesting3", entityTesting4],
- `"at"` - [datetime.now(), datetime.now()],
- `"from"` - [datetime.now(), datetime.now()],
}
builder.new_iot_bulk_collection_builder().from_dataframe(df).from_spreadsheet("collect.xslx",0).add_device_datastream_datapoints_with_from("device_identifier", "device.temperature.value", [(300, datetime.now(), datetime.now())])
.add_device_datastream_datapoints("entity", "device.temperature.value", [(300, datetime.now())])
.build().execute())

opengate_data.collection.iot_collection

IotCollectionBuilder Objects

class IotCollectionBuilder()

Iot Collection Builder

with_device_identifier

def with_device_identifier(device_identifier: str) -> "IotCollectionBuilder"

Add the device identifier to the constructor and validates the type.

Arguments:

device_identifier str - The unique identifier for the device.

Returns:

IotCollectionBuilder - Returns itself to allow for method chaining.

Example:

builder.with_device_identifier('device_identifier')

with_origin_device_identifier

def with_origin_device_identifier(
        origin_device_identifier: str) -> "IotCollectionBuilder"

Origin Device Identifier in case of be different that the device Identifier that sends information (included in the URI).

Add the origin_device_identifier to the constructor and validates the type.

Arguments:

origin_device_identifier str - The unique identifier for the device.

Returns:

IotCollectionBuilder - Returns itself to allow for method chaining.

Example:

builder.with_origin_device_identifier('origin_device_identifier')

with_version

def with_version(version: str) -> "IotCollectionBuilder"

Indicates the version of the structure

Add the version to the constructor and validates the type.

Arguments:

version str - The version string to be set.

Returns:

IotCollectionBuilder - Returns itself to allow for method chaining.

Example:

builder.with_version('1.0.0')

with_path

def with_path(path: list[str]) -> "IotCollectionBuilder"

Identifier of the gateway or gateways that has been used by the asset for sending the information.

This method adds the path gateway to the constructor and validates the type.

Arguments:

path list - The list of gateway identifiers.

Returns:

IotCollectionBuilder - Returns itself to allow for method chaining.

Example:

builder.with_path(["path"])

with_device

def with_device(device: str) -> "IotCollectionBuilder"

Device Identifier in case of be different that the device Identifier that sends information (included in the URI).

Arguments:

device str - The unique identifier for the device.

Returns:

IotCollectionBuilder - Returns itself to allow for method chaining.

Example:

builder.with_device("sub-device-001")

with_trustedboot

def with_trustedboot(trustedboot: str) -> "IotCollectionBuilder"

Indicates that a validation of the Trusted_boot type is required, it is not necessary to enter the value of the field but if you enter it, the entire message received by the platform will compare the value of TrustedBoot with the provisioned value, if they are different the message will not be collected.

Add the trustedboot to the constructor and validates the type.

Arguments:

trustedboot str - The unique identifier for the device.

Returns:

IotCollectionBuilder - Returns itself to allow for method chaining.

Example:

builder.with_trustedboot("trustedboot")

add_datastream_datapoints

def add_datastream_datapoints(
        datastream_id: str,
        datapoints: list[tuple[
            int | float | bool | dict | list | str,
            None | datetime | int,
            None | str,
            None | str,
        ]],
        feed: str | None = None) -> "IotCollectionBuilder"

Add the datastream identifier and a list of datapoints with their value and at for data collection.

add_datastream_datapoints(“datastream_identifier”, [(value, at, source, source_info)])

Multiple datastreams can be grouped under a single identifier

Arguments:

datastream_id str - The identifier for the datastream to which the datapoints will be added.
datapoints list[tuple[int | float | bool | dict | list, None | datetime | int, None | datetime | int]] - A list of tuples where each tuple represents a datapoint. Each tuple contains the datapoint value and an optional timestamp (‘at’):
value - Collected value
at - Number with the time in miliseconds from epoch of the measurement. If this field is None, the platform will assign the server current time to the datapoint whe data is received.
feed str | None - The feed to collect the datapoints under. Optional.

Returns:

IotCollectionBuilder - Returns itself to allow for method chaining.

Example:

builder.add_datastream_datapoints("datastream_identifier_1", [(value1, datetime.now()), (value2, None, "HTTP-Basic", "OK")])
builder.add_datastream_datapoints("datastream_identifier_2", [(value3, None), (value4, 1431602523123)])

add_datastream_datapoints_with_from

def add_datastream_datapoints_with_from(
        datastream_id: str,
        datapoints: list[tuple[
            int | float | bool | dict | list | str,
            None | datetime | int,
            None | datetime | int,
            None | str,
            None | str,
        ]],
        feed: str | None = None) -> "IotCollectionBuilder"

Add the datastream identifier and a list of datapoints with their value, at and from for data collection.

add_datastream_datapoints_with_from(“datastream_identifier”, [(value, at, from, Source, SourceInfo)])

Multiple datastreams can be grouped under a single identifier

Arguments:

datastream_id str - The identifier for the datastream to which the datapoints will be added.
datapoints list[tuple[int | float | bool | dict, None | datetime | int, None | datetime | int]] - A list of tuples where each tuple represents a datapoint. Each tuple contains the datapoint value and an optional timestamp (‘at’) (‘from):
value - Collected value
at - Number with the time in miliseconds from epoch of the measurement. If this field is None, the platform will assign the server current time to the datapoint whe data is received.
from - Number with the time in miliseconds from epoch of the start period of measurement. This indicates that value is the same within this time interval (from, at).
feed str | None - The feed to collect the datapoints under. Optional.

Returns:

IotCollectionBuilder - Returns itself to allow for method chaining.

Example:

builder.add_datastream_datapoints_with_from("datastream_identifier_1", [(value, 1431602523123, None), (value, None, None, "HTTP-Basic", "OK")])
builder.add_datastream_datapoints_with_from("datastream_identifier_2", [(value, None, datetime.now()), (value, 1431602523123, datetime.now())])

from_dict

def from_dict(payload: dict[str, Any]) -> "IotCollectionBuilder"

Constructs the collection configuration from a dictionary input.

This method dynamically applies builder methods based on the keys in the input dictionary. It should be used after the build() method has been called to ensure that the builder is in a proper state to accept configuration from a dictionary.

Arguments:

payload dict[str, Any] - The dictionary containing the configuration Args.

Returns:

IotCollectionBuilder - Returns itself to allow for method chaining.

Raises:

ValueError - If required keys are missing in the payload or if the ‘datastreams’ field is empty.

Example:

builder.build().from_dict({
- `'version'` - '1.0.0',
- `'path'` - ["mews"],
- `'trustedBoot'` - "trustedBoot",
- `'origin_device_identifier'` - 'device123',
- `'datastreams'` - [
- `{'id'` - 'temp', 'datapoints': [(22, 1609459200000)]}
]
})

build

def build() -> "IotCollectionBuilder"

Finalizes the construction of the IoT collection configuration.

Returns:

IotCollectionBuilder - Returns itself to allow for method chaining, enabling further actions like execute.

Raises:

ValueError - If required configurations are missing or if incompatible methods are used together.

Notes:

This method should be used as a final step before execute to prepare the IoT collection configuration. It does not modify the state but ensures that the builder’s state is ready for execution.

Example:

builder.build()

to_dict

def to_dict() -> dict

Returns:

dict - A dictionary representing the current state of the payload within the IotCollectionBuilder. This dictionary includes all devices, datastreams, and datapoints that have been configured.

Raises:

Exception - If the build() method was not called before this method.

Example:

builder.build().to_dict()

build_execute

def build_execute(include_payload: bool = False)

Executes the IoT collection immediately after building the configuration.

This method is a shortcut that combines building and executing in a single step. It should be used when you want to build and execute the configuration without modifying the builder state in between these operations.

It first validates the build configuration and then executes the collection if the validation is successful.

Arguments:

include_payload bool - Determine if the payload should be included in the response.

Returns:

dict - A dictionary containing the execution response which includes the status code and potentially other metadata about the execution.

Raises:

ValueError - If build has already been called on this builder instance, indicating that build_execute is being incorrectly used after build.
Exception - If there are issues during the execution process, including network or API errors.

Example:

new_iot_collection_builder().with_device_identifier("entity").with_version("2.0.0").add_datastream_datapoints("device.temperature.value", [(100, None), (50, datetime.now())]).build_execute(True)

execute

def execute(include_payload: bool = False)

Executes the IoT collection based on the current configuration of the builder.

Arguments:

include_payload bool - Determine if the payload should be included in the response.

Returns:

Dict - A dictionary containing the execution response which includes the status code and, optionally, the payload. If an error occurs, a string describing the error is returned.

Raises:

Exception - If build() has not been called before execute(), or if it was not the last method invoked prior to execute().

Example:

builder.with_device_identifier("device_identifier").with_version("2.0.0").add_datastream_datapoints("device.temperature.value", [(100, None), (50, datetime.now())]).build().execute(True)

opengate_data.collection.iot_pandas_collection

PandasIotCollectionBuilder Objects

class PandasIotCollectionBuilder()

Builder class to process a pandas DataFrame into IoT collections and send them to a specified endpoint.

from_dataframe

def from_dataframe(df: pd.DataFrame) -> "PandasIotCollectionBuilder"

Set the input DataFrame that contains the IoT data to process.

The DataFrame must include a ‘device_id’ and ‘at’ column. Additional columns are considered as potential datastream values. If ‘at’ is empty or None, a timestamp will be assigned.

Arguments:

df pd.DataFrame - The DataFrame with ‘device_id’ and ‘at’ columns.

Returns:

PandasIotCollectionBuilder - The current builder instance.

Raises:

Exception - If ‘device_id’ or ‘at’ column is missing in the DataFrame.

with_columns

def with_columns(columns: list[str]) -> "PandasIotCollectionBuilder"

Specify the columns from the DataFrame that should be included as datastreams in the IoT payload.

If this method is not called, all available datastream columns (except required/optional ones) are used. If it is called, only the specified columns will be considered.

Arguments:

columns list[str] - The list of column names to include as datastreams.

Returns:

PandasIotCollectionBuilder - The current builder instance.

Raises:

Exception - If any specified column does not exist in the DataFrame.

with_max_bytes_per_request

def with_max_bytes_per_request(max_bytes: int) -> "PandasIotCollectionBuilder"

Set the maximum number of bytes per request for IoT collection.

This controls how the payload is batched when sending to the endpoint.

Arguments:

max_bytes int - The maximum request size in bytes.

Returns:

PandasIotCollectionBuilder - The current builder instance.

build

def build() -> "PandasIotCollectionBuilder"

Build the request payload after the DataFrame and columns have been configured.

This method processes the DataFrame, converting columns into the appropriate IoT datastream format. It must be called before execute() if not using build_execute().

Returns:

PandasIotCollectionBuilder - The current builder instance.

Raises:

Exception - If build() and build_execute() are used together.

build_execute

def build_execute(
        include_payload: bool = False) -> dict[str, list[dict[str, Any]]]

Build the payload and execute the request in a single step.

This method is a shortcut for users who want to build and then immediately execute. It cannot be used together with build() or execute().

Arguments:

include_payload bool - Whether to include the payload in the result. Defaults to False.

Returns:

dict[str, list[dict[str, Any]]]: The results of the IoT collection request.

Raises:

ValueError - If build_execute() is used together with build() or execute().

execute

def execute(include_payload: bool = False) -> Union[str, pd.DataFrame]

Execute the request after building it with build() or build_execute().

If include_payload is True, it returns a JSON string with the payload and results. Otherwise, it returns a pandas DataFrame with a status column summarizing the results.

Arguments:

include_payload bool - Whether to include the payload in the result. Defaults to False.

Returns:

Union[str, pd.DataFrame]: The result of the IoT collection request.

Raises:

Exception - If the required method invocation order is not respected.

opengate_data.collection

Datasets

opengate_data.datasets.find_datasets

FindDatasetsBuilder Objects

class FindDatasetsBuilder()

Find Datasets Builder

with_organization_name

def with_organization_name(organization_name: str) -> "FindDatasetsBuilder"

Set organization name

Arguments:

organization_name str - The name of the organization that owns the data sets.

Returns:

FindDatasetsBuilder - Returns itself to allow for method chaining.

Example:

builder.with_organization_name("organization_name")

with_format

def with_format(format_data: str) -> "FindDatasetsBuilder"

Formats the flat entities data based on the specified format (‘dict’, or ‘pandas’). By default, the data is returned as a dictionary.

Arguments:

format_data str - The format to use for the data.

Example:

builder.with_format(‘dict’) builder.with_format(‘pandas’)

Returns:

FindDatasetsBuilder - Returns itself to allow for method chaining.

with_identifier

def with_identifier(identifier: str) -> "FindDatasetsBuilder"

set the dataset identifier.

Arguments:

identifier str - The identifier of the dataset.

Returns:

FindDatasetsBuilder - Returns itself to allow for method chaining.

Example:

builder.with_identifier("dataset_id")

with_config_file

def with_config_file(config_file: str,
                     section: str,
                     config_key: str,
                     prefer: str = "auto") -> "FindDatasetsBuilder"

Reads a value from the INI and saves it as a source. ‘prefer’ controls whether the value will be interpreted as identifier, name, or auto (first id, then name).

Arguments:

config_file str - Path to the INI file to read.
section str - The section of the INI file the value lives in.
config_key str - The key holding the value.
prefer str - How to read the value: ‘identifier’, ’name’, or ‘auto’ to try the identifier first and fall back to the name. Defaults to ‘auto’.

with_name

def with_name(find_name: str) -> "FindDatasetsBuilder"

Specify the name to find.

Arguments:

find_name str - The name of the dataset.

Returns:

FindDatasetsBuilder - Returns self for chaining.

Example:

builder.with_name('dataset_name')

with_env

def with_env(env_key: str, prefer: str = "auto") -> "FindDatasetsBuilder"

Use an environment variable as the source. ‘prefer’ can be:

‘identifier’ -> treat the value as an identifier
’name’ -> treat the value as a name
‘auto’ -> try identifier and, if not, name

Arguments:

env_key str - The name of the environment variable to read.
prefer str - How to read the value: ‘identifier’, ’name’, or ‘auto’ to try the identifier first and fall back to the name. Defaults to ‘auto’.

find_all

def find_all() -> "FindDatasetsBuilder"

Searches for all available data sets resources.

Returns:

FindDatasetsBuilder - Returns the current instance to allow method chaining.

Example:

builder.with_organization_name('my_organization').find_all()

find_one

def find_one() -> "FindDatasetsBuilder"

Searches for a single dataset resource by its identifier.

This method prepares the request to find a specific dataset based on its identifier. The identifier is obtained automatically if not explicitly defined or can be obtained from a configuration file or environment variables.

Returns:

FindDatasetsBuilder - Returns the current instance to allow method chaining.

Example:

builder.with_organization_name('my_organization').with_organization_name("organization_name").with_format("dict").with_identifier("identifier").find_one().build().execute()

build

def build() -> "FindDatasetsBuilder"

Finalizes the construction of the IoT collection configuration.

Returns:

FindDatasetsBuilder - Returns itself to allow for method chaining, enabling further actions like execute.

Raises:

ValueError - If required configurations are missing or if incompatible methods are used together.

Example:

builder.build()

build_execute

def build_execute()

Executes the data sets search immediately after building the configuration.

This method is a shortcut that combines building and executing in a single step.

Returns:

dict - A dictionary containing the execution response which includes the status code and potentially other metadata about the execution.

Raises:

ValueError - If build has already been called on this builder instance.

Example:

builder.build_execute()

execute

def execute() -> Response

Execute the configured operation and return the response.

Returns:

requests.Response - The response object from the executed request.

Raises:

Exception - If the build method has not been called or if it is not the last method invoked before execute.
ValueError - If the configured method is unsupported.

Example:

builder.execute()

opengate_data.datasets

File Connector

opengate_data.file_connector.file_connector

FileConnectorBuilder Objects

class FileConnectorBuilder()

File Connector Builder

with_organization_name

def with_organization_name(organization_name: str) -> "FileConnectorBuilder"

Set organization name

Arguments:

organization_name str - The name of the organization the files belong to.

Returns:

FileConnectorBuilder - Returns itself to allow for method chaining.

Example:

builder.with_organization_name("organization_name")

with_overwrite_files

def with_overwrite_files(overwrite_files: bool) -> "FileConnectorBuilder"

Set the overwrite file.

Arguments:

overwrite_files bool - Whether an upload replaces a file that already exists.

Returns:

FileConnectorBuilder - Returns itself to allow for method chaining.

add_local_file

def add_local_file(local_file: str) -> "FileConnectorBuilder"

Add a single local file to be uploaded.

You can call this method multiple times or combine it with add_local_multiple_files().

Arguments:

local_file str - Local file path to be uploaded.

Returns:

FileConnectorBuilder - Returns itself to allow for method chaining.

Example:

builder.add_local_file("data/file1.csv")

add_local_multiple_files

def add_local_multiple_files(local_files: list[str]) -> "FileConnectorBuilder"

Add multiple local files to be uploaded.

The provided list can include one or more filesystem paths. They will be appended to the same internal collection used by add_local_file, so you can freely combine both methods:

builder.add_local_file(“foo.zip”).add_local_multiple_files([“bar.zip”, “baz.tar”])

Arguments:

local_files list[str] - List of file paths to upload.

Returns:

FileConnectorBuilder - Returns itself to allow for method chaining.

with_format

def with_format(format_data: str) -> "FileConnectorBuilder"

Formats the flat entities data based on the specified format (‘dict’, or ‘pandas’). By default, the data is returned as a dictionary.

Arguments:

format_data str - The format to use for the data.

Example:

builder.with_format(‘dict’) builder.with_format(‘pandas’)

Returns:

FileConnectorBuilder - Returns itself to allow for method chaining.

with_destiny_path

def with_destiny_path(path: str) -> "FileConnectorBuilder"

Set destiny path

Arguments:

path str - The remote directory the operation works on. A trailing slash is added if missing.

Returns:

FileConnectorBuilder - Returns itself to allow for method chaining.

Example:

builder.with_destiny_path("path")

with_find_name

def with_find_name(find_file_name: str) -> "FileConnectorBuilder"

Set find by name

Arguments:

find_file_name str - The name of the file to look for.

Returns:

FileConnectorBuilder - Returns itself to allow for method chaining.

Example:

builder.with_find_name("file.csv")

with_output_path

def with_output_path(output_path: str) -> "FileConnectorBuilder"

Set output path so that when downloading the file it is saved in that path

Arguments:

output_path str - The local directory a download is saved into. A trailing slash is added if missing.

Returns:

FileConnectorBuilder - Returns itself to allow for method chaining.

Example:

builder.with_output_path("output_path")

add_remote_file

def add_remote_file(file: str) -> "FileConnectorBuilder"

Adds one remote file to the operation.

Call it as many times as needed, or combine it with add_remote_multiple_files().

Arguments:

file str - The name of the remote file.

Returns:

FileConnectorBuilder - Returns itself to allow for method chaining.

Example:

builder.add_remote_file("file.csv")

add_remote_multiple_files

def add_remote_multiple_files(files: list) -> "FileConnectorBuilder"

Adds several remote files to the operation at once.

The list is appended to the same collection add_remote_file() fills, so both can be combined.

Arguments:

files list - The names of the remote files.

Returns:

FileConnectorBuilder - Returns itself to allow for method chaining.

Example:

builder.add_remote_multiple_files(["file1.csv", "file2.csv"])

from_dataframe

def from_dataframe(df: "pd.DataFrame",
                   *,
                   defaults: dict | None = None) -> "FileConnectorBuilder"

Assign a DataFrame that describes operations per row. Expected columns (depending on method):

upload: local_file [req], destiny_path [opt], overwrite [opt]

If there is no destiny_path, use defaults[‘destiny_path’] or defaults[‘path’] or with_destiny_path(…) or “/”
default overwrite = False

download: path [req], filename [req], output_path [opt]

path can come from column, defaults[‘path’], with_destiny_path(…)

delete: path [req], filename [opt] (empty or absent -> delete the entire path)

Supported defaults: {“destiny_path”: str, “path”: str, “overwrite”: bool, “output_path”: str}

NOTE: if you mix from_dataframe with setters in download (path/filenames/output_path), then you must use all THREE setters; if not, use only from_dataframe.

Arguments:

df pandas.DataFrame - The DataFrame holding the files to upload.
defaults dict | None - Values to fall back on when a row leaves a column out: “destiny_path”, “path”, “overwrite” and “output_path”.

upload

def upload() -> "FileConnectorBuilder"

Configures the builder to upload a file to the specified organization.

This method sets the internal state of the builder to prepare for a file upload operation. It does not execute the operation immediately but prepares the necessary configurations for when the execute method is called.

Returns:

FileConnectorBuilder - Returns itself to allow for method chaining.

Example:

builder.upload()

list_all

def list_all() -> "FileConnectorBuilder"

Configures the builder to list files available in the specified organization.

This method sets the internal state of the builder to prepare for a file listing operation. It does not execute the operation immediately but prepares the necessary configurations for when the execute method is called.

Returns:

FileConnectorBuilder - Returns itself to allow for method chaining.

Example:

builder.list_all()

list_one

def list_one() -> "FileConnectorBuilder"

Configures the builder to list a single file from the specified organization.

This method sets the internal state of the builder to prepare for a single file listing operation. It does not execute the operation immediately but prepares the necessary configurations for when the execute method is called.

Returns:

FileConnectorBuilder - Returns itself to allow for method chaining.

Example:

builder.list_one()

download

def download() -> "FileConnectorBuilder"

Configures the builder to download a file from the specified organization.

This method sets the internal state of the builder to prepare for a file download operation. It does not execute the operation immediately but prepares the necessary configurations for when the execute method is called.

Returns:

FileConnectorBuilder - Returns itself to allow for method chaining.

Example:

builder.download()

delete

def delete() -> "FileConnectorBuilder"

Selects the operation that deletes files from the file connector.

Requires with_destiny_path(). Name the files to remove with add_remote_file() or add_remote_multiple_files(); with none named, the whole path is deleted.

Returns:

FileConnectorBuilder - Returns itself to allow for method chaining.

Example:

builder.with_organization_name("organization").with_destiny_path(
"/to/delete"
).add_remote_file("file.csv").delete().build().execute()

build

def build() -> "FileConnectorBuilder"

Closes the chain and checks it, without sending the request.

Call it last, immediately before execute(). Use build_execute() instead to do both in one step; mixing the two raises.

Returns:

FileConnectorBuilder - Returns itself to allow for method chaining.

Raises:

RuntimeError - If called more than once.
Exception - If combined with build_execute().
ValueError - If the chain is missing a method the selected operation requires, or carries one it forbids.

Example:

builder.upload().build()

build_execute

def build_execute()

Closes the chain, checks it and sends the request in one step.

Returns:

requests.Response | dict | pandas.DataFrame: The same result as execute().

Raises:

RuntimeError - If combined with build() or with execute().
ValueError - If the chain is missing a method the selected operation requires, or carries one it forbids.

Example:

builder.with_organization_name("organization").with_destiny_path(
"/path"
).add_local_file("file.csv").upload().build_execute()

execute

def execute() -> Response

Sends the selected operation to the file connector.

Which request goes out depends on the operation chosen in the chain: upload(), list_all(), list_one(), download() or delete(). The two listing operations default to the “dict” format when with_format() was not called.

Returns:

requests.Response | dict | str | pandas.DataFrame: The listing in the requested format, the contents of a download, or a dict carrying status_code and either data or error.

Raises:

RuntimeError - If build() was not the last call before execute(), or if neither build() nor build_execute() was called.
ValueError - If no operation was selected in the chain.

Example:

builder.with_organization_name("organization").with_destiny_path(
"/path"
).list_all().build().execute()

opengate_data.file_connector

OpenGate Client

opengate_data.opengate_client

Provision

opengate_data.provision.devices.provision_device

ProvisionDeviceBuilder

ProvisionDeviceBuilder Objects

class ProvisionDeviceBuilder()

Class Provision builder

with_organization_name

def with_organization_name(organization_name: str) -> "ProvisionDeviceBuilder"

Specify the organization for the device.

Arguments:

organization_name str - The organization for the device.

Returns:

ProvisionDeviceBuilder - Returns self for chaining.

Example:

builder.with_organization_name('organization_name')

with_identifier

def with_identifier(identifier: str) -> "ProvisionDeviceBuilder"

Specify the identifier for the device.

Arguments:

identifier str - The identifier for the device.

Returns:

ProvisionDeviceBuilder - Returns self for chaining.

Example:

builder.with_identifier('identifier')

with_flattened

def with_flattened() -> "ProvisionDeviceBuilder"

Flatten the data

Returns:

ProvisionDeviceBuilder - Returns itself to allow for method chaining.

Example:

builder.with_flattened()

with_utc

def with_utc() -> "ProvisionDeviceBuilder"

Set UTC flag

Returns:

ProvisionDeviceBuilder - Returns itself to allow for method chaining.

Example:

builder.with_utc()

with_provision_identifier

def with_provision_identifier(identifier: str) -> "ProvisionDeviceBuilder"

Set provision identifier

Arguments:

identifier str - The identifier to provision the device with.

Returns:

ProvisionDeviceBuilder - Returns itself to allow for method chaining.

Example:

builder.with_provision_identifier("identifier")

with_provision_channel

def with_provision_channel(channel: str) -> "ProvisionDeviceBuilder"

Set provision channel

Arguments:

channel str - The channel to provision the device into.

Returns:

ProvisionDeviceBuilder - Returns itself to allow for method chaining.

Example:

builder.with_provision_channel("channel")

with_provision_service_group

def with_provision_service_group(
        service_group: str) -> "ProvisionDeviceBuilder"

Set provision servicegroup

Arguments:

service_group str - The service group to provision the device into.

Returns:

ProvisionDeviceBuilder - Returns itself to allow for method chaining.

Example:

builder.with_provision_service_group("emptyServiceGroup")

with_provision_organization

def with_provision_organization(organization: str) -> "ProvisionDeviceBuilder"

Set provision organization

Arguments:

organization str - The organization to provision the device into.

Returns:

ProvisionDeviceBuilder - Returns itself to allow for method chaining.

Example:

builder.with_provision_service_group("organization_name")

add_provision_datastream_value

def add_provision_datastream_value(datastream: str,
                                   value: Any) -> "ProvisionDeviceBuilder"

Add a datastream value to the payload.

Arguments:

datastream str - The datastream identifier.
value Any - The value to be added. It Can be a primitive type or a complex object.

Returns:

ProvisionDeviceBuilder - Returns itself to allow for method chaining.

Example:

location_value = {
- `"position"` - {
- `"coordinates"` - [
-3.66131084,
40.458442
]
}
}
builder.add_provision_datastream_value("provision.device.location", location_value)
builder.add_provision_datastream_value("provision.device.name", "Name")

from_dict

def from_dict(dct: dict[str, Any]) -> "ProvisionDeviceBuilder"

Loads data as a python dictionary. If you want to enter the dictionary in flattened mode, you need to use with_flattened().

Arguments:

dct dict - The dictionary variable.

Returns:

ProvisionDeviceBuilder - Returns itself to allow for method chaining.

Example:

# Mode flattened
builder.with_flattened().from_dict(
{"resourceType":{"_value":{"_current":{"value":"entity.device"}}},
"provision.device.identifier":{"_value":{"_current":{"value":"identifier"}}},
"provision.administration.organization":{"_value":{"_current":{"value":"organization"}}},
"provision.administration.channel":{"_value":{"_current":{"value":"default_channel"}}},
"provision.administration.serviceGroup":{"_value":{"_current":{"value":"emptyServiceGroup"}}},
"provision.device.location":{"_value":{"_current":{"value":{"position":{"coordinates":[-3.66131084,40.458442]}}}}},

# Mode without flattened
builder.from_dict({
- `"resourceType"` - {
- `"_current"` - {
- `"value"` - "entity.device"
}
},
- `"provision"` - {
- `"administration"` - {
- `"channel"` - {
- `"_current"` - {
- `"value"` - "battery_channel"
}
},
- `"organization"` - {
- `"_current"` - {
- `"value"` - "battery_organization"
}
},
- `"serviceGroup"` - {
- `"_current"` - {
- `"value"` - "emptyServiceGroup"
}
}
},
- `"device"` - {
- `"identifier"` - {
- `"_current"` - {
- `"value"` - "worker_battery_id"
}
}
}
}
})

from_dataframe

def from_dataframe(df: pd.DataFrame) -> "ProvisionDeviceBuilder"

Loads data as a pandas DataFrame. Columns must be the names of the datastreams separated with ‘_’ or ‘.’.

Arguments:

df pd.DataFrame - The DataFrame variable.

Returns:

ProvisionDeviceBuilder - Returns itself to allow for method chaining.

Example:

import pandas as pd
data = {
- `'provision_administration_organization_current_value'` - ['base_organization','test_organization'],
- `'provision_device_location_current_value_position_type'` - ['Point','Other_Point'],
- `'provision_device_location_current_value_position_coordinates'` - [[-3.7028,40.41675],[-5.7028,47.41675]],
- `'provision_device_location_current_value_postal'` - ['28013','28050']
}
df = pd.DataFrame(df)
builder.from_dataframe(df)

find_one

def find_one() -> "ProvisionDeviceBuilder"

Retrieve a single device.

This method sets up the ProvisionDeviceBuilder instance to retrieve a specific assey associated with the specified organization and identifier.

Returns:

ProvisionDeviceBuilder - The instance of the ProvisionDeviceBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name("organization_name").with_identifier("model_identifier").find_one()

create

def create() -> "ProvisionDeviceBuilder"

Initiates the creation process of a new device.

This method prepares the ProvisionDeviceBuilder instance to create a new device.

Returns:

ProvisionDeviceBuilder - The instance of the ProvisionDeviceBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name("organization_name")
.with_provision_identifier("provision_identifier")
.with_provision_organization("provision_organization")
.with_provision_channel("provision_channel")
.with_provision_service_group("provision_service_group")
.add_provision_datastream_value("provision.device.name", "Name")
.create()

update

def update() -> "ProvisionDeviceBuilder"

Update an existing device.

This method sets up the ProvisionDeviceBuilder instance to update a specific device associated with the specified organization and identifier.

You can update a device with a flattened format sending a PUT request using the URL above. You must replace {identifier} with the identifier of the device you want to update. Also, it is sent a boolean parameter, flattened, to allow sending a flattened JSON format

Returns:

ProvisionDeviceBuilder - The instance of the ProvisionDeviceBuilder class itself, allowing for method chaining.

Example:

dict_flatenned = {“resourceType”:{"_value":{"_current":{“value”:“entity.device”}}}, “provision.device.identifier”:{"_value":{"_current":{“value”:“ManuEntityTests”}}}, “provision.administration.organization”:{"_value":{"_current":{“value”:“orgnization_name”}}}, “provision.administration.channel”:{"_value":{"_current":{“value”:“default_channel”}}}, “provision.administration.serviceGroup”:{"_value":{"_current":{“value”:“emptyServiceGroup”}}},

builder.with_organization_name("organization_name").with_identifier("model_identifier").with_flattened().from_dict(dict_flatenned).update()

delete

def delete() -> "ProvisionDeviceBuilder"

Delete an existing device.

This method sets up the ProvisionDeviceBuilder instance to delete a specific device associated with the specified organization and identifier.

Returns:

ProvisionDeviceBuilder - The instance of the ProvisionDeviceBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name('organization_name').with_identifier("identifier").delete()

build

def build() -> "ProvisionDeviceBuilder"

Finalizes the construction of the device configuration.

Returns:

ProvisionDeviceBuilder - Returns itself to allow for method chaining, enabling further actions like execute.

Raises:

ValueError - If required configurations are missing or if incompatible methods are used together.

Example:

builder.build()

build_execute

def build_execute()

Executes the data sets search immediately after building the configuration.

This method is a shortcut that combines building and executing in a single step.

Returns:

dict - A dictionary containing the execution response which includes the status code and potentially other metadata about the execution.

Raises:

ValueError - If build has already been called on this builder instance.

Example:

builder.build_execute()

execute

def execute() -> str | dict[str, str | int]

Execute the configured device and return the response.

Returns:

requests.Response - The response object from the executed request.

Raises:

Exception - If the build method has not been called or if it is not the last method invoked before execute.
ValueError - If the configured method is unsupported.

Example:

builder.execute()

opengate_data.provision.devices

opengate_data.provision.bulk.provision_bulk

ProvisionBulkBuilder Objects

class ProvisionBulkBuilder()

Provision Bulk Builder

Provisions many entities in a single request, which is the way to go when a per-entity call would mean thousands of them. The payload can come from a file — from_json(), from_csv(), from_excel() — or from memory, with from_dataframe() or from_dict().

with_bulk_action() chooses what to do with the rows — CREATE by default, UPDATE, PATCH or DELETE — and with_bulk_type() what they are, ENTITIES by default or TICKETS. Close the chain with build() and execute(), or with build_execute().

Example:

builder = client.new_provision_bulk_builder()
builder.with_organization_name("organization").from_csv(
"entities.csv"
).with_bulk_action("CREATE").build().execute()

with_organization_name

def with_organization_name(organization_name: str) -> "ProvisionBulkBuilder"

Specify the organization name.

Arguments:

organization_name str - The name of the organization name that we want to bulk data.

Returns:

ProvisionBulkBuilder - Returns itself to allow for method chaining.

Example:

builder.with_organization_name('organization_name')

with_bulk_action

def with_bulk_action(bulk_action: str) -> "ProvisionBulkBuilder"

Adds the bulk action to the constructor and validates the type.

Arguments:

bulk_action str - The bulk action. You can choose between these actions:
- CREATE (default)
- UPDATE
- PATCH
- DELETE

Returns:

ProvisionBulkBuilder - Returns itself to allow for method chaining.

Raises:

ValueError - If the bulk action isn’t one of the mentioned above.

Example:

builder.with_bulk_action('bulk_action')

with_bulk_type

def with_bulk_type(bulk_type: str) -> "ProvisionBulkBuilder"

Adds the bulk type to the constructor and validates the type.

Arguments:

bulk_type str - The bulk type. You can choose between these types:
- ENTITIES (default)
- TICKETS

Returns:

ProvisionBulkBuilder - Returns itself to allow for method chaining.

Raises:

ValueError - If the bulk type isn’t one of the mentioned above.

Example:

builder.with_bulk_type('bulk_type')

from_json

def from_json(path: str) -> "ProvisionBulkBuilder"

Loads data as a json file.

Arguments:

path str - The path to the json file.

Returns:

ProvisionBulkBuilder - Returns itself to allow for method chaining.

Raises:

FileNotFoundError - If the path isn’t correct or the file doesn’t exist in the selected folder.

Example:

builder.from_json('path_to_json.json')

from_csv

def from_csv(path: str) -> "ProvisionBulkBuilder"

Loads data as a csv file.

Arguments:

path str - The path to the csv file.

Returns:

ProvisionBulkBuilder - Returns itself to allow for method chaining.

Raises:

FileNotFoundError - If the path isn’t correct or the file doesn’t exist in the selected folder.

Example:

builder.from_csv('path_to_csv.csv')

from_excel

def from_excel(path: str) -> "ProvisionBulkBuilder"

Loads data as an Excel file (supports xls and xlsx).

Arguments:

path str - The path to the Excel file.

Returns:

ProvisionBulkBuilder - Returns itself to allow for method chaining.

Raises:

FileNotFoundError - If the path isn’t correct or the file doesn’t exist in the selected folder.

Example:

builder.from_excel('path_to_excel.xls')

from_dataframe

def from_dataframe(df: pd.DataFrame) -> "ProvisionBulkBuilder"

Loads data as a pandas DataFrame. Columns must be the names of the datastreams separated with ‘_’ or ‘.’.

Arguments:

df pd.DataFrame - The DataFrame variable.

Returns:

ProvisionBulkBuilder - Returns itself to allow for method chaining.

Example:

import pandas as pd
data = {
- `'provision_administration_organization_current_value'` - ['base_organization','test_organization'],
- `'provision_device_location_current_value_position_type'` - ['Point','Other_Point'],
- `'provision_device_location_current_value_position_coordinates'` - [[-3.7028,40.41675],[-5.7028,47.41675]],
- `'provision_device_location_current_value_postal'` - ['28013','28050']
}
df = pd.DataFrame(df)
builder.from_dataframe(df)

from_dict

def from_dict(dct: dict[str, Any]) -> "ProvisionBulkBuilder"

Loads data as a python dictionary (same structure as ‘from_json’).

Arguments:

dct dict - The dictionary variable.

Returns:

ProvisionBulkBuilder - Returns itself to allow for method chaining.

Example:

builder.from_dict({ … “entities”: [ … { … “provision”: { … “administration”: { … “organization”: {"_current": {“value”: “my_org”}} … }, … “asset”: { … “identifier”: {"_current": {“value”: “asset_123”}} … } … } … } … ] … })

build

def build() -> "ProvisionBulkBuilder"

Finalizes the construction of the provision bulk configuration.

This method prepares the builder to execute the request by ensuring all necessary configurations are set and validates the overall integrity of the build. It should be called before executing the request to ensure that the configuration is complete and valid.

The build process involves checking that mandatory fields such as the organization name are set. It also ensures that method calls that are incompatible with each other (like build and build_execute) are not both used.

Returns:

ProvisionBulkBuilder - Returns itself to allow for method chaining, enabling further actions like execute.

Raises:

ValueError - If required configurations are missing or if incompatible methods are used together.

Example:

builder.build()

build_execute

def build_execute(include_payload=False)

Executes the provision bulk immediately after building the configuration.

It first validates the build configuration and then executes the request if the validation is successful.

Arguments:

include_payload bool - Determine if the payload should be included in the response.

Returns:

dict - A dictionary containing the execution response which includes the status code and potentially other metadata about the execution.

Raises:

ValueError - If build has already been called on this builder instance, indicating that build_execute is being incorrectly used after build.
Exception - If there are issues during the execution process, including network or API errors.

Example:

response = builder.build_execute()

execute

def execute(include_payload=False)

Executes the provision bulk based on the current configuration of the builder.

Arguments:

include_payload bool - Determine if the payload should be included in the response.

Returns:

Dict - A dictionary containing the execution response which includes the status code and, optionally, the payload. If an error occurs, a string describing the error is returned.

Raises:

Exception - If build() has not been called before execute(), or if it was not the last method invoked prior to execute().

Example:

builder.build()
response = builder.execute(True)

opengate_data.provision.bulk

opengate_data.provision.processor

opengate_data.provision.processor.provision_processor

ProvisionProcessorBuilder

ProvisionProcessorBuilder Objects

class ProvisionProcessorBuilder()

Provision Processor Builder

with_organization_name

def with_organization_name(
        organization_name: str) -> "ProvisionProcessorBuilder"

Specify the organization name.

Arguments:

organization_name str - The name of the organization.

Returns:

ProvisionProcessorBuilder - Returns self for chaining.

Example:

builder.with_organization_name('organization_name')

with_identifier

def with_identifier(
        provision_processor_id: str) -> "ProvisionProcessorBuilder"

Specify the identifier for the provision processor.

Arguments:

provision_processor_id str - The identifier for the pipeline.

Returns:

ProvisionProcessorBuilder - Returns self for chaining.

Example:

builder.with_identifier('identifier')

with_name

def with_name(provision_processor_name: str) -> "ProvisionProcessorBuilder"

Specify the name for the provision processor.

Arguments:

provision_processor_name str - The name for the provision processor.

Returns:

ProvisionProcessorBuilder - Returns self for chaining.

Example:

builder.with_name('name')

with_bulk_file

def with_bulk_file(bulk_file: str) -> "ProvisionProcessorBuilder"

Specify the file for bulk processing.

Arguments:

bulk_file str - The path to the file to be uploaded for bulk processing.

Returns:

ProvisionProcessorBuilder - Returns self for chaining.

Example:

bulk_file_path = os.path.join(os.path.dirname(__file__), 'file.xlsx')
builder.with_bulk_file('bulk_file_path')

with_bulk_process_identitifer

def with_bulk_process_identitifer(
        bulk_process_id: str) -> "ProvisionProcessorBuilder"

Specify the identifier for the bulk process identifier.

Arguments:

bulk_process_id str - The identifier for the bulk process.

Returns:

ProvisionProcessorBuilder - Returns self for chaining.

Example:

builder.with_bulk_process_identitifer('identifier')

bulk

def bulk() -> "ProvisionProcessorBuilder"

Configure the builder for bulk provisioning.

This method sets the necessary headers and URL for performing a bulk provisioning operation.

Returns:

ProvisionProcessorBuilder - Returns self for chaining.

Example:

bulk_file_path = os.path.join(os.path.dirname(__file__), 'file.xlsx')
builder.with_organization_name('organization_name').with_identifier('identifier').with_bulk_file(bulk_file_path).bulk()

find_by_name

def find_by_name() -> "ProvisionProcessorBuilder"

Configure the builder to find a provision processor by name.

This method sets the necessary headers and URL for finding a provision processor by its name.

Returns:

ProvisionProcessorBuilder - Returns self for chaining.

Example:

builder.with_organization_name('organization_name').with_name('provision_processor_name').find_by_name()

bulk_status

def bulk_status() -> "ProvisionProcessorBuilder"

Configure the builder to check the status of a bulk process.

This method sets the necessary headers and URL for checking the status of a bulk process.

Returns:

ProvisionProcessorBuilder - Returns self for chaining.

Example:

builder.with_organization_name('organization_name').with_bulk_process_identitifer('bulk_process_id').bulk_status()

bulk_details

def bulk_details() -> "ProvisionProcessorBuilder"

Configure the builder to get the details of a bulk process.

This method sets the necessary headers and URL for retrieving the details of a bulk process.

Returns:

ProvisionProcessorBuilder - Returns self for chaining.

Example:

builder.with_organization_name('organization_name').with_bulk_process_identitifer('bulk_process_id').bulk_details()

build

def build() -> "ProvisionProcessorBuilder"

Finalizes the construction of the IoT collection configuration.

Returns:

ProvisionProcessorBuilder - Returns itself to allow for method chaining, enabling further actions like execute.

Raises:

ValueError - If required configurations are missing or if incompatible methods are used together.

Example:

builder.build()

build_execute

def build_execute()

Executes the data sets search immediately after building the configuration.

This method is a shortcut that combines building and executing in a single step.

Returns:

dict - A dictionary containing the execution response which includes the status code and potentially other metadata about the execution.

Raises:

ValueError - If build has already been called on this builder instance.

Example:

builder.build_execute()

execute

def execute() -> requests.Response

Execute the configured operation and return the response.

Returns:

requests.Response - The response object from the executed request.

Raises:

Exception - If the build method has not been called or if it is not the last method invoked before execute.
ValueError - If the configured method is unsupported.

Example:

builder.build_execute()

opengate_data.provision.asset.provision_asset

ProvisionAssetBuilder Objects

class ProvisionAssetBuilder()

Provision Asset Builder

Provisions assets: creates them, reads one, updates and deletes. Describe the asset with the with_provision_* setters and add_provision_datastream_value(), or hand over a whole payload with from_dict() or from_dataframe(). Then pick the operation — create(), find_one(), update(), delete() — and close the chain with build() and execute(), or with build_execute().

Example:

builder = client.new_provision_asset_builder()
builder.with_organization_name("organization").with_provision_identifier(
"asset_identifier"
).with_provision_channel("channel").create().build().execute()

with_organization_name

def with_organization_name(organization_name: str) -> "ProvisionAssetBuilder"

Specify the organization for the asset.

Arguments:

organization_name str - The organization for the asset.

Returns:

ProvisionAssetBuilder - Returns self for chaining.

Example:

builder.with_organization_name('organization_name')

with_identifier

def with_identifier(identifier: str) -> "ProvisionAssetBuilder"

Specify the identifier for the asset.

Arguments:

identifier str - The identifier for the asset.

Returns:

ProvisionAssetBuilder - Returns self for chaining.

Example:

builder.with_identifier('identifier')

with_flattened

def with_flattened() -> "ProvisionAssetBuilder"

Flatten the data

Returns:

ProvisionAssetBuilder - Returns itself to allow for method chaining.

Example:

builder.with_flattened()

with_utc

def with_utc() -> "ProvisionAssetBuilder"

Set UTC flag

Returns:

ProvisionAssetBuilder - Returns itself to allow for method chaining.

Example:

builder.with_utc()

with_provision_identifier

def with_provision_identifier(identifier: str) -> "ProvisionAssetBuilder"

Set provision identifier

Arguments:

identifier str - The identifier to provision the asset with.

Returns:

ProvisionAssetBuilder - Returns itself to allow for method chaining.

Example:

builder.with_provision_identifier("identifier")

with_provision_channel

def with_provision_channel(channel: str) -> "ProvisionAssetBuilder"

Set provision channel

Arguments:

channel str - The channel to provision the asset into.

Returns:

ProvisionAssetBuilder - Returns itself to allow for method chaining.

Example:

builder.with_provision_channel("channel")

with_provision_service_group

def with_provision_service_group(
        service_group: str) -> "ProvisionAssetBuilder"

Set provision servicegroup

Arguments:

service_group str - The service group to provision the asset into.

Returns:

ProvisionAssetBuilder - Returns itself to allow for method chaining.

Example:

builder.with_provision_service_group("emptyServiceGroup")

with_provision_organization

def with_provision_organization(organization: str) -> "ProvisionAssetBuilder"

Set provision organization

Arguments:

organization str - The organization to provision the asset into.

Returns:

ProvisionAssetBuilder - Returns itself to allow for method chaining.

Example:

builder.with_provision_service_group("organization_name")

add_provision_datastream_value

def add_provision_datastream_value(datastream: str,
                                   value: Any) -> "ProvisionAssetBuilder"

Add a datastream value to the payload.

Arguments:

datastream str - The datastream identifier.
value Any - The value to be added. It Can be a primitive type or a complex object.

Returns:

ProvisionAssetBuilder - Returns itself to allow for method chaining.

Example:

location_value = {
- `"position"` - {
- `"coordinates"` - [
-3.66131084,
40.458442
]
}
}
builder.add_provision_datastream_value("provision.asset.location", location_value)
builder.add_provision_datastream_value("provision.asset.name", "Name")

from_dict

def from_dict(dct: dict[str, Any]) -> "ProvisionAssetBuilder"

Loads data as a python dictionary. If you want to enter the dictionary in flattened mode, you need to use with_flattened().

Arguments:

dct dict - The dictionary variable.

Returns:

ProvisionAssetBuilder - Returns itself to allow for method chaining.

Example:

# Mode flattened
builder.with_flattened().from_dict(
{"resourceType":{"_value":{"_current":{"value":"entity.asset"}}},
"provision.asset.identifier":{"_value":{"_current":{"value":"identifier"}}},
"provision.administration.organization":{"_value":{"_current":{"value":"organization"}}},
"provision.asset.description":{"_value":{"_current":{"value":"Descripcion"}}},
"provision.administration.channel":{"_value":{"_current":{"value":"default_channel"}}},
"provision.administration.serviceGroup":{"_value":{"_current":{"value":"emptyServiceGroup"}}},
"provision.asset.location":{"_value":{"_current":{"value":{"position":{"coordinates":[-3.66131084,40.458442]}}}}},
"provision.human.name":{"_value":{"_current":{"value":"Name"}}},
"provision.human.surname":{"_value":{"_current":{"value":"Surname"}}}})

# Mode without flattened
builder.from_dict({
- `"resourceType"` - {
- `"_current"` - {
- `"value"` - "entity.asset"
}
},
- `"provision"` - {
- `"administration"` - {
- `"channel"` - {
- `"_current"` - {
- `"value"` - "battery_channel"
}
},
- `"organization"` - {
- `"_current"` - {
- `"value"` - "battery_organization"
}
},
- `"serviceGroup"` - {
- `"_current"` - {
- `"value"` - "emptyServiceGroup"
}
}
},
- `"asset"` - {
- `"identifier"` - {
- `"_current"` - {
- `"value"` - "worker_battery_id"
}
}
}
}
})

from_dataframe

def from_dataframe(df: pd.DataFrame) -> "ProvisionAssetBuilder"

Loads data as a pandas DataFrame. Columns must be the names of the datastreams separated with ‘_’ or ‘.’.

Arguments:

df pd.DataFrame - The DataFrame variable.

Returns:

ProvisionAssetBuilder - Returns itself to allow for method chaining.

Example:

import pandas as pd
data = {
- `'provision_administration_organization_current_value'` - ['base_organization','test_organization'],
- `'provision_device_location_current_value_position_type'` - ['Point','Other_Point'],
- `'provision_device_location_current_value_position_coordinates'` - [[-3.7028,40.41675],[-5.7028,47.41675]],
- `'provision_device_location_current_value_postal'` - ['28013','28050']
}
df = pd.DataFrame(df)
builder.from_dataframe(df)

find_one

def find_one() -> "ProvisionAssetBuilder"

Retrieve a single asset.

This method sets up the ProvisionAssetBuilder instance to retrieve a specific assey associated with the specified organization and identifier.

Returns:

ProvisionAssetBuilder - The instance of the ProvisionDeviceBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name("organization_name").with_identifier("model_identifier").find_one()

create

def create() -> "ProvisionAssetBuilder"

Initiates the creation process of a new asset.

This method prepares the ProvisionAssetBuilder instance to create a new asset.

Returns:

ProvisionAssetBuilder - The instance of the ProvisionAssetBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name("organization_name")
.with_provision_identifier("provision_identifier")
.with_provision_organization("provision_organization")
.with_provision_channel("provision_channel")
.with_provision_service_group("provision_service_group")
.add_provision_datastream_value("provision.asset.name", "Name")
.create()

update

def update() -> "ProvisionAssetBuilder"

Update an existing asset.

This method sets up the ProvisionAssetBuilder instance to update a specific asset associated with the specified organization and identifier.

You can update an asset with a flattened format sending a PUT request using the URL above. You must replace {identifier} with the identifier of the asset you want to update. Also, it is sent a boolean parameter, flattened, to allow sending a flattened JSON format

Returns:

ProvisionAssetBuilder - The instance of the ProvisionAssetBuilder class itself, allowing for method chaining.

Example:

dict_flatenned = {“resourceType”:{"_value":{"_current":{“value”:“entity.asset”}}}, “provision.asset.identifier”:{"_value":{"_current":{“value”:“EntityTest”}}}, “provision.administration.organization”:{"_value":{"_current":{“value”:“orgnization_name”}}}, “provision.administration.channel”:{"_value":{"_current":{“value”:“default_channel”}}}, “provision.administration.serviceGroup”:{"_value":{"_current":{“value”:“emptyServiceGroup” }}},

builder.with_organization_name("organization_name").with_identifier("model_identifier").with_flattened().from_dict(dict_flatenned).update()

delete

def delete() -> "ProvisionAssetBuilder"

Delete an existing asset.

This method sets up the ProvisionAssetBuilder instance to delete a specific asset associated with the specified organization and identifier.

Returns:

ProvisionAssetBuilder - The instance of the ProvisionAssetBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name('organization_name').with_identifier("identifier").delete()

modify

def modify() -> "ProvisionAssetBuilder"

Modify an existing asset.

This method sets up the ProvisionAssetBuilder instance to update a specific asset associated with the specified organization and identifier.

You can update an asset with a flattened format sending a Patch request using the URL above. You must replace {identifier} with the identifier of the asset you want to update. Also, it is sent a boolean parameter, flattened, to allow sending a flattened JSON format

Returns:

ProvisionAssetBuilder - The instance of the ProvisionAssetBuilder class itself, allowing for method chaining.

Example:

dict_flatenned = {"resourceType":{"_value":{"_current":{"value":"entity.asset"}}},
"provision.asset.identifier":{"_value":{"_current":{"value":"EntityTest"}}},
"provision.administration.organization":{"_value":{"_current":{"value":"orgnization_name"}}},
"provision.administration.channel":{"_value":{"_current":{"value":"default_channel"}}},
"provision.administration.serviceGroup":{"_value":{"_current":{"value":"emptyServiceGroup" }}},


builder.with_organization_name("organization_name").with_identifier("model_identifier").with_flattened().from_dict(dict_flatenned).modify()

build

def build() -> "ProvisionAssetBuilder"

Finalizes the construction of the asset configuration.

Returns:

ProvisionAssetBuilder - Returns itself to allow for method chaining, enabling further actions like execute.

Raises:

ValueError - If required configurations are missing or if incompatible methods are used together.

Example:

builder.build()

build_execute

def build_execute()

Executes the data sets search immediately after building the configuration.

This method is a shortcut that combines building and executing in a single step.

Returns:

dict - A dictionary containing the execution response which includes the status code and potentially other metadata about the execution.

Raises:

ValueError - If build has already been called on this builder instance.

Example:

builder.build_execute()

execute

def execute() -> str | dict[str, str | int]

Execute the configured asset and return the response.

Returns:

requests.Response - The response object from the executed request.

Raises:

Exception - If the build method has not been called or if it is not the last method invoked before execute.
ValueError - If the configured method is unsupported.

Example:

builder.execute()

opengate_data.provision.asset

opengate_data.provision

Rules

opengate_data.rules.rules

RulesBuilder

RulesBuilder Objects

class RulesBuilder()

Rules builder

with_organization_name

def with_organization_name(organization_name: str) -> "RulesBuilder"

Specify the organization name.

Arguments:

organization_name str - The name of the organization.

Returns:

RulesBuilder - Returns self for chaining.

Example:

builder.with_organization_name('organization_name')

with_identifier

def with_identifier(identifier: str) -> "RulesBuilder"

Specify the identifier for the rule.

Arguments:

identifier str - The identifier for the rules.

Returns:

RulesBuilder - Returns self for chaining.

Example:

builder.with_identifier('identifier')

with_actions

def with_actions(actions: dict[str, Any]) -> "RulesBuilder"

Specify the actions in rules.

Arguments:

actions dict - Actions

Returns:

RulesBuilder - Returns self for chaining.

Example:

rule = {
- `"actions"` - {
- `"close"` - [
{
- `"enabled"` - False,
- `"ruleToClose"` - "rule_name",
- `"alarmToClose"` - "alarmToClose"
}
]
}
}
with_actions = rule["actions"]
builder.with_actions(with_actions)

with_actions_delay

def with_actions_delay(actions_delay: int) -> "RulesBuilder"

Waiting threshold before actions are executed. Allows cancellation of the execution of actions if another rule exists with a subsequent delay cancellation action.

Arguments:

actions_delay int - Delay option in milliseconds

Returns:

RulesBuilder - Returns self for chaining.

Example:

builder.with_actions(1000)

with_active

def with_active(active: bool) -> "RulesBuilder"

Specify the active in rules.

Arguments:

active bool - Activate or deactivate action

Returns:

RulesBuilder - Returns self for chaining.

Example:

builder.with_active(False)
builder.with_active(True)

with_channel

def with_channel(channel: str) -> "RulesBuilder"

Specify the channel in rules.

Arguments:

channel str - Channel

Returns:

RulesBuilder - Returns self for chaining.

Example:

builder.with_channel('default_channel')

with_condition

def with_condition(condition: dict[str, Any]) -> "RulesBuilder"

Specify the condition for the rule. Mandatory for EASY mode and not applicable for ADVANCED mode. JSON filter which follows the same filter structure of the Opengate platform. It can contain rule parameters.

Arguments:

condition dict - Specify the identifier for the rule.

Returns:

RulesBuilder - Returns self for chaining.

Example:

filter_builder_build = FilterBuilder().and_(FilterBuilder().eq("provision.administration.organization","Organization")).build()
builder.with_condition('filter_builder_build)
builder.with_condition({device.cpu.usage._current.value:
"$datastream:device.cpu.usage._current.value"})

with_mode

def with_mode(mode: str) -> "RulesBuilder"

Specify rule type mode

Arguments:

mode str - Advanced or basic.

Returns:

RulesBuilder - Returns self for chaining.

Example:

builder.with_mode('EASY')
builder.with_mode('ADVANCED')

with_name

def with_name(name: str) -> "RulesBuilder"

Specify the name for the rule.

Arguments:

name str - The identifier for the rules.

Returns:

RulesBuilder - Returns self for chaining.

Example:

builder.with_mode('name_rule')

with_description

def with_description(description: str) -> "RulesBuilder"

Specify the description.

Arguments:

description str - The description for the rules.

Returns:

RulesBuilder - Returns self for chaining.

Example:

builder.with_organization_name('description')

with_type

def with_type(rule_type: dict[str, Any]) -> "RulesBuilder"

Specify the description.

Arguments:

rule_type dict - The description for the rules.

Returns:

RulesBuilder - Returns self for chaining.

Example:

- `"rule"` - {
- `"type"` - {
- `"datastreams"` - [
{
- `"name"` - "device.cpu.usage",
- `"fields"` - [
{
- `"field"` - "value",
- `"alias"` - "CPU usage"
}
],
- `"prefilter"` - False
}
],
- `"name"` - "DATASTREAM"
}
}
type = rule["type"]
builder.with_type(type)

with_parameters

def with_parameters(parameters: list[dict[str, str]]) -> "RulesBuilder"

Specify the parameters for rules.

Arguments:

parameters dict - The parameters for the rules.

Returns:

RulesBuilder - Returns self for chaining.

Example:

parameters = [
{
- `"name"` - "name",
- `"schema"` - "string",
- `"value"` - "2"
}
]
builder.with_parameters(parameters)

with_code

def with_code(code: str) -> "RulesBuilder"

Specify the JavaScript code for advanced rules.

Arguments:

code str - The JavaScript code to be used in the rule.

Returns:

RulesBuilder - Returns self for chaining.

Raises:

Exception - If the mode is not set to ‘ADVANCED’.

Example:

code = '''
function add(a, b) {
// This is a comment
return a + b;
}
'''
builder.with_mode('ADVANCED').with_code(code).with_code_file('code')

with_code_file

def with_code_file(code_file: str) -> "RulesBuilder"

Specify the JavaScript code for advanced rules from a file.

This method reads the JavaScript code from a specified file and converts it into a single line to be used in the rule.

Arguments:

code_file str - The path to the file containing the JavaScript code.

Returns:

RulesBuilder - Returns self for chaining.

Raises:

ValueError - If the file does not exist or is not a valid file.
ValueError - If the mode is not set to ‘ADVANCED’.

Example:

builder.with_mode('ADVANCED').with_code_file('path/to/code.js')

with_env

def with_env(data_env: str) -> "RulesBuilder"

Specify the environment variable.

Arguments:

data_env str - The environment variable.

Returns:

RulesBuilder - Returns self for chaining.

Example:

builder.with_env('RULE_ID')

with_config_file

def with_config_file(config_file: str, section: str,
                     config_key: str) -> "RulesBuilder"

Sets up the configuration file (.ini).

This method allows specifying a configuration file, a section within that file, and a key to retrieve a specific value from the section.

Arguments:

config_file str - The path to the.ini configuration file.
section str - The section name within the.ini file where the desired configuration is located.
config_key str - The key within the specified section whose value will be retrieved.

Returns:

RulesBuilder - Returns itself to allow for method chaining.

Example:

[id]
rule_id = afe07216-14ec-4134-97ae-c483b11d965a
builder.with_config_file('model_config.ini', 'id', 'rule_id')

with_find_by_name

def with_find_by_name(find_name: str) -> "RulesBuilder"

Specify the name to find.

Arguments:

find_name str - The name of the pipeline.

Returns:

RulesBuilder - Returns self for chaining.

Example:

builder.with_find_by_name('name_rule')

find_all

def find_all() -> "RulesBuilder"

Retrieve all models.

This method sets up the RulesBuilder instance to retrieve all rules associated with the specified organization.

Returns:

RulesBuilder - The instance of the RulesBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name("organization_name").find_all()

find_one

def find_one() -> "RulesBuilder"

Retrieve all models.

This method sets up the RulesBuilder instance to retrieve all rules associated with the specified organization.

Returns:

RulesBuilder - The instance of the RulesBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name('organization').with_channel(
'default_channel'
).with_identifier('4ae733b0-2dc6-4ad4-9d2c-9ab426c9f32d').find_one().build().execute()

create

def create() -> "RulesBuilder"

Initiates the creation process of a new model.

This method prepares the RulesBuilder instance to create a new model by setting up the necessary parameters such as the organization name and the file to be associated with the model. It also specifies the URL endpoint for creating the model and sets the operation type to ‘create’.

Returns:

RulesBuilder - The instance of the RulesBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name("organization").with_channel(
"default_channel"
).with_name("rule_name").with_mode("EASY").create().build().execute()

update

def update() -> "RulesBuilder"

Update an existing rule.

This method sets up the RulesBuilder instance to update a specific rule associated with the specified organization and identifier.

Returns:

RulesBuilder - The instance of the RulesBuilder class itself, allowing for method chaining.

Example:

rule = {
- `"identifier"` - "9482a13d-ade5-46ec-b6c9-1cfc23f1f2c6",
- `"name"` - "avanzado22",
- `"active"` - False,
- `"mode"` - "ADVANCED",
- `"type"` - {
- `"datastreams"` - [
{
- `"name"` - "device.cpu.usage",
- `"fields"` - [
{
- `"field"` - "value",
- `"alias"` - "CPU usage"
}
],
- `"prefilter"` - False
}
],
- `"name"` - "DATASTREAM"
},
- `"actionsDelay"` - 1000
}

with_type = rule["type"]
with_type(with_type).
with_actions_delay(rule["actionsDelay"]).
with_code_file('reglas_update.js').
update()

delete

def delete() -> "RulesBuilder"

Delete an existing model within the organization.

This method sets up the RulesBuilder instance to delete a specific model associated with the specified organization and identifier. It configures the URL endpoint for the delete operation and sets the operation type to ‘delete’.

Returns:

RulesBuilder - The instance of the RulesBuilder class itself, allowing for method chaining.

Example:

builder.with_organization_name('organization_name').with_channel(
'default_channel'
).with_identifier("45ddc1a9-4de2-4d5f-a9fe-7972aa4555a4").delete().build().execute()

update_parameters

def update_parameters() -> "RulesBuilder"

Updates the parameters of an existing rule.

This function prepares the RulesBuilder instance to update the parameters of a specific rule associated with the specified organization and channel.

Returns:

RulesBuilder - The RulesBuilder instance itself, allowing method chaining.

Example:

builder.with_organization_name("organization_name").with_channel("default_channel").
with_name("rule_name").with_active(True).with_mode("ADVANCED").
- `with_parameters({"parameter1"` - "value1", "parameter2": "value2"}).update_parameters()

catalog

def catalog() -> "RulesBuilder"

Retrieves the rules catalog.

This function prepares the RulesBuilder instance to retrieve the catalog of rules

Returns:

RulesBuilder - The RulesBuilder instance itself, allowing method chaining.

Example:

builder.catalog()

save

def save() -> "RulesBuilder"

Selects the create-or-update operation.

It reads the rule identifier from the .env variable set with with_env(), or from the file set with with_config_file(), and then decides on its own: if a rule with that identifier already exists it is updated, and if it does not, it is created and the resulting identifier written back to the same place. Use it when a script has to be safe to run more than once.

Returns:

RulesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_organization_name("organization").with_config_file(
"rules_config.ini", "id", "rule_id"
).save().build().execute()

set_config_file_identifier

def set_config_file_identifier() -> "RulesBuilder"

Selects the operation that writes the rule identifier into a configuration file.

It stores the identifier given to with_identifier() under the section and key named with with_config_file(), so a later run can pick the rule up from the file instead of carrying its identifier in the code. The key must already exist in the file.

Returns:

RulesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_identifier("rule_identifier").with_config_file(
'rules_config.ini', 'id', 'rule_id'
).set_config_file_identifier().build().execute()

set_env_identifier

def set_env_identifier() -> "RulesBuilder"

Selects the operation that writes the rule identifier into the .env file.

It stores the identifier given to with_identifier() under the variable named with with_env(), so a later run can pick the rule up from the environment. The variable must already exist in the .env file.

Returns:

RulesBuilder - Returns itself to allow for method chaining.

Raises:

ValueError - If there is no identifier to write, or if the variable is not in the .env file.

Example:

builder.with_identifier("rule_identifier").with_env(
"RULE_ID"
).set_env_identifier().build().execute()

build

def build() -> "RulesBuilder"

Finalizes the construction of the IoT collection configuration.

Returns:

RulesBuilder - Returns itself to allow for method chaining, enabling further actions like execute.

Raises:

ValueError - If required configurations are missing or if incompatible methods are used together.

Example:

builder.build()

build_execute

def build_execute()

Executes the data sets search immediately after building the configuration.

This method is a shortcut that combines building and executing in a single step.

Returns:

dict - A dictionary containing the execution response which includes the status code and potentially other metadata about the execution.

Raises:

ValueError - If build has already been called on this builder instance.

Example:

builder.build_execute()

execute

def execute()

Execute the configured operation and return the response.

Returns:

requests.Response - The response object from the executed request.

Raises:

Exception - If the build method has not been called or if it is not the last method invoked before execute.
ValueError - If the configured method is unsupported.

Example:

builder.execute()

opengate_data.rules

Searching

opengate_data.searching.filter

FilterBuilder Objects

class FilterBuilder(Expressions)

Filter Builder

and_

def and_(*conditions)

Combines conditions using the logical AND operator.

Arguments:

*conditions - The conditions to combine.

Returns:

FilterBuilder - Returns itself to allow for method chaining.

Example:

builder.and_(eq(“device.operationalStatus”, “NORMAL”), like(“device.name”, “device_.*”) )

or_

def or_(*conditions)

Combines conditions using the logical OR operator.

Arguments:

*conditions - The conditions to combine.

Returns:

FilterBuilder - Returns itself to allow for method chaining.

Example:

builder.or_(eq(“device.operationalStatus”, “NORMAL”), like(“device.name”, “device_.*”) )

build

def build()

Builds the final filter.

Returns:

dict - The final filter.

Raises:

ValueError - If there is an incomplete condition.

Example:

builder.build()

opengate_data.searching.search_base

SearchBuilderBase Objects

class SearchBuilderBase()

Search Base Builder

build

def build()

Finalizes the construction of the search configuration.

build_execute

def build_execute()

Short-cut for build().execute()

with_format

def with_format(format_data: str) -> "SearchBuilderBase"

Formats the flat entities data based on the specified format (‘csv’, ‘dict’, or ‘pandas’).

Arguments:

format_data str - The format to use for the data.

Example:

builder.with_format(‘dict’) builder.with_format(‘csv’) builder.with_format(‘pandas’)

Returns:

SearchBuilderBase - Returns itself to allow for method chaining.

with_flattened

def with_flattened() -> "SearchBuilderBase"

Flatten the data

Returns:

SearchBuilderBase - Returns itself to allow for method chaining.

with_utc

def with_utc() -> "SearchBuilderBase"

Set UTC flag

Returns:

SearchBuilderBase - Returns itself to allow for method chaining.

with_summary

def with_summary() -> "SearchBuilderBase"

Set summary flag

Returns:

SearchBuilderBase - Returns itself to allow for method chaining.

with_default_sorted

def with_default_sorted() -> "SearchBuilderBase"

Set default sorted flag

Returns:

SearchBuilderBase - Returns itself to allow for method chaining.

with_case_sensitive

def with_case_sensitive() -> "SearchBuilderBase"

Set case-sensitive flag

Returns:

SearchBuilderBase - Returns itself to allow for method chaining.

opengate_data.searching.select

SelectBuilder Objects

class SelectBuilder()

A flexible builder for constructing SELECT clauses for several OpenGate entities.

This builder supports three independent modes, which cannot be mixed inside the same instance:

Simple mode (Datasets, Timeseries search):

.add("field_name")
Produces: [“field1”, “field2”, …]

Extended mode (Structured search):

.add("path.to.resource", ["field", ("other", "alias")])
Produces: [ { “name”: “…”, “fields”: [{ “field”: “…”, “alias”: “…” }] } ]

Column mode (Timeseries EXPORT):

.add_column("FIRST")
.add_column("bucket_id", output={"parquet": {"type": "INT"}})
Produces: [ { “column”: “FIRST” }, { “column”: “bucket_id”, “output”: {…} } ]

You cannot mix modes. Each builder instance must use only one mode.

Examples:

Simple mode: SelectBuilder().add(“Gross”).add(“Temp”)

Extended mode: SelectBuilder().add(“provision.device.identifier”, [(“value”, “id”), “date”])

Column mode (Timeseries Export): SelectBuilder().add_column(“FIRST”).add_column(“LAST”)

Use .build() to retrieve the final SELECT list.

add

def add(name: str, fields=None)

Add a SELECT entry in either simple or extended mode.

Arguments:

name str - Field name (simple mode) or entity name (extended mode).
fields list, optional - Only for extended mode; list of strings or tuples (field, alias).

Returns:

SelectBuilder - fluent API.

add_column

def add_column(column_name: str, output: dict | None = None)

Add a Timeseries Export column entry.

Produces backend-compatible objects like: { “column”: “FIRST” } { “column”: “bucket_id”, “output”: {…} }

Arguments:

column_name str - Name of the export column.
output dict, optional - Optional output descriptor such as: { “parquet”: { “type”: “INT” } } { “name”: “serial_number”, “parquet”: { “type”: “STRING” } }

Returns:

SelectBuilder - fluent API.

build

def build()

Return the constructed SELECT list.

Raises:

ValueError - If no select elements were added.

Returns:

list - Dicts (column mode), strings (simple mode) or dicts (extended mode).

opengate_data.searching.builder.rules_search

RulesSearchBuilder

RulesSearchBuilder Objects

class RulesSearchBuilder(SearchBuilderBase, SearchBuilder)

Rules Search Builder

with_format

def with_format(format_data: str) -> "RulesSearchBuilder"

Formats the flat entities data based on the specified format (‘dict’, or ‘pandas’).

Arguments:

format_data str - The format to use for the data.

Returns:

RulesSearchBuilder - Returns itself to allow for method chaining.

Example:

builder.with_format("dict")
builder.with_format("pandas")

execute

def execute()

Executes the rule search based on the built configuration.

Returns:

dict - The response data.

Raises:

Exception - If the build() method was not called before execute().

Example:

new_rules_search_builder.with_filter(filter).with_format("dict").build_execute()
new_rules_search_builder.with_filter(filter).with_format("pandas").build_execute()

opengate_data.searching.builder.alarm_search

AlarmSearchBuilder

AlarmSearchBuilder Objects

class AlarmSearchBuilder(SearchBuilderBase, SearchBuilder)

Alarm Search Builder

Searches the alarms raised by the platform’s rules, over /v80/search/entities/alarms. Compose the query with the inherited with_filter, with_select, with_limit and with_format methods, then close it with build() and execute(), or with build_execute().

Example:

builder = client.new_alarm_search_builder()
filter_open = client.new_filter_builder().eq("alarm.status", "OPEN").build()
builder.with_filter(filter_open).with_format("pandas").build_execute()

validate_builds

def validate_builds()

Checks the combination of methods called before the search is sent.

Returns:

AlarmSearchBuilder - Returns itself to allow for method chaining.

Raises:

ValueError - If with_format received something other than “dict”, “csv” or “pandas”.
Exception - If “csv” is combined with with_limit, or used without with_select — the CSV output needs to know its columns.

execute

def execute()

Executes the alarm search based on the built configuration.

with_summary() switches the request to /search/entities/alarms/summary and returns the aggregated counters instead of the alarms themselves.

Returns:

str | pandas.DataFrame: A JSON string for the “dict” format, raw text for “csv”, or a DataFrame of flattened records for “pandas”.

Raises:

Exception - If build() was not the last call before execute(), or if neither build() nor build_execute() was called.

Example:

builder.with_filter(filter_open).with_format("dict").build().execute()

opengate_data.searching.builder.operations_search

OperationsBuilder

OperationsSearchBuilder Objects

class OperationsSearchBuilder(SearchBuilderBase, SearchBuilder)

Builder Operations Search

execute

def execute()

Executes the operation search based on the built configuration.

Returns:

dict, csv or dataframe: The response data in the specified format.

Raises:

Exception - If the build() method was not called before execute().

Example:

new_operations_search_builder.with_format("csv").build().execute()
new_operations_search_builder.with_filter(filter).with_format("pandas").build().execute()
new_operations_search_builder.with_filter(filter).with_format("dict").build().execute()

opengate_data.searching.builder.datasets_search

DatasetsSearchBuilder

DatasetsSearchBuilder Objects

class DatasetsSearchBuilder(SearchBuilderBase, SearchBuilder)

Dataset Search Builder

with_organization_name

def with_organization_name(organization_name: str) -> "DatasetsSearchBuilder"

Set organization name

Arguments:

organization_name str - The name of the organization that owns the data set.

Returns:

DatasetsSearchBuilder - Returns itself to allow for method chaining.

Example:

builder.with_organization_name("organization_name")

with_identifier

def with_identifier(identifier: str) -> "DatasetsSearchBuilder"

Set identifier

Arguments:

identifier str - The identifier of the data set to query.

Returns:

DatasetsSearchBuilder - Returns itself to allow for method chaining.

Example:

builder.with_identifier("identifier")

with_utc

def with_utc() -> "DatasetsSearchBuilder"

Set UTC

Returns:

DatasetsSearchBuilder - Returns itself to allow for method chaining.

Example:

builder.with_utc()

with_format

def with_format(format_data: str) -> "DatasetsSearchBuilder"

Formats the flat entities data based on the specified format (‘csv’, ‘dict’, or ‘pandas’).

Arguments:

format_data str - The format to use for the data.

Returns:

DatasetsSearchBuilder - Returns itself to allow for method chaining.

Example:

builder.with_format("dict")
builder.with_format("pandas")
builder.with_format("csv")

with_sort

def with_sort(sort: str) -> "DatasetsSearchBuilder"

Set the sort identifier.

The value must be the identifier of one of the sorts declared in the dataset definition “sorts” section (the auto-generated reverse sorts are also valid). When omitted, results are sorted by the identifier column ascending.

The sort is sent in the payload for every format. NOTE: the platform currently ignores the sort for ‘csv’ and ‘pandas’ exports (a server/database limitation, not an SDK decision); it is still sent so the SDK stays forward-compatible if the backend starts honoring it.

Arguments:

sort str - The sort identifier declared in the dataset definition.

Returns:

DatasetsSearchBuilder - Returns itself to allow for method chaining.

Example:

builder.with_sort("sortByProvIdentifierDesc")

add_sort_by

def add_sort_by(field_name: str, order: str) -> "DatasetsSearchBuilder"

Deprecated for datasets. The dataset search API no longer accepts the object-based sort format; sorts are now declared in the dataset definition and referenced by identifier.

Raises:

NotImplementedError - Always. Use with_sort() instead.

execute

def execute()

Executes the data set search based on the built configuration.

Returns:

dict, csv or dataframe: The response data in the specified format.

Raises:

Exception - If the build() method was not called before execute().

Example:

new_data_sets_search_builder.with_format("csv").with_organization_name(organization).build().execute()
new_data_sets_search_builder.with_filter(filter).with_organization_name(organization).with_format("pandas").build().execute()
new_data_sets_search_builder.with_filter(filter).with_organization_name(organization).with_format("dict").build().execute()

opengate_data.searching.builder.datapoints_search

DataPointsSearchBuilder Objects

class DataPointsSearchBuilder(SearchBuilderBase, SearchBuilder)

Datapoints Search Builder

with_transpose

def with_transpose() -> "DataPointsSearchBuilder"

Enables transposing the data in the result.

This function allows the data returned by the search to be transposed, meaning that rows and columns are swapped. This can be useful for certain data analyses where it is preferred to have datastreams as columns and entities as rows.

Notes:

This function can only be used with the ‘pandas’ format.

Returns:

DataPointsSearchBuilder - Returns the builder instance to allow for method chaining.

Example:

builder.with_transpose()

with_mapped_transpose

def with_mapped_transpose(
        mapping: dict[str, dict[str, str]]) -> "DataPointsSearchBuilder"

Enables transposing the data with a specific mapping.

This function allows the data returned by the search to be transposed and mapped according to a provided mapping dictionary. The mapping specifies how complex data should be transformed into flat columns.

Arguments:

mapping dict[str, dict[str, str]] - The mapping of complex data to flat columns. The main key is the column name, and its value another dictionary defining the mapping of the substructures.

Notes:

This function can only be used with the ‘pandas’ format.

Returns:

DataPointsSearchBuilder - Returns the builder instance to allow for method chaining.

Example:

complexData = {
- `'device.communicationModules[].subscription.address'` - {
- `'type'` - 'type',
- `'IP'` - 'value'
}
}
builder.with_mapped_transpose(complexData)

execute

def execute()

Execute the configured operation and return the response.

Returns:

requests.Response - The response object from the executed request.

Raises:

Exception: If the build method has not been called or if it is not the last method invoked before execute.

ValueError - If the configured method is unsupported.

Example:

builder.execute()

opengate_data.searching.builder.timeseries_search

TimeseriesSearchBuilder Objects

class TimeseriesSearchBuilder(SearchBuilderBase, SearchBuilder)

Timeseries Search Builder

with_organization_name

def with_organization_name(
        organization_name: str) -> "TimeseriesSearchBuilder"

Set organization name

Arguments:

organization_name str - The name of the organization that owns the timeseries.

with_identifier

def with_identifier(identifier: str) -> "TimeseriesSearchBuilder"

Set identifier

Arguments:

identifier str - The identifier of the timeseries to query.

with_utc

def with_utc() -> "TimeseriesSearchBuilder"

Set UTC flag for date-time parsing

with_format

def with_format(format_data: str) -> "TimeseriesSearchBuilder"

Formats the timeseries data based on the specified format (‘csv’, ‘dict’, or ‘pandas’).

Arguments:

format_data str - The format to return the data in: ‘dict’, ‘csv’ or ‘pandas’.

with_sort

def with_sort(sort: str) -> "TimeseriesSearchBuilder"

Set sort identifier

Arguments:

sort str - The identifier of a sort declared in the timeseries definition.

execute

def execute()

Executes the timeseries search based on the built configuration.

opengate_data.searching.builder

opengate_data.searching.builder.entities_search

EntitiesSearchBuilder

EntitiesSearchBuilder Objects

class EntitiesSearchBuilder(SearchBuilderBase, SearchBuilder)

Entities Search Builder

execute

def execute()

Executes the entities search based on the built configuration.

Returns:

dict, csv or dataframe: The response data in the specified format.

Raises:

Exception - If the build() method was not called before execute().

Example:

new_entities_search_builder.with_format("csv").with_select(select).build().execute()
new_entities_search_builder.with_filter(filter).with_format("pandas").build().execute()
new_entities_search_builder.with_filter(filter).with_format("dict").build().execute()

opengate_data.searching.search

SearchBuilder

SearchBuilder Objects

class SearchBuilder()

Search Builder

with_filter

def with_filter(filter_data: dict) -> "SearchBuilder"

Adds a filter to the search.

Arguments:

filter_data Union[dict, FilterBuilder] - The filter data to apply. Can be a dictionary or a FilterBuilder instance.

Returns:

SearchBuilder - Returns itself to allow for method chaining.

Example:

search_builder.with_filter(filter_builder.build()) search_builder.with_filter({

"and" - [
{"eq" - {“device.operationalStatus”: “NORMAL”}},
{"like" - {“device.communicationModules[].mobile.imei”: “351873000102290”}} ] })

with_select

def with_select(select_data: list[dict]) -> "SearchBuilder"

Adds selection criteria to the search.

Arguments:

select_data list[dict] | SelectBuilder - The selection criteria to apply. Can be a list of dictionaries or a SelectBuilder instance.

Returns:

SearchBuilder - Returns itself to allow for method chaining.

with_limit

def with_limit(size: int, start: int = None) -> "SearchBuilder"

Adds pagination parameters to the search.

Arguments:

size int - The number of entities to retrieve per page. Limit size value 1000
start int, optional - Page number you request. By default, is 1.

Returns:

SearchBuilder - Returns itself to allow for method chaining.

Example:

search_builder.with_limit(1000, 2)

add_by_group

def add_by_group(field_name: str) -> "SearchBuilder"

Adds a field to the group.

Arguments:

field_name str - The name of the field to group by.

Returns:

SearchBuilder - Returns itself to allow for method chaining.

Example:

builder.add_by_group(“provision.device.model”) builder.add_by_group(“provision.device.software”)

add_sort_by

def add_sort_by(field_name: str, order: str) -> "SearchBuilder"

Adds a field to the sort.

Arguments:

field_name str - The name of the field to sort by.
order str - The order of sorting, either ‘ASCENDING’ or ‘DESCENDING’.

Returns:

SearchBuilder - Returns itself to allow for method chaining.

Example:

builder.add_sort_by(“datapoints._current.at”, “DESCENDING”) builder.add_sort_by(“devices._current.at”, “ASCENDING”)

opengate_data.searching

Timeseries

opengate_data.timeseries.timeseries

Provision Timeseries Builder

TimeseriesBuilder Objects

class TimeseriesBuilder(SearchBuilder)

Timeseries Builder

Exports the data of a timeseries to a file — Parquet unless you ask for another content type — and reports the state of an export already running. Both operations work over the same endpoint, /v80/timeseries/provision/organizations/{organization}/{identifier}/export: export() starts one with a POST, export_status() asks about it with a GET.

Pick the operation, then close the chain with build() and execute(), or with build_execute(). Only one export per timeseries can run at a time.

To read rows instead of exporting them, use client.new_timeseries_search_builder().

Example:

builder = client.new_timeseries_builder()
builder.with_organization_name("organization").with_identifier(
"timeseries_identifier"
).with_output_file("export.parquet").export().build().execute()

with_organization_name

def with_organization_name(organization_name: str) -> "TimeseriesBuilder"

Sets the organization that owns the timeseries. Required.

Arguments:

organization_name str - The name of the organization.

Returns:

TimeseriesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_organization_name("organization")

with_identifier

def with_identifier(identifier: str) -> "TimeseriesBuilder"

Sets the identifier of the timeseries to export. Required.

Arguments:

identifier str - The identifier of the timeseries.

Returns:

TimeseriesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_identifier("timeseries_identifier")

with_callback

def with_callback(callback_url: str) -> "TimeseriesBuilder"

Sets a URL to be notified when the export finishes, sent as the callback header. Optional: without it, poll with export_status().

Arguments:

callback_url str - The URL to notify.

Returns:

TimeseriesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_callback("https://your-application/export-done")

with_output_file

def with_output_file(filename: str,
                     content_type: str | None = None) -> "TimeseriesBuilder"

Names the file the export writes to, and optionally its content type.

Arguments:

filename str - The name of the output file.
content_type str | None - The content type to produce. Defaults to application/vnd.apache.parquet.

Returns:

TimeseriesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_output_file("export.parquet")
builder.with_output_file("export.csv", "text/csv")

with_sort

def with_sort(sort: str) -> "TimeseriesBuilder"

Not supported for the Parquet export. The export endpoint decides the output order internally and cannot be changed, and any ‘sort’ field in the payload makes the platform reject the request as “Json is malformed”.

To read timeseries data in a given order, use the search builder instead: client.new_timeseries_search_builder().with_sort(""), where the identifier is one of the sorts declared in the timeseries definition (or its automatically exposed reverse). Note that sorting is also disabled server-side for CSV output.

Raises:

NotImplementedError - Always.

export

def export() -> "TimeseriesBuilder"

Selects the operation that starts an export of the timeseries data.

Returns:

TimeseriesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_organization_name("organization").with_identifier(
"timeseries_identifier"
).export().build().execute()

export_status

def export_status() -> "TimeseriesBuilder"

Selects the operation that reports the state of the current export.

Unlike export(), it accepts no request body, so with_filter, with_select, with_limit and with_output_file are rejected here.

Returns:

TimeseriesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_organization_name("organization").with_identifier(
"timeseries_identifier"
).export_status().build().execute()

build

def build() -> "TimeseriesBuilder"

Closes the chain and checks it, without sending the request.

Call it last, immediately before execute(). Use build_execute() instead to do both in one step; mixing the two raises.

Returns:

TimeseriesBuilder - Returns itself to allow for method chaining.

Raises:

Exception - If the chain is incomplete — no operation selected, or a required or forbidden method for that operation.

Example:

builder.export().build()

build_execute

def build_execute()

Closes the chain, checks it and sends the request in one step.

Returns:

dict[str, Any]: The same response as execute().

Raises:

ValueError - If combined with build() or with execute().

Example:

builder.with_organization_name("organization").with_identifier(
"timeseries_identifier"
).export().build_execute()

execute

def execute() -> Any

Sends the selected operation to the platform.

Returns:

dict[str, Any]: Always carries status_code, plus data on success or error with the response body on failure. For export(), 202 means the export was accepted and runs in the background, 204 that the timeseries holds no data, and 409 that another process is already exporting it. For export_status(), 200 carries the parsed state of the export; a 406 is retried for up to 20 seconds before being returned.

Raises:

Exception - If build() or build_execute() was not called first.
ValueError - If no operation was selected.

Example:

builder.with_organization_name("organization").with_identifier(
"timeseries_identifier"
).export().build().execute()

opengate_data.timeseries.find_timeseries

FindTimeseriesBuilder Objects

class FindTimeseriesBuilder(SearchBuilder)

Find time series Builder

with_expand

def with_expand(expand: str) -> "FindTimeseriesBuilder"

With expand, select the data field to show information, columns, context or columns.context.

Arguments:

expand str - The extra information to include: “columns”, “context” or “columns.context” for both.

Returns:

FindTimeseriesBuilder - Returns itself to allow for method chaining.

Raises:

TypeError - If the value is not a string.
ValueError - If the value is not one of the three accepted.

Example:

builder.with_expand("columns.context")

with_datastreams

def with_datastreams(datastreams: str) -> "FindTimeseriesBuilder"

With dataStreams, select the dataStreams to filter the Timeseries. To be accept and intepreted by the System the dataStream will be in format URL.

Arguments:

datastreams str - The datastreams to filter the timeseries by, as a comma-separated list in URL format.

Returns:

FindTimeseriesBuilder - Returns itself to allow for method chaining.

Raises:

TypeError - If the value is not a string.

Example:

builder.with_datastreams("provision.device.identifier")

with_organization_name

def with_organization_name(organization_name: str) -> "FindTimeseriesBuilder"

Set organization name

Arguments:

organization_name str - The name of the organization that owns the timeseries.

Returns:

FindTimeseriesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_organization_name("organization_name")

with_format

def with_format(format_data: str) -> "FindTimeseriesBuilder"

Formats the flat entities data based on the specified format (‘csv’, ‘dict’, or ‘pandas’). By default, the data is returned as a dictionary.

Arguments:

format_data str - The format to use for the data.

Example:

builder.with_format(‘dict’) builder.with_format(‘pandas’)

Returns:

FindTimeseriesBuilder - Returns itself to allow for method chaining.

with_sort

def with_sort(sort: str) -> "FindTimeseriesBuilder"

Set sort identifier

Arguments:

sort str - The identifier of a sort declared in the timeseries definition.

with_identifier

def with_identifier(identifier: str) -> "FindTimeseriesBuilder"

set the timeseries identifier.

Arguments:

identifier str - The identifier of the timeseries.

Returns:

FindTimeseriesBuilder - Returns itself to allow for method chaining.

Example:

builder.with_identifier("timeseries_id")

with_config_file

def with_config_file(config_file: str,
                     section: str,
                     config_key: str,
                     prefer: str = "auto") -> "FindTimeseriesBuilder"

Reads a value from the INI and saves it as a source. ‘prefer’ controls whether the value will be interpreted as identifier, name, or auto (first id, then name).

Arguments:

config_file str - Path to the INI file to read.
section str - The section of the INI file the value lives in.
config_key str - The key holding the value.
prefer str - How to read the value: ‘identifier’, ’name’, or ‘auto’ to try the identifier first and fall back to the name. Defaults to ‘auto’.

with_name

def with_name(find_name: str) -> "FindTimeseriesBuilder"

Specify the name to find.

Arguments:

find_name str - The name of the timeseries.

Returns:

FindTimeseriesBuilder - Returns self for chaining.

Example:

builder.with_name('timeseries_name')

with_env

def with_env(env_key: str, prefer: str = "auto") -> "FindTimeseriesBuilder"

Use an environment variable as the source. ‘prefer’ can be:

‘identifier’ -> treat the value as an identifier
’name’ -> treat the value as a name
‘auto’ -> try identifier and, if not, name

Arguments:

env_key str - The name of the environment variable to read.
prefer str - How to read the value: ‘identifier’, ’name’, or ‘auto’ to try the identifier first and fall back to the name. Defaults to ‘auto’.

find_all

def find_all() -> "FindTimeseriesBuilder"

Searches for all available timeseries resources.

Returns:

FindTimeseriesBuilder - Returns the current instance to allow method chaining.

Example:

builder.with_organization_name('my_organization').find_all()

find_one

def find_one() -> "FindTimeseriesBuilder"

Searches for a single timeseries resource by its identifier.

This method prepares the request to find a specific timeseries based on its identifier. The identifier is obtained automatically if not explicitly defined or can be obtained from a configuration file or environment variables.

Returns:

FindTimeseriesBuilder - Returns the current instance to allow method chaining.

Example:

builder.with_organization_name('my_organization').with_organization_name("organization_name").with_format("dict").with_identifier("identifier").find_one().build().execute()

build

def build() -> "FindTimeseriesBuilder"

Finalizes the construction of the IoT collection configuration.

Returns:

FindTimeseriesBuilder - Returns itself to allow for method chaining, enabling further actions like execute.

Raises:

ValueError - If required configurations are missing or if incompatible methods are used together.

Example:

builder.build()

build_execute

def build_execute()

Executes the timeseries search immediately after building the configuration.

This method is a shortcut that combines building and executing in a single step.

Returns:

dict - A dictionary containing the execution response which includes the status code and potentially other metadata about the execution.

Raises:

ValueError - If build has already been called on this builder instance.

Example:

builder.build_execute()

execute

def execute() -> Response

Execute the configured operation and return the response.

Returns:

requests.Response - The response object from the executed request.

Raises:

Exception - If the build method has not been called or if it is not the last method invoked before execute.
ValueError - If the configured method is unsupported.

Example:

builder.execute()

opengate_data.timeseries

Utils

opengate_data.utils.expressions

Expressions Objects

class Expressions()

Expressions

The filter conditions a search accepts, as static methods returning plain dicts: eq, neq, like, gt, lt, gte, lte, in_, nin and exists. FilterBuilder extends this class, so in practice you reach them through client.new_filter_builder() and combine them with and_ / or_ before calling build().

Example:

filter = client.new_filter_builder().and_(
Expressions.eq("provision.administration.organization", "organization"),
Expressions.exists("provision.device.identifier", True),
).build()

eq

def eq(field, value)

Adds an equality condition to the filter.

Arguments:

field str - The field to compare.
value any - The value to compare against.

Returns:

dict - The equality condition.

Example:

eq(“device.operationalStatus”, “NORMAL”)

neq

def neq(field, value)

Adds a not-equal condition to the filter.

Arguments:

field str - The field to compare.
value any - The value to compare against.

Returns:

dict - The not-equal condition.

Example:

neq(“device.operationalStatus”, “ERROR”)

like

def like(field, value)

Adds a like condition to the filter.

Arguments:

field str - The field to compare.
value str - The regex pattern to match.

Returns:

dict - The like condition.

Example:

like(“device.name”, “device_.*”)

gt

def gt(field, value)

Adds a greater-than condition to the filter.

Arguments:

field str - The field to compare.
value any - The value to compare against.

Returns:

dict - The greater-than condition.

Example:

gt(“device.batteryLevel”, 50)

lt

def lt(field, value)

Adds a less-than condition to the filter.

Arguments:

field str - The field to compare.
value any - The value to compare against.

Returns:

dict - The less-than condition.

Example:

lt(“device.batteryLevel”, 20)

gte

def gte(field, value)

Adds a greater-than-or-equal condition to the filter.

Arguments:

field str - The field to compare.
value any - The value to compare against.

Returns:

dict - The greater-than-or-equal condition.

Example:

gte(“device.batteryLevel”, 80)

lte

def lte(field, value)

Adds a less-than-or-equal condition to the filter.

Arguments:

field str - The field to compare.
value any - The value to compare against.

Returns:

dict - The less-than-or-equal condition.

Example:

lte(“device.batteryLevel”, 30)

in_

def in_(field, values)

Adds an in condition to the filter.

Arguments:

field str - The field to compare.
values list - The list of values to compare against.

Returns:

dict - The in condition.

Example:

in_(“device.name”, [“device_1”, “device_2”])

nin

def nin(field, values)

Adds a not-in condition to the filter.

Arguments:

field str - The field to compare.
values list - The list of values to compare against.

Returns:

dict - The not-in condition.

Example:

nin(“device.name”, [“device_3”, “device_4”])

exists

def exists(field, value)

Adds an existence condition to the filter.

Arguments:

field str - The field to check for existence.
value bool - True to match the entities that have the field, False to match the ones that do not.

Returns:

dict - The existence condition.

Example:

exists("device.location", True)

opengate_data.utils.utils

validate_type

def validate_type(variable: Any, expected_type: Any,
                  variable_name: str) -> None

Validates that the given variable is of the expected type or types.

This function checks if the variable matches the expected type or any type in a tuple of expected types. It raises a TypeError if the variable does not match the expected type(s).

Arguments:

variable Any - The variable to be checked.
expected_type Any - The expected type or a tuple of expected types.
variable_name str - The name of the variable, used in the error message to identify the variable.

Raises:

TypeError - If the variable is not of the expected type(s).

Returns:

None - This function does not return a value; it raises an exception if the type check fails.

set_method_call

def set_method_call(method)

Decorates a method to ensure it is properly registered and tracked within the builder’s workflow.

This decorator adds the method’s name to a set that tracks method calls

Arguments:

method function - The method to be decorated.

Returns:

function - The wrapped method with added functionality to register its call.

Raises:

None - This decorator does not raise exceptions by itself but ensures the method call is registered.

parse_json

def parse_json(value)

Attempts to convert a string into a Python object by interpreting it as JSON.

Arguments:

value str | Any - The value to attempt to convert. If the value is not a string, it is returned directly without attempting conversion.

Returns:

Any - The Python object resulting from the JSON conversion if value is a valid JSON string. If the conversion fails due to a formatting error (ValueError), the original value is returned. If value is not a string, it is returned as is.

send_request

def send_request(method: str,
                 headers: dict | None = None,
                 url: str = "",
                 data: dict[str, Any] | str | None = None,
                 files: Any = None,
                 json_payload: dict[str, Any] | None = None,
                 params: Any = None,
                 verify: bool = False,
                 timeout: int = 3000,
                 stream: bool = False) -> Response | dict[str, Any]

Helper function to make HTTP requests using the requests library.

Arguments:

method str - HTTP method (e.g., ‘GET’, ‘POST’, ‘PUT’, ‘DELETE’, ‘PATCH’).
headers dict, optional - Request headers.
url str - The URL for the request.
data dict | str, optional - Payload for the request body.
files Any, optional - Files for multipart encoding upload.
json_payload dict, optional - JSON payload for the request body.
params dict | Any, optional - URL parameters.
verify bool - Whether to verify SSL certificates. Defaults to False.
timeout int - Request timeout in seconds. Defaults to 3000.
stream bool - Whether to keep the response body unread until it is consumed, which is what a file download needs. Defaults to False.

Returns:

Response | dict[str, Any]: The response object if successful, or an error dictionary.

handle_basic_response

def handle_basic_response(response: requests.Response) -> dict[str, Any]

Handle basic HTTP response.

This function processes the HTTP response and returns a dictionary containing the status code. If the response indicates an error, it also includes the error message.

Arguments:

response requests.Response - The response object to process.

Returns:

dict[str, Any]: A dictionary containing the status code and, if applicable, the error message.

handle_error_response

def handle_error_response(response: requests.Response) -> dict[str, Any]

Turn a failed HTTP response into the dictionary the builders return.

Nothing is raised: the caller gets the status code and, when the platform sent one, the body as the error.

Arguments:

response requests.Response - The response object to process.

Returns:

dict[str, Any]: The status code and, if the response carried a body, the error.

handle_exception

def handle_exception(e)

Turn a transport failure into the dictionary the builders return.

A request that never reached the platform has no status code, so the result names the kind of failure instead: connection, timeout, request or unexpected.

Arguments:

e Exception - The exception raised while sending the request.

Returns:

dict[str, str]: The kind of failure and its details.

validate_build_method_calls_execute

def validate_build_method_calls_execute(method_calls)

Check that a chain was closed properly before execute() runs.

Every builder has to be closed with build() or with build_execute(), and build() has to be the last call before execute() — otherwise a setter called after it would never be validated.

Arguments:

method_calls list[str] - The methods called on the builder, in order.

Raises:

Exception - If build() was called more than once, if it was not the last call before execute(), or if neither build() nor build_execute() was called.

validate_build

def validate_build(*,
                   method: str,
                   state: dict,
                   spec: dict,
                   used_methods: list[str] | None = None,
                   allowed_method_calls: set[str] | None = None,
                   field_aliases: dict[str, str] | None = None,
                   method_aliases: dict[str, str] | None = None) -> None

Generic builder validator with messages intended for the end user.

The two alias maps exist so the errors name what the caller wrote, not the internals: without them a missing with_destiny_path() would be reported as a missing ‘path’.

Arguments:

method str - The operation selected in the chain, which picks its entry in the spec.
state dict - The current value of each field of the builder, by internal name.
spec dict - The rules per operation: ‘required’ and ‘forbidden’ field names, ‘choices’ mapping a field to its allowed values, and ‘custom’ holding extra checks called with the state.
used_methods list[str] | None - The methods called on the builder, in order. Needed to catch two operations in the same chain.
allowed_method_calls set[str] | None - The method names that select an operation, of which a chain may use exactly one, once.
field_aliases dict[str, str] | None - Maps internal fields to public setter names (e.g., ‘path’ → ‘with_path’).
method_aliases dict[str, str] | None - Maps logical method names to public method names (e.g., ’list_one’ → ’list_one()’).

Raises:

RuntimeError - If the chain combines several operations, or repeats one.
ValueError - If no operation was selected, if it is not in the spec, or if the state misses a required field, carries a forbidden one, or holds a value outside its choices.

build_headers

def build_headers(client_headers: dict | None,
                  *,
                  accept: str | None = None,
                  content_type: str | None = None) -> dict

Build request headers starting from client headers (auth preserved) and optionally overriding Accept / Content-Type.

This function NEVER mutates client headers.

Arguments:

client_headers dict | None - The headers of the client, holding the authentication. They are copied, never modified.
accept str | None - The Accept header to set. Left untouched if None.
content_type str | None - The Content-Type header to set. Left untouched if None.

Returns:

dict - A new set of headers.

Python Reference

Subsections of Python Reference

AI Models

opengate_data.ai_models.ai_models

AIModelsBuilder Objects

with_organization_name

with_identifier

with_env

with_find_by_name

with_config_file

add_file

with_prediction

with_output_file_path

create

find_one

find_all

update

delete

validate

download

prediction

save

set_config_file_identifier

set_env_identifier

build

build_execute

execute

opengate_data.ai_models

AI Pipelines

opengate_data.ai_pipelines.ai_pipelines

AIPipelinesBuilder Objects

with_organization_name

with_identifier

with_env

with_find_by_name

with_config_file

with_prediction

with_name

add_action

build

build_execute

create

find_all

find_one

update

delete

prediction

save

set_config_file_identifier

set_env_identifier

execute

opengate_data.ai_pipelines

AI Transformers

opengate_data.ai_transformers.ai_transformers

AITransformersBuilder Objects

with_organization_name

with_identifier

with_env

with_config_file

add_file

with_find_by_name

with_evaluate

with_output_file_path

with_file_name

create

find_all

find_one

update

delete

download

evaluate

save

set_config_file_identifier

set_env_identifier

build

build_execute

execute

opengate_data.ai_transformers

Collection

opengate_data.collection.iot_bulk_collection