Metadata-Version: 2.5
Name: gicc-datasets
Version: 0.1.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

Necesitas un perfil AWS con lectura y escritura limitadas al destino asignado. No necesitas ser administrador ni listar todos los buckets.

```bash
# Sustituye los valores por los que te entregue el responsable de AWS.
gicc-datasets configure --profile gicc --bucket mi-bucket \
  --prefix datasets/mi-equipo/ --region us-east-1

gicc-datasets doctor

# Revisa el contenido antes de subirlo.
gicc-datasets upload ./encuesta --dataset encuesta --version 1.0.0 --dry-run

gicc-datasets upload ./encuesta --dataset encuesta --version 1.0.0

gicc-datasets download encuesta --version 1.0.0 --output ./descargas/encuesta
```

`doctor` comprueba el listado del prefijo; no prueba la escritura ni modifica S3.

## Tres formas de subir

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

Anteponer `gicc-datasets` a cada comando. Una versión publicada no se reemplaza desde el cliente; usa una versión nueva para actualizar datos.

## Python

```python
from gicc_datasets import DatasetClient

client = DatasetClient(
    profile="gicc",
    bucket="mi-bucket",
    prefix="datasets/mi-equipo/",
    region="us-east-1",
)

client.upload("./datos", dataset="muestra", version="1.0.0")
client.download("muestra", version="1.0.0", output="./descargas/muestra")
```

En un servicio con rol AWS, omite `profile` para usar la cadena de credenciales de Boto3.

## 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.
- La configuración guarda destino y nombre de perfil, sin credenciales.
- 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.

**[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)
