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.

Create a .env file with the following content: TOKEN_JWT="token_jwt"
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:

Create environment variable
- On UNIX systems, use:
```
export TOKEN_JWT="token_jwt"
```
- On Windows, use:
```
set TOKEN_JWT="token_jwt"
```
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
- Alarms
- Datapoints
- Data sets
- Entities
- Operations
- Rules
- Timeseries
File Connector
- File Connector

Basic Examples of the OpenGate-Data Modules

The unit tests double as usage examples: opengate_data/test/unit/ holds one directory per module, each showing the configurations and use cases of its builders.

Documentation

The reference for every module is published at documentation.opengate.es/libs/ogapy-docs, generated from the docstrings in this repository. The same reference ships here as a single file, docs/documentation_single.md.

Generate Version and Upload to PyPI

To upload your package to PyPI, follow these steps:

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
```

Create file .env with this format

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

Release from develop
```
git checkout develop
./dist.sh
```
dist.sh drives the whole release and is the only supported way to bump a version. It checks that develop is clean and in sync and that master holds nothing missing from develop, runs the unit and integration suites, regenerates the documentation, merges develop into master, bumps the version, tags vX.Y.Z, publishes to PyPI, creates the GitLab release, back-merges master into develop and leaves you on develop.

Rehearse a release without touching anything remote:
```
./dist.sh --dry-run
```
If the integration suite fails for a known, unrelated reason, --force-integration continues but requires a written justification that is recorded in the release notes.

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.

Metadata

Release files for opengate-data 1.15.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for opengate-data 1.15.2
File	Size	Uploaded
opengate_data-1.15.2.tar.gz	537.4 kB	Jul 30, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for opengate-data 1.15.2
File	Interpreter	ABI	Platform	Reset
opengate_data-1.15.2-py3-none-any.whl 365.5 kB Jul 30, 2026	Python 3	none	any	Details

Total release size: 902.9 kB

Release files / opengate_data-1.15.2.tar.gz

Download URL	opengate_data-1.15.2.tar.gz
Size	537.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`89b646217c6995731da91264f791547d98083bb72ac1bd5db9d017f4388ace85`
BLAKE2b-256 checksum How to use checksums	`79a1c78ad526502d6d637be12645c9028af20c907c6067206fd92c88b17f18c8`
Upload date	Jul 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.8`

Release files / opengate_data-1.15.2-py3-none-any.whl

Download URL	opengate_data-1.15.2-py3-none-any.whl
Size	365.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4664f2a5669f883aa3c1693ebf805fee32b2aa5a2c5cd36b29c61f818cb7d497`
BLAKE2b-256 checksum How to use checksums	`11250e64209b4d2f5c0a406410c2b0228f3c927574e0df01990a1d7e0e50e0cf`
Upload date	Jul 30, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.9.8`