Metadata-Version: 2.4
Name: tai-storage
Version: 0.2.1
Summary: Librería para gestión unificada de archivos en múltiples orígenes de almacenamiento
Author: MateoSaezMata
Author-email: msaez@triplealpha.in
Requires-Python: >=3.10, <4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Provides-Extra: all
Provides-Extra: analysis
Provides-Extra: azure
Provides-Extra: azure-identity
Provides-Extra: data
Provides-Extra: dev
Provides-Extra: googledrive
Provides-Extra: sharepoint
Requires-Dist: azure-identity (>=1.15.0) ; extra == "all"
Requires-Dist: azure-identity (>=1.15.0) ; extra == "azure-identity"
Requires-Dist: azure-storage-blob (>=12.0.0) ; extra == "all"
Requires-Dist: azure-storage-blob (>=12.0.0) ; extra == "azure"
Requires-Dist: azure-storage-blob (>=12.0.0) ; extra == "azure-identity"
Requires-Dist: google-auth (>=2.0.0) ; extra == "all"
Requires-Dist: google-auth (>=2.0.0) ; extra == "googledrive"
Requires-Dist: httpx (>=0.27,<1.0) ; extra == "all"
Requires-Dist: httpx (>=0.27,<1.0) ; extra == "googledrive"
Requires-Dist: httpx (>=0.27,<1.0) ; extra == "sharepoint"
Requires-Dist: hypothesis (>=6.0) ; extra == "dev"
Requires-Dist: jinja2 (>=3.1) ; extra == "all"
Requires-Dist: jinja2 (>=3.1) ; extra == "analysis"
Requires-Dist: msal (>=1.20.0) ; extra == "all"
Requires-Dist: msal (>=1.20.0) ; extra == "sharepoint"
Requires-Dist: numpy (>=1.24.0) ; extra == "all"
Requires-Dist: numpy (>=1.24.0) ; extra == "analysis"
Requires-Dist: numpy (>=1.24.0) ; extra == "data"
Requires-Dist: openpyxl (>=3.1.0) ; extra == "all"
Requires-Dist: openpyxl (>=3.1.0) ; extra == "data"
Requires-Dist: pandas (>=2.0.0,<3.0.0) ; (python_version < "3.11") and (extra == "all")
Requires-Dist: pandas (>=2.0.0,<3.0.0) ; (python_version < "3.11") and (extra == "analysis")
Requires-Dist: pandas (>=2.0.0,<3.0.0) ; (python_version < "3.11") and (extra == "data")
Requires-Dist: pandas (>=3.0.0) ; (python_version >= "3.11") and (extra == "all")
Requires-Dist: pandas (>=3.0.0) ; (python_version >= "3.11") and (extra == "analysis")
Requires-Dist: pandas (>=3.0.0) ; (python_version >= "3.11") and (extra == "data")
Requires-Dist: plotly (>=5.24) ; extra == "all"
Requires-Dist: plotly (>=5.24) ; extra == "analysis"
Requires-Dist: pyarrow (>=12.0.0) ; extra == "all"
Requires-Dist: pyarrow (>=12.0.0) ; extra == "data"
Requires-Dist: pytest (>=8.0) ; extra == "dev"
Requires-Dist: tai-alphi (>=2.1.0,<3.0)
Requires-Dist: xlrd (>=2.0.0) ; extra == "all"
Requires-Dist: xlrd (>=2.0.0) ; extra == "data"
Project-URL: Documentation, https://triplealpha-innovation.github.io/tai-storage/
Project-URL: Issues, https://github.com/triplealpha-innovation/tai-storage/issues
Project-URL: Repository, https://github.com/triplealpha-innovation/tai-storage
Description-Content-Type: text/markdown

# tai-storage

