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.

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:

  • 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.

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.datasets