Metadata-Version: 2.5
Name: inventa-client
Version: 1.0.0
Summary: INVENTA API Client Library
Project-URL: Documentation, https://www.vectronic-aerospace.com/inventa-api-python-client-library
Project-URL: Source code, https://github.com/Vectronic-Aerospace/inventa-api-python-client-library
Author-email: VECTRONIC Aerospace <mail@vectronic-aerospace.com>
License-Expression: Apache-2.0
License-File: LICENSE.txt
Keywords: Aerospace,Inventa,Vectronic,Wildlife
Requires-Python: >=3.10
Requires-Dist: alembic>=1.18.4
Requires-Dist: apscheduler>=3.10
Requires-Dist: httpx<1.0,>=0.28
Requires-Dist: pydantic>=2
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: sqlalchemy<3.0,>=2.0
Requires-Dist: typer>=0.12
Requires-Dist: typing-extensions>=4.7.1
Requires-Dist: urllib3<3.0.0,>=2.1.0
Provides-Extra: mysql
Requires-Dist: mysqlclient>=2.2.8; extra == 'mysql'
Provides-Extra: postgresql
Requires-Dist: psycopg2>=2.9.12; extra == 'postgresql'
Description-Content-Type: text/markdown

# INVENTA API Client

[GitHub Repository](https://github.com/Vectronic-Aerospace/inventa-api-python-client-library)

This project provides a Python client library for interacting with the [INVENTA API](https://www.vectronic-aerospace.com/inventa-api/). 

# Installation

Install the base package via pip:

```bash
pip install inventa-client
```

## Optional Database Dependencies

Depending on what database you want to use, you can install the corresponding optional dependency:

| Database   | installation command                     | additional libraries                                                                                  |
|------------|------------------------------------------|-------------------------------------------------------------------------------------------------------|
| SQLite     | `pip install inventa-client`             | no additional dependency will be installed                                                            |
| PostgreSQL | `pip install inventa-client[postgresql]` | Installs the `psycopg2` library (licensed under LGPL)                                                 |
| MySQL      | `pip install inventa-client[mysql]`      | Installs the `mysqlclient` library (licensed under GPL; may introduce additional license obligations) |


If you intend to use a different database (e.g., Oracle or Microsoft SQL Server), or prefer a different database driver for PostgreSQL/MySQL, install the appropriate driver manually. Please refer to the [Database URL Documentation of SQLAlchemy](https://docs.sqlalchemy.org/en/20/core/engines.html#supported-databases) for details..

# Usage

## Database Configuration

To store data inside the database, you need to provide a valid database URL. The database URL should follow the format supported by SQLAlchemy. For example:

| database URL                                    | Your Database     | 
|-------------------------------------------------|-------------------|
| `sqlite:///C:\\path\\to\\database`              | SQLite (Windows)  |
| `sqlite:////absolute/path/to/database`          | SQLite (Unix/Mac) | 
| `postgresql://user:password@host:port/database` | PostgreSQL        | 
| `mysql://user:password@host:port/database`      | MySQL             | 

See the [Database URL Documentation of SQLAlchemy](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls) for more details.

## API Key

To download data, you need an [INVENTA API key](https://inventa.vectronic-wildlife.com/api-keys).

## Core Functions

### `create_schema`

```python
from inventa import create_schema

create_schema(
    db_url="...",
    enable_postgis=True
)
```

Creates the required database schema if it does not already exist.
- Required parameters:
  - db_url: database connection string
- Optional parameters:
  - enable_postgis: adds a PostGIS `GEOMETRY(Point, 4326)` column called `geom` to the `positions` table. Works only with PostgreSQL and when PostGIS is installed. (If omitted, the `geom` column will not be created)

### `validate_schema`

```python
from inventa import validate_schema

validate_schema(
    db_url="...",
    enable_postgis=True
)
```

Validates the database schema and logs compatibility issues.
- Required parameters:
  - db_url: database connection string
- Optional parameters:
  - enable_postgis: adds a PostGIS `GEOMETRY(Point, 4326)` column called `geom` to the `positions` table. Works only with PostgreSQL and when PostGIS is installed. (If omitted, the `geom` column will not be validated)

### `download_devices`

```python
from inventa import download_devices

download_devices(
    db_url="...",
    api_key="...",
    enable_progress_log=True
)
```

Downloads collar and trap device metadata and stores it in the database.
- Required parameters:
  - db_url: database connection string
  - api_key: INVENTA API key
- Optional parameters:
  - enable_progress_log: enables logging (if omitted, progress will not be logged)

### `download_events_once`

```python
from inventa import download_events_once, DataType

download_events_once(
    db_url="...",
    api_key="...",
    device_ids=[1000106,1000100],
    data_types=[DataType.POSITION, DataType.MORTALITY],
    enable_progress_log=True,
    enable_postgis=True
)
```

Downloads event data from the INVENTA API and stores it in the database.

- Automatically fetches only new data based on existing records
- Validates the database schema before execution
- Required parameters:
  - db_url: database connection string
  - api_key: INVENTA API key
- Optional parameters:
  - device_ids: limits data to specific devices (if omitted, data for all available devices will be downloaded)
  - data_types: filters by data types (if omitted, data for all available data types will be downloaded)
  - enable_progress_log: enables logging (if omitted, progress will not be logged)
  - enable_postgis: adds a PostGIS `GEOMETRY(Point, 4326)` column called `geom` to the `positions` table. Works only with PostgreSQL and when PostGIS is installed. (If omitted, the `geom` column will not be populated)

### `download_events_scheduled`

```python
from inventa import download_events_scheduled, DataType

download_events_scheduled(
    db_url="...",
    api_key="...",
    repeat_minutes=30,
    device_ids=[1000106, 1000100],
    data_types=[DataType.POSITION, DataType.MORTALITY],
    enable_progress_log=True,
    enable_postgis=True
)
```

Runs `download_events_once` on a schedule.

- The main application thread must remain active
- Required parameters:
  - db_url: database connection string
  - api_key: INVENTA API key
  - repeat_minutes: interval in minutes (>= 15)
- Optional parameters:
  - device_ids: limits data to specific devices (if omitted, data for all available devices will be downloaded)
  - data_types: filters by data types (if omitted, data for all available data types will be downloaded)
  - enable_progress_log: enables logging (if omitted, progress will not be logged)
  - enable_postgis: adds a PostGIS `GEOMETRY(Point, 4326)` column called `geom` to the `positions` table. Works only with PostgreSQL and when PostGIS is installed. (If omitted, the `geom` column will not be populated)

## Direct API Access

In addition to high-level methods, the library allows direct interaction with the API.

Example: Download position data

```python
from inventa.openapi_client import DownloadDataApi, ApiClient

api_client = ApiClient()
api_client.default_headers['x-api-key'] = "..."

dataApi = DownloadDataApi(api_client=api_client)

data = dataApi.get_position_data(
    page=0,
    filters_dto={'collarIds': [1000106,1000100]},
    gt_id=0
)
```
### Pagination and Incremental Fetching
- The response will contain metadata about the page. Use this information to get all available pages.
- `page` is required 
- `gt_id` is required:
  - Retrieve only records with an ID greater than the provided value
  - Use `0` for initial requests
  - Use the highest known ID for subsequent calls

## DTOs and Models

The library provides:
- DTOs (Data Transfer Objects) for API responses
- Database models mirroring these DTOs

Example imports:
```python
from inventa.openapi_client import PageDtoPositionDto, PositionDto
from inventa import Position
```

# Command Line Interface

The library provides a command line interface for the Core Functions. You can run: 
```bash
inventa-sync download-events --db-connection-string "..." --api-key "..."

inventa-sync download-events --db-connection-string "..." --api-key "..." --repeat-minutes 60

inventa-sync download-devices --db-connection-string "..." --api-key "..."

inventa-sync validate-schema --db-connection-string "..."

inventa-sync create-schema --db-connection-string "..."
```

For details on the command line interface:
```bash
inventa-sync --help
```

# Build

To build the project, clone it from [GitHub](https://github.com/Vectronic-Aerospace/inventa-api-python-client-library) and run `pip install -e .`.

# Legal Notice

This project is licensed with the Apache License, Version 2.0. See LICENSE.txt for details.

This project depends on third-party libraries with their own licenses. Optional dependencies may introduce additional license requirements. See NOTICE.txt for details.
