Metadata-Version: 2.4
Name: opengate-data
Version: 1.13.0
Summary: Python library for integration with the OpenGate IoT platform
Project-URL: Documentation, https://documentation.opengate.es/libs/ogapy-docs/index.html
Project-URL: Source, https://github.com/amplia-iiot/opengate-data-py
Project-URL: Homepage, https://www.amplia.es
Author: amplia soluciones
Author-email: pipy@amplia.es
License: Apache-2.0
License-File: LICENSE
Keywords: api,data,iot,opengate,sdk
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: aiohttp
Requires-Dist: configparser
Requires-Dist: datetime
Requires-Dist: flatten-dict
Requires-Dist: jsonpath-ng
Requires-Dist: numpy
Requires-Dist: openpyxl
Requires-Dist: pandas
Requires-Dist: parse
Requires-Dist: pyarrow
Requires-Dist: python-dotenv
Requires-Dist: requests
Requires-Dist: urllib3
Description-Content-Type: text/markdown

# 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:

```bash
pip install opengate-data
```

Or, if you are using [uv](https://github.com/astral-sh/uv):

```bash
uv add opengate-data
```

## Quick Start: Searching Entities

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

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

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

## Basic use with api-key

To initialize the client using an api_key:

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

    ```python
    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 `API_KEY` environment variable.

## 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:

     ```bash
     export TOKEN_JWT="token_jwt"
     ```

   - On Windows, use:

      ```bash
      set TOKEN_JWT="token_jwt"
      ```

2. Initialize the client.

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

```python
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](opengate_data/test/unit/) which demonstrate various configurations and use cases.

## Additional Documentation

For more details and examples about each of the modules,
consult the [complete documentation](https://documentation.opengate.es/libs/ogapy-docs/index.html).

## 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)**:

      ```bash
      export UV_PUBLISH_TOKEN=pypi-YOUR_TOKEN_HERE
      ```

    - **Alternative (.pypirc)**:
      Create the `.pypirc` file in your home directory:

      ```ini
      [pypi]
        username = __token__
        password = pypi-YOUR_TOKEN_HERE
      ```

2. **Create file `.env` with this format**

    ```bash
    OPENGATE_URL="URL"
    OPENGATE_API_KEY="OPENGATE_API_KEY"
    ORGANIZATION="ORGANIZATION"
    ```

3. **Generate project documentation**

    Before publishing the package, generate the documentation files:

    ```bash
    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):

    ```bash
    ./dist.sh
    ```

## Test

### Create file `.env` with this format

```bash
OPENGATE_URL="URL"
OPENGATE_API_KEY="OPENGATE_API_KEY"
ORGANIZATION="ORGANIZATION"
```

### Configure your environment

This project uses [uv](https://github.com/astral-sh/uv) for dependency management. To set up your development environment and install all dependencies (including test libraries):

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

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

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

### Running One Unit Test

```bash
uv run pytest opengate_data/test/unit/datasets/test_find_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:

```bash
uv run pytest opengate_data/test/integration
```

or using marker:

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

### Running One Integration Test

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

## License

This project is licensed under the Apache License 2.0.