[![PyPI](https://img.shields.io/pypi/v/tai-storage.svg)](https://pypi.org/project/tai-storage/)
[![Python](https://img.shields.io/pypi/pyversions/tai-storage.svg)](https://pypi.org/project/tai-storage/)
[![Manual](https://img.shields.io/badge/manual-github.io-blue.svg)](https://triplealpha-innovation.github.io/tai-storage/)

**Los mismos ficheros, estén donde estén.** Una sola API para el disco local, SharePoint Online,
Azure Blob Storage y Google Drive, **con la misma semántica en los cuatro**, y la lectura de CSV,
Excel, JSON y Parquet como DataFrames, sin perder ni una fila ni una columna sin avisar.

```
StorageFactory.create_*()  ──▶  Origin  ──get_folder()──▶  Folder  ──get_file()──▶  File
 local · sharepoint ·            la raíz                    list_files()             read() · write()
 azure · googledrive                                        upload_file()            move_to() · delete()
                                                                                     get_data() → DataFrame
```

📖 **[El manual completo está en triplealpha-innovation.github.io/tai-storage](https://triplealpha-innovation.github.io/tai-storage/)**

---

## Quickstart

```bash
pip install "tai-storage[sharepoint,data]"
export SHAREPOINT_TENANT_ID=… SHAREPOINT_CLIENT_ID=… SHAREPOINT_CLIENT_SECRET=…
export SHAREPOINT_HOSTNAME=contoso.sharepoint.com SHAREPOINT_SITE_NAME=Ventas
```

```python
from tai_storage import StorageFactory

origin = StorageFactory.create_sharepoint()                 # comprueba ya las credenciales

for file in origin.get_folder("Clientes/Entrada").list_files(pattern=r"\.xlsx$"):
    df = file.get_data().to_dataframe(sheet_name="Pedidos")  # formato español, sin perder ceros ni decimales
    ...
    file.move_to(origin.get_file(f"Clientes/Procesados/{file.filename}"))
```

Con `create_local("datos")`, `create_azure(container="ventas")` o `create_googledrive()` el resto
del código **no cambia**. Con `dev_mode=True`, lo que se lee se guarda en una caché local
mientras desarrollas.

---

## Los principios que explican el resto

1. **Nada falla en silencio.** Toda operación devuelve lo que promete o lanza un error con **qué
   ha pasado y qué hacer**. `exists()` no devuelve `False` porque haya caducado un token, y leer un
   CSV no convierte en vacío lo que no entiende.
2. **Un contrato, cuatro backends.** El mismo código hace lo mismo en los cuatro, con caché o sin
   ella. Lo prueba una misma batería de tests contra cada uno.
3. **Seguro por defecto.** Una ruta nunca sale del origen, y nada se sobrescribe ni se borra sin
   pedirlo.
4. **Importar no tiene efectos.** `import tai_storage` no carga pandas ni los SDK, no conecta y no
   lee el entorno.
5. **El coste se sabe.** Cada operación remota documenta cuántas peticiones hace, y los ficheros
   grandes van por trozos (1 GB, unos 20 MB de memoria).

---

## Qué trae

| | |
|---|---|
| **Cuatro orígenes** | Local, SharePoint (Microsoft Graph), Azure Blob Storage y Google Drive, con la misma API y la misma semántica |
| **Errores con solución** | Cada error dice qué hacer; los de fichero son también los de Python (`except FileNotFoundError`) |
| **Robustez** | Token que se renueva, reintentos de 429 y 5xx con `Retry-After`, paginación, subidas por trozos sin límite de tamaño |
| **`dev_mode`** | Una caché local de lo que se lee, con la semántica exacta del servicio |
| **DataFrames** | CSV, Excel, JSON y Parquet; formato español por defecto; la inferencia nunca introduce un nulo; los tipos declarados fallan diciendo la línea o la celda |
| **Informe de datos** | `analyze(df).save(…)`: un HTML autocontenido con los avisos y una ficha por columna |
| **Logs** | Con tai-alphi: lo que cambia algo en `INFO`, lo anómalo en `WARNING`, nunca secretos |
| **Reglas para asistentes de IA** | `tai-storage rules install` deja en tu proyecto lo que un asistente necesita saber de la librería |

## Instalación

```bash
pip install tai-storage                    # núcleo y disco local
pip install "tai-storage[sharepoint]"      # SharePoint (httpx, msal)
pip install "tai-storage[azure]"           # Azure Blob (azure-storage-blob); [azure-identity] sin clave
pip install "tai-storage[googledrive]"     # Google Drive (httpx, google-auth)
pip install "tai-storage[data]"            # DataFrames (pandas, openpyxl, xlrd, pyarrow)
pip install "tai-storage[analysis]"        # el informe HTML (pandas, plotly, jinja2)
pip install "tai-storage[all]"             # todo
```

Python 3.10 o posterior. Detalle de cada extra, y qué hacer si falta, en
[Instalación](https://triplealpha-innovation.github.io/tai-storage/empezar/instalacion/). Si vienes
de la 0.1: [De la 0.1 a la 0.2](https://triplealpha-innovation.github.io/tai-storage/referencia/migracion/).

## Desarrollo

```bash
pip install -e ".[all,dev]"
pytest -m "not sharepoint and not azure and not googledrive and not azurite"

pip install -r docs/requirements.txt
mkdocs serve                              # el manual en http://127.0.0.1:8000
```

El manual (`docs/`) es para quien **usa** tai-storage. Cómo está montada y qué no romper, para
quien trabaja **en** ella: [CLAUDE.md](CLAUDE.md), [.claude/rules/](.claude/rules/) y
[specs/](specs/README.md).

## Autores

- **Mateo Saez Mata** — [msaez@triplealpha.in](mailto:msaez@triplealpha.in)

