opengate-data 1.14.0

Python library for integration with the OpenGate IoT platform

Opengate-data

Opengate-data is a Python library (requires Python 3.10+) that helps you integrate OpenGate into your Python projects.

Installation

To install the library, run:

pip install opengate-data

Or, if you are using uv:

uv add opengate-data

Quick Start: Searching Entities

Here is a simple example of how to search for entities using the EntitiesSearchBuilder:

from opengate_data import OpenGateClient

# Initialize the client
client = OpenGateClient(url="https://api.opengate.es", api_key="YOUR_API_KEY")

# Create a search builder
search = client.new_entities_search_builder()

# Build the query with filters and selection
search.with_filter(
    client.new_filter_builder().eq("provision.administration.organization", "your_org").build()
).with_select(
    client.new_select_builder().add("provision.device.identifier", ["value"]).build()
).with_limit(10, 0)

# Execute the search
results = search.execute()
print(results)

Basic use with user and password

To initialize the OpenGateClient using a username and password:

client = OpenGateClient(url="Url", user="User", password="Password")

Basic use with api-key

To initialize the client using an api_key:

client = OpenGateClient(url="Url", api_key="Api_Key")

Basic use token_jwt with .env

To initialize the client using a token_jwt with a .env file.

1. Create a .env file with the following content: TOKEN_JWT="token_jwt"

2. Load the environment variable and initialize the client:

   client = OpenGateClient()
   

By default, if you use OpenGateClient without parameters, and you set the environment variable TOKEN_JWT, OpenGateClient will be created with this value. If you want to use TOKEN_JWT from environment, you may delete the OPENGATE_API_KEY environment variable.

Basic use with environment variables

The most professional way to initialize the client is by using standard environment variables. If you set these, you can simply call OpenGateClient():

# export OPENGATE_URL="https://api.opengate.es"
# export OPENGATE_API_KEY="YOUR_API_KEY"

client = OpenGateClient()

Basic use of token_jwt with an environment variable

To initialize the client using a token_jwt from an environment variable, you can set the token_jwt directly in your environment without relying on a .env:

1. Create environment variable

   • On UNIX systems, use:

     export TOKEN_JWT="token_jwt"
     

   • On Windows, use:

     set TOKEN_JWT="token_jwt"
     

2. Initialize the client.

   client = OpenGateClient()
   

Similar to the previous example, if you use OpenGateClient without parameters, and you set the environment variable TOKEN_JWT, OpenGateClient will be created with this value. If you want to use TOKEN_JWT from environment, you may delete API_KEY variable environment.

Basic use without url for services K8s

To initialize the OpenGateClient without specifying a URL, you can either omit the url parameter or set it to None.

client = OpenGateClient(api_key="Api_Key")
# or
client = OpenGateClient(url=None, api_key="Api_Key")

Similar to the previous examples, you have the option to provide the api_key directly, set it to None, or omit it altogether. If you choose to omit it, the client will automatically retrieve the api_key from the environment variable if it is set. Additionally, you can also authenticate using a username and password by specifying those credentials instead.

Features

The library consists of the following modules:

• IA
  • Models
  • Pipelines
  • Transformers
• Collection
  • Collection
  • Bulk Collection
  • Pandas Collection
• Provision
  • Asset
  • Bulk
  • Devices
  • Processor
• Rules
  • Rules
• Searching
  • Datapoints
  • Data sets
  • Entities
  • Operations
  • Rules
  • Timeseries
• File Connector
  • File Connector

Documentation

The full API documentation for all modules is available at docs/documentation_single.md

Basic Examples of the OpenGate-Data Modules

The examples of the different modules can be found in the unit tests which demonstrate various configurations and use cases.

Additional Documentation

For more details and examples about each of the modules, consult the complete documentation.

Generate Version and Upload to PyPI

To upload your package to PyPI, follow these steps:

1. Configure PyPI credentials

   PyPI requires API tokens for authentication (username/password is no longer supported).

   • Recommended (Environment Variable):

     export UV_PUBLISH_TOKEN=pypi-YOUR_TOKEN_HERE
     

   • Alternative (.pypirc): Create the .pypirc file in your home directory:

     [pypi]
       username = __token__
       password = pypi-YOUR_TOKEN_HERE
     

2. Create file .env with this format

   OPENGATE_URL="URL"
   OPENGATE_API_KEY="OPENGATE_API_KEY"
   ORGANIZATION="ORGANIZATION"
   

3. Generate project documentation

   Before publishing the package, generate the documentation files:

   uv run ./generate_doc.sh
   

   This will create or update docs/documentation_single.md with the latest docstrings.

4. Build and upload the package

   Run the following script to build and upload the package (it uses uv build and uv publish internally):

   ./dist.sh
   

Test

Create file .env with this format

OPENGATE_URL="URL"
OPENGATE_API_KEY="OPENGATE_API_KEY"
ORGANIZATION="ORGANIZATION"

Configure your environment

This project uses uv for dependency management. To set up your development environment and install all dependencies (including test libraries):

uv sync

This will create a virtual environment in .venv and install everything defined in pyproject.toml.

Running All Tests

If you want to run all the tests (unit and integration), simply run:

uv run pytest

This will discover and run all test files matching the pattern defined in pytest.ini.

Running All Unit Tests

Unit tests are located under:

opengate_data/test/unit/

Each subfolder corresponds to a module (e.g., search, collect, rules, etc.).

To run all unit tests:

uv run pytest -m unit -x --maxfail=1

Running One Unit Test

uv run pytest opengate_data/test/unit/searching/test_datasets.py

Running All Integration Tests

Integration tests are located under:

opengate_data/test/integration/

Each subfolder corresponds to a module (e.g., search, collect, rules, etc.).

To run all integration tests:

uv run pytest opengate_data/test/integration

or using marker:

uv run pytest -m integration -x --maxfail=1

Running One Integration Test

uv run pytest opengate_data/test/integration/steps_definitions/step_datasets.py

License

This project is licensed under the Apache License 2.0.