Metadata-Version: 2.5
Name: gicc-datasets
Version: 0.2.0
Summary: Versioned datasets in Amazon S3, using your existing AWS permissions.
Project-URL: Homepage, https://github.com/pshiguihara/gicc-datasets
Project-URL: Documentation, https://github.com/pshiguihara/gicc-datasets/blob/main/docs/tutorial.md
Project-URL: Issues, https://github.com/pshiguihara/gicc-datasets/issues
Author: pshiguihara
License-Expression: MIT
License-File: LICENSE
Keywords: aws,datasets,research,s3
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Requires-Dist: boto3<2,>=1.35.99
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: moto[s3]<6,>=5; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: ruff>=0.11; extra == 'dev'
Requires-Dist: twine>=6; extra == 'dev'
Description-Content-Type: text/markdown

# gicc-datasets

**Datasets versionados en Amazon S3, desde Python o la terminal.**

[![PyPI](https://img.shields.io/pypi/v/gicc-datasets?color=176B87)](https://pypi.org/project/gicc-datasets/)
[![Python](https://img.shields.io/pypi/pyversions/gicc-datasets)](https://pypi.org/project/gicc-datasets/)
[![License: MIT](https://img.shields.io/badge/license-MIT-64748B)](https://github.com/pshiguihara/gicc-datasets/blob/main/LICENSE)

Sube carpetas, ZIP o archivos. Descarga versiones específicas y verifica su contenido con SHA-256.
Cada usuario utiliza sus propias credenciales AWS y los permisos asignados a su bucket y prefijo.

## Instalar

Python 3.11 o posterior. Se recomienda un entorno virtual.

```bash
pip install gicc-datasets
```

## Empezar con las claves entregadas por tu equipo

El responsable te entrega **tus propias claves**, bucket, región y prefijo permitido. No necesitas AWS CLI, perfiles, `~/.aws`, el repositorio ni scripts adicionales.

```bash
# Una sola vez; solicita el destino y las claves con entrada oculta.
gicc-datasets setup

# Uso diario, desde cualquier carpeta con tus datos.
gicc-datasets upload ./datos.csv
```

`setup` comprueba la identidad y el listado del prefijo antes de guardar. Para un usuario IAM propone `uploads/NOMBRE_USUARIO/`; confirma el prefijo asignado por el administrador. No crea recursos ni concede permisos. La escritura se comprueba al subir.

La carga elige el nombre del dataset a partir del archivo y una versión única con fecha UTC. Al terminar imprime el comando exacto para descargar. Cópialo; por ejemplo, sustituyendo `VERSION_MOSTRADA`:

```bash
gicc-datasets download datos --version VERSION_MOSTRADA
```

La descarga se guarda en `./descargas/datos/VERSION_MOSTRADA/` y verifica tamaño y SHA-256. Consulta las versiones con `gicc-datasets versions datos`.

Las claves se guardan **sin cifrar** en `~/.config/gicc-datasets/credentials.json`, con permisos `600` en macOS/Linux y carpeta `700`. El destino se guarda en `config.toml`. Si defines `XDG_CONFIG_HOME`, se usa esa ubicación. No compartas estos archivos. `gicc-datasets logout` elimina las claves locales; no revoca el acceso AWS. Para claves temporales, usa `setup --temporary`, introduce también el token y renueva las credenciales cuando expiren.

## Archivos, carpetas y ZIP

| Origen | Comando | Resultado |
| :--- | :--- | :--- |
| Carpeta | `upload ./datos` | Conserva archivos y subcarpetas. |
| ZIP | `upload ./datos.zip` | Conserva el ZIP intacto. |
| ZIP extraído | `upload ./datos.zip --extract-zip` | Publica los archivos del ZIP. |
| Archivo | `upload ./datos.csv` | Conserva el archivo original. |

Anteponer `gicc-datasets` a cada comando. Una versión publicada no se reemplaza desde el cliente. Puedes seguir eligiendo nombres, versiones y destinos explícitos:

```bash
gicc-datasets upload ./datos --dataset muestra --version 1.0.0 --dry-run
gicc-datasets upload ./datos --dataset muestra --version 1.0.0
gicc-datasets download muestra --version 1.0.0 --output ./mi-descarga
```

`--dry-run` revisa archivos, bytes y exclusiones sin llamar a AWS; una versión automática mostrada en un ensayo no queda reservada. Las exclusiones no detectan todos los secretos: mantén las claves y su Excel fuera de los datos.

## Python

```python
from gicc_datasets import DatasetClient

client = DatasetClient.from_config()  # Reutiliza setup.
release = client.upload("./datos.csv")
client.download(release.dataset, version=release.version)
```

También se admite `DatasetClient(bucket=..., prefix=..., region=..., access_key_id=..., secret_access_key=...)` y `session_token` para acceso directo sin guardar claves. Obtén los valores con entrada oculta o un gestor de secretos; no los escribas en código.

## Si ya usas perfiles, SSO o roles

El flujo anterior sigue disponible:

```bash
gicc-datasets configure --profile gicc --bucket mi-bucket \
  --prefix datasets/mi-equipo/ --region us-east-1
gicc-datasets doctor
```

`configure` guarda solo destino y perfil. Los perfiles seleccionados y las credenciales de entorno tienen prioridad sobre las claves de `setup`. Sin ellos, se usan las claves guardadas por el paquete; si no existen, se conserva la cadena estándar de Boto3. En servicios con rol AWS, usa un entorno sin claves guardadas por `setup`. Las claves directas de la API tienen prioridad y no se pueden combinar con `profile` o `s3_client`.

## Consultar

```bash
gicc-datasets list
gicc-datasets versions muestra
gicc-datasets info muestra --version 1.0.0
gicc-datasets --json list
```

## Acceso y alcance

- Instalar el paquete no concede acceso a S3. AWS aplica los permisos de cada identidad.
- `doctor` verifica identidad y listado del prefijo; no prueba la escritura ni modifica S3.
- No incluye operaciones de borrado, administración IAM ni modificación de ACL.
- Las descargas verifican tamaño y SHA-256 antes de copiar los datos al destino.
- La protección contra sobrescrituras de versiones corresponde al cliente; no sustituye controles de retención en AWS.

Para archivos de más de 1 GB, reserva espacio temporal: se copia cada archivo al subir y se prepara la descarga completa para verificarla. La subida utiliza multipart y reintentos, pero no reanuda entre procesos ni muestra barra de progreso. Consulta a TI si el firewall bloquea HTTPS saliente a S3 o STS; conserva la verificación TLS.

**[Tutorial](https://github.com/pshiguihara/gicc-datasets/blob/main/docs/tutorial.md)** · **[Permisos](https://github.com/pshiguihara/gicc-datasets/blob/main/docs/permissions.md)** · **[Formato y límites](https://github.com/pshiguihara/gicc-datasets/blob/main/docs/format.md)**

Las guías también están en `docs/` del archivo fuente descargable en PyPI. Los enlaces a GitHub requieren acceso al repositorio privado.

MIT · [pshiguihara](https://github.com/pshiguihara)
