Metadata-Version: 2.4
Name: tecsci-cloud-api
Version: 0.2.1
Summary: Python client for Tecsci Cloud.
Author: TECSCI SAS
Project-URL: Homepage, https://cloud.tecsci.com.ar
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: tb-rest-client==4.3
Requires-Dist: requests<3,>=2.31
Requires-Dist: tzdata>=2024.1
Provides-Extra: dev
Requires-Dist: bandit<2,>=1.9; extra == "dev"
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: detect-secrets<2,>=1.5; extra == "dev"
Requires-Dist: pip-audit<3,>=2.10; extra == "dev"
Requires-Dist: ruff<1,>=0.11; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"

# Tecsci Cloud Python API

Cliente Python para consultar dispositivos, assets y telemetría de **Tecsci Cloud**,
exportar datos a CSV y automatizar tareas de administración en Tecsci Cloud.
Usa API key y se conecta por defecto a `https://cloud.tecsci.com.ar`.

## Instalación

Necesitás **Python 3.10 o posterior** y una API key con acceso a las entidades
que quieras consultar. Las funciones de grupos y administración requieren los
permisos correspondientes de Tecsci Cloud.

Instalá la versión publicada desde PyPI, sin clonar ningún repositorio:

```bash
python -m pip install tecsci-cloud-api==0.2.1
```

No necesitás Git, credenciales de descarga ni acceso al repositorio de desarrollo.
El paquete incluye el código fuente de la versión, sin el historial de commits.

## Primera consulta

Configurá la clave en la terminal; no la escribas dentro del código:

```bash
export TECSCI_CLOUD_API_KEY="tu-api-key"
```

En PowerShell: `$env:TECSCI_CLOUD_API_KEY = "tu-api-key"`.
La biblioteca recibe la clave explícitamente; los ejemplos y comandos la leen del entorno.

```python
import os
from tecsci_cloud_python_api import TecsciCloudClient

with TecsciCloudClient(api_key=os.environ["TECSCI_CLOUD_API_KEY"]) as client:
    telemetry = client.get_latest_device_telemetry(
        device_name="sensor-001",  # Reemplazá por el nombre de tu dispositivo.
        keys=["temperature"],     # Usá una key que exista en tu dispositivo.
    )
    print(telemetry)
```

Para otro servidor, pasá `base_url="https://tu-servidor.example"` al constructor.
Los nombres de dispositivos, clientes y keys de esta guía son ficticios.

## Ejemplos ejecutables

Después de instalar el paquete, descargá y descomprimí la distribución fuente
como indica la [guía de instalación](docs/installation.md#ver-el-código-fuente).
Desde la carpeta descomprimida:

```bash
python examples/read_telemetry.py --device sensor-001 --keys temperature humidity
python examples/export_devices.py --customer Demo --output exports/devices.csv
```

Ambos ejemplos consultan datos; no modifican entidades del servidor.
Consultá [examples/README.md](examples/README.md) para ver resultados y opciones.

## Exportar desde la terminal

Estos comandos se instalan con el paquete y funcionan desde cualquier directorio:

```bash
tecsci-export-telemetry --customer Demo --days 30
tecsci-export-temperature-limits --customer Demo
```

Usá `--help` para ver todas las opciones. Ambos leen `TECSCI_CLOUD_API_KEY`.
El primer comando genera un CSV por asset del tipo `temp_door`, con sus datos de
los últimos 30 días. El segundo exporta los atributos `minTemp` y `maxTemp`.
Podés cambiar el tipo con `--asset-type`; los archivos se guardan en `exports/`.

## Qué ofrece la biblioteca

| Tarea | Métodos principales |
| --- | --- |
| Consultar dispositivos y assets | `get_device`, `get_asset`, `list_customer_devices`, `list_customer_assets` |
| Leer telemetría | `get_latest_device_telemetry`, `get_device_telemetry`, `get_asset_telemetry` |
| Guardar telemetría | `save_device_telemetry`, `save_asset_telemetry` |
| Exportar e importar CSV | `download_customer_devices_to_csv`, `download_asset_telemetry_to_csv`, `upload_asset_telemetry_from_csv` |
| Administrar entidades | atributos, perfiles, usuarios, relaciones y asignación a clientes |
| Procesar históricos | copia de telemetría y reconstrucción de diferencias de energía |

- [Referencia completa de firmas públicas](docs/api.md)
- [Guía de operaciones y formatos CSV](docs/usage.md)
- [Desarrollo, pruebas y distribución](CONTRIBUTING.md)

Los timestamps son **Unix epoch en milisegundos**. Las columnas de fecha legibles
en los CSV están en UTC. Las operaciones por lotes pueden devolver errores por
entidad: revisá el resultado completo. Las escrituras pueden sobrescribir datos
con la misma key y timestamp. Los métodos de renombrado admiten `dry_run=True`.

## Solución de problemas

| Problema | Qué revisar |
| --- | --- |
| `ModuleNotFoundError` | Usá el comando de instalación de esta guía con el mismo Python que ejecuta tu script. |
| Falta `TECSCI_CLOUD_API_KEY` | Definí la variable en la misma terminal desde la que ejecutás el ejemplo. |
| Respuesta 401 o 403 | Verificá la vigencia de la API key, los permisos y el servidor configurado. |
| Entidad no encontrada o resultado vacío | Revisá el nombre, las keys, el cliente propietario y el rango de fechas. |
| Error de conexión o certificado | Verificá la URL, la conectividad y la cadena de certificados del servidor. |

Los exports históricos reúnen datos en memoria; para volúmenes grandes, dividí
la descarga en rangos de fechas.

## Desarrollo

```bash
python -m pip install -e ".[dev]"
python -m unittest discover -s tests -v
ruff check .
python -m build
python -m twine check dist/*
```

Los tests usan mocks y archivos temporales; no requieren credenciales ni acceso a
Tecsci Cloud. El repositorio incluye código, documentación, ejemplos y tests;
los datos exportados, claves y archivos temporales quedan fuera de Git.
