gicc-datasets 0.1.0__tar.gz

gicc_datasets-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+build/
+dist/
+.env
+.aws/
+.DS_Store
+plah.html

gicc_datasets-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pshiguihara
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gicc_datasets-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+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)

gicc_datasets-0.1.0/README.md

@@ -0,0 +1,91 @@
+# 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)

gicc_datasets-0.1.0/docs/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+permissions:
+  contents: read
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python: ['3.11', '3.12', '3.13', '3.14']
+        include:
+          - os: macos-latest
+            python: '3.14'
+          - os: windows-latest
+            python: '3.14'
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e '.[dev]'
+      - run: ruff check src tests
+      - run: pytest -q
+      - run: python -m build
+      - run: python -m twine check dist/*

gicc_datasets-0.1.0/docs/development.md

@@ -0,0 +1,17 @@
+# Desarrollo
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e '.[dev]'
+ruff check src tests
+pytest -q
+python -m build
+python -m twine check dist/*
+```
+
+Las pruebas usan S3 simulado; no requieren claves AWS ni acceden a buckets reales.
+Cubren carpetas, ZIP, archivos, multipart, conflictos de publicación, integridad, rutas y errores de acceso.
+Las políticas IAM deben verificarse por separado en el entorno de cada organización.
+
+La plantilla `docs/ci.yml` define comprobaciones para Python 3.11–3.14 en Linux y Python 3.14 en macOS y Windows. Para activarla, muévela a `.github/workflows/ci.yml` con una sesión de GitHub autorizada para gestionar workflows. La plantilla no requiere secretos de PyPI o AWS.

gicc_datasets-0.1.0/docs/format.md

@@ -0,0 +1,28 @@
+# Formato y límites
+
+```text
+<prefix>/<dataset>/versions/<version>/
+├── manifest.json
+└── uploads/<uuid>/files/<ruta-relativa>
+```
+
+El manifiesto usa `schema: 1`, dataset, versión, fecha UTC, UUID de carga, modo de origen, directorios y una lista de archivos con ruta, clave, tamaño y SHA-256. No contiene credenciales ni rutas locales absolutas.
+
+La publicación sube los objetos bajo un UUID independiente y crea el manifiesto al final con `IfNoneMatch="*"`. Dos publicaciones concurrentes no mezclan objetos: solo una puede crear el manifiesto. El cliente solo lista versiones con manifiesto válido. Esto no es una transacción S3; una identidad con permiso de lectura puede acceder a objetos incompletos si conoce sus claves.
+
+Las claves de los archivos quedan restringidas al UUID y prefijo del manifiesto. En descargas se validan rutas y hashes antes de copiar al destino. No se verifica criptográficamente la identidad del publicador: quien pueda modificar tanto el manifiesto como los archivos puede alterar el contenido.
+
+## Límites de la versión inicial
+
+- Python 3.11–3.14; API y CLI con una única dependencia directa: Boto3.
+- Hasta 100000 archivos y directorios y 16 MiB por manifiesto.
+- Nombres portables: se rechazan rutas absolutas, `..`, enlaces, nombres reservados de Windows y colisiones por mayúsculas o normalización Unicode.
+- Se preservan bytes, rutas relativas y directorios vacíos. No se preservan permisos POSIX, atributos extendidos ni enlaces duros como tales.
+- Se usa una copia temporal por archivo durante la subida, y una carpeta temporal con toda la descarga para verificarla. Debe haber espacio local suficiente.
+- Las copias de cada archivo son estables; no constituyen una instantánea atómica de una carpeta que otro proceso esté modificando. Mantén el origen sin cambios.
+- Las transferencias grandes usan multipart y reintentos acotados. La CLI muestra el resultado final; no incluye barra de progreso ni reanudación entre procesos.
+- Una descarga verificada se incorpora archivo por archivo. Un fallo local durante esa incorporación puede dejar una carpeta parcialmente poblada.
+- El listado pagina objetos S3 y valida manifiestos. Su coste crece con el contenido del prefijo; no hay catálogo central ni caché.
+- No hay borrado, sincronización incremental, deduplicación, servidor HTTP ni edición de versiones publicadas.
+
+La versión del paquete Python y la versión de cada dataset son independientes.

gicc_datasets-0.1.0/docs/permissions.md

@@ -0,0 +1,55 @@
+# Permisos AWS
+
+La persona que usa el paquete necesita acceso a un bucket y prefijo asignados. Esta sección está dirigida a quien administra esos permisos.
+
+## Publicador limitado
+
+Adjunta al rol del usuario una política de identidad equivalente a la siguiente, sustituyendo `mi-bucket` y `datasets/mi-equipo/`:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": "s3:ListBucket",
+      "Resource": "arn:aws:s3:::mi-bucket",
+      "Condition": {
+        "StringLike": {
+          "s3:prefix": ["datasets/mi-equipo/", "datasets/mi-equipo/*"]
+        }
+      }
+    },
+    {
+      "Effect": "Allow",
+      "Action": [
+        "s3:GetObject",
+        "s3:PutObject",
+        "s3:AbortMultipartUpload",
+        "s3:ListMultipartUploadParts"
+      ],
+      "Resource": "arn:aws:s3:::mi-bucket/datasets/mi-equipo/*"
+    }
+  ]
+}
+```
+
+Para un lector, conserva `s3:ListBucket` y únicamente `s3:GetObject` en la segunda declaración. No se necesita `s3:ListAllMyBuckets`, `s3:DeleteObject`, administración IAM ni acceso a otros buckets. El cliente no usa `HeadBucket` para diagnosticar un prefijo restringido.
+
+## Configuración de la cuenta
+
+- Usa IAM Identity Center para personas y roles de ejecución para servicios. Cada usuario conserva su propia identidad.
+- Mantén Block Public Access. Utiliza Object Ownership con ACL deshabilitadas; el cliente no envía ACL.
+- Configura el cifrado predeterminado en el bucket. Con SSE-KMS, autoriza la clave además de S3: `kms:Decrypt` para lectura y también `kms:GenerateDataKey` para publicación multipart.
+- Para otra cuenta AWS, configura AssumeRole o las políticas de identidad y bucket necesarias. No compartas claves del propietario.
+- Otras políticas pueden ampliar o restringir el acceso. Un `Deny` explícito, SCP o límite de permisos puede prevalecer sobre esta concesión.
+
+Retira las asignaciones al terminar el acceso y considera las sesiones temporales todavía vigentes. No es posible retirar mediante IAM las copias descargadas.
+
+## Versiones y mantenimiento
+
+El manifiesto se crea con una escritura condicional y el cliente rechaza reemplazos. La política anterior permite `PutObject`: alguien que use otra herramienta podría modificar claves existentes. Para una exigencia de retención, diseña controles adicionales en AWS. El versionado de S3 permite recuperación, pero no bloquea escrituras.
+
+No elimines automáticamente todo `uploads/`: contiene también datos publicados. Una tarea administrativa debe identificar cargas sin referencia en los manifiestos antes de eliminarlas. Puede configurarse por separado el aborto de multipart incompletos.
+
+Referencias: [permisos S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-with-s3-policy-actions.html), [credenciales Boto3](https://docs.aws.amazon.com/boto3/latest/guide/credentials.html), [escrituras condicionales](https://docs.aws.amazon.com/AmazonS3/latest/userguide/conditional-writes.html).

gicc_datasets-0.1.0/docs/tutorial.md

@@ -0,0 +1,161 @@
+# Tutorial
+
+Para usuarios con permisos limitados de lectura y publicación en un bucket y prefijo asignados.
+No se requiere un rol administrador. Sustituye `mi-bucket`, `datasets/mi-equipo/`, región y perfil por tus valores.
+
+## 1. Instalar
+
+En macOS o Linux:
+
+```bash
+python3 -m venv ~/.venvs/gicc-datasets
+source ~/.venvs/gicc-datasets/bin/activate
+pip install gicc-datasets
+gicc-datasets --help
+```
+
+En Windows, crea el entorno con `py -m venv .venv` y actívalo con `.venv\Scripts\Activate.ps1` en PowerShell.
+Activa el entorno en cada nueva terminal. Para actualizar el software, ejecuta `pip install --upgrade gicc-datasets`.
+
+## 2. Iniciar sesión en AWS
+
+Si ya tienes un perfil AWS autorizado, úsalo directamente. Para IAM Identity Center necesitas AWS CLI v2 y los datos de acceso facilitados por tu organización:
+
+```bash
+aws configure sso --profile gicc
+aws sso login --profile gicc
+```
+
+Selecciona el rol limitado para datasets. No copies claves de otra persona. La región de SSO puede diferir de la del bucket. Las credenciales temporales de un rol o las configuradas en `~/.aws` también funcionan mediante Boto3.
+
+## 3. Configurar el destino
+
+```bash
+gicc-datasets configure --profile gicc --bucket mi-bucket \
+  --prefix datasets/mi-equipo/ --region us-east-1
+
+gicc-datasets doctor
+```
+
+Se guarda un archivo sin secretos en `~/.config/gicc-datasets/config.toml`, o bajo `XDG_CONFIG_HOME` cuando está definido. `doctor` comprueba el listado y muestra la identidad cuando utiliza una sesión propia. La escritura aparece como `not_checked`; se comprueba al subir.
+
+Para otra ejecución, las opciones globales se colocan antes del subcomando:
+
+```bash
+gicc-datasets --profile otro-perfil --bucket otro-bucket \
+  --prefix datasets/otro-equipo/ --region us-east-1 list
+```
+
+La configuración explícita tiene prioridad sobre variables de entorno y valores guardados. Variables admitidas: `AWS_PROFILE`, `GICC_DATASETS_BUCKET`, `GICC_DATASETS_PREFIX`, `GICC_DATASETS_REGION`.
+Sin perfil seleccionado, se utiliza la cadena estándar de Boto3. Cambiar el destino no amplía los permisos AWS.
+
+## 4. Subir una carpeta
+
+Origen:
+
+```text
+encuesta/
+├── README.md
+├── raw/hogares.csv
+└── processed/resumen.parquet
+```
+
+```bash
+gicc-datasets upload ./encuesta --dataset encuesta --version 1.0.0 --dry-run
+gicc-datasets upload ./encuesta --dataset encuesta --version 1.0.0
+```
+
+Se conservan las rutas relativas, sin añadir la carpeta exterior `encuesta`. Los directorios vacíos se registran. `--dry-run` muestra archivos, bytes y exclusiones; no llama a S3. En modo ZIP extraído sí usa almacenamiento temporal local.
+
+Se excluyen por defecto `.git`, `.venv`, `.DS_Store`, `__MACOSX`, `.env` y `.aws`, en cualquier nivel. Puedes añadir patrones sobre la ruta relativa:
+
+```bash
+gicc-datasets upload ./encuesta --dataset encuesta --version 1.1.0 \
+  --exclude '*.tmp' --exclude 'borradores/*'
+```
+
+Las exclusiones no detectan todos los secretos: revisa el inventario. Mantén el origen estable durante la carga.
+
+## 5. Subir un ZIP
+
+Conservarlo intacto:
+
+```bash
+gicc-datasets upload ./encuesta.zip --dataset encuesta-zip --version 1.0.0
+```
+
+Extraerlo y publicar sus archivos:
+
+```bash
+gicc-datasets upload ./encuesta.zip --dataset encuesta-extraida --version 1.0.0 --extract-zip
+```
+
+La segunda opción mantiene la estructura interna, incluida cualquier carpeta exterior del ZIP. Rechaza rutas inseguras, enlaces, colisiones y ZIP cifrados. Aplica exclusiones después de validar y extraer.
+
+Límites predeterminados: 100000 entradas, 100 GiB descomprimidos y relación de compresión 1000. Puedes reducirlos o ajustarlos con `--zip-max-entries`, `--zip-max-bytes` y `--zip-max-ratio`. El límite general del manifiesto sigue siendo 100000 entradas y 16 MiB.
+
+## 6. Subir un archivo
+
+```bash
+gicc-datasets upload ./indicadores.parquet --dataset indicadores --version 1.0.0
+```
+
+El formato y contenido se conservan, sin conversión.
+
+## 7. Descargar y actualizar
+
+```bash
+gicc-datasets list
+gicc-datasets versions encuesta
+gicc-datasets info encuesta --version 1.0.0
+gicc-datasets download encuesta --version 1.0.0 --output ./descargas/encuesta-1.0.0
+```
+
+Usa el mismo perfil limitado. Se verifican los archivos en una carpeta temporal antes de trasladarlos al destino. No se sobrescriben archivos por defecto; utiliza una carpeta nueva o `--overwrite` conscientemente. No se eliminan archivos locales adicionales.
+
+Para actualizar el dataset, publica una versión nueva:
+
+```bash
+gicc-datasets upload ./encuesta --dataset encuesta --version 2.0.0
+```
+
+Cada versión es una copia completa. La versión anterior permanece accesible. Especificar la versión permite reproducir una descarga; no existe un alias `latest`.
+
+## 8. Python
+
+```python
+from gicc_datasets import DatasetClient, VersionExistsError, ZipLimits
+
+client = DatasetClient(profile="gicc", bucket="mi-bucket",
+                       prefix="datasets/mi-equipo/", region="us-east-1")
+
+for dataset in client.list_datasets():
+    print(dataset.id, dataset.versions)
+
+try:
+    release = client.upload("./datos.zip", dataset="muestra", version="1.0.0",
+                            extract_zip=True, zip_limits=ZipLimits(max_bytes=1024**3))
+    print(release.files, release.bytes)
+except VersionExistsError:
+    print("La versión ya está publicada.")
+
+manifest = client.info("muestra", "1.0.0")
+client.download("muestra", version="1.0.0", output="./descargas/muestra")
+```
+
+`upload(..., dry_run=True)` devuelve el plan sin utilizar AWS. `upload` y `download` devuelven `Release`. `info` devuelve el manifiesto como diccionario. `versions` devuelve una lista de cadenas ordenadas lexicográficamente.
+
+## Errores
+
+| Código | Situación | Acción |
+| --- | --- | --- |
+| 2 | Configuración o argumentos | Revisa bucket, prefijo y opciones. |
+| 3 | Identidad o acceso | Revisa el perfil, renueva SSO o consulta al responsable. |
+| 4 | Objeto o bucket inexistente | Revisa dataset y versión. |
+| 5 | Versión existente o concurrente | Publica una versión nueva. |
+| 6 | Integridad, rutas o ZIP | Revisa el origen y el destino. |
+| 7 | Transferencia o disco | Revisa conexión, permisos de transferencia y espacio. |
+| 130 | Cancelación | Vuelve a iniciar la operación cuando corresponda. |
+
+`--json` genera JSON para automatización; los errores se escriben en stderr. Un fallo de transferencia multipart puede informar código 7 incluso cuando su causa sea un permiso AWS.
+Una carga fallida no publica un manifiesto completo, pero puede dejar objetos huérfanos. No se reanudan transferencias entre ejecuciones. La limpieza corresponde al responsable del bucket.

gicc_datasets-0.1.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gicc-datasets"
+version = "0.1.0"
+description = "Versioned datasets in Amazon S3, using your existing AWS permissions."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{name = "pshiguihara"}]
+keywords = ["datasets", "s3", "aws", "research"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Operating System :: OS Independent",
+]
+dependencies = ["boto3>=1.35.99,<2"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8,<10", "moto[s3]>=5,<6", "ruff>=0.11", "build>=1.2", "twine>=6"]
+
+[project.urls]
+Homepage = "https://github.com/pshiguihara/gicc-datasets"
+Documentation = "https://github.com/pshiguihara/gicc-datasets/blob/main/docs/tutorial.md"
+Issues = "https://github.com/pshiguihara/gicc-datasets/issues"
+
+[project.scripts]
+gicc-datasets = "gicc_datasets.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/gicc_datasets"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src", "/tests", "/docs", "/README.md", "/LICENSE", "/pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

gicc_datasets-0.1.0/src/gicc_datasets/__init__.py

@@ -0,0 +1,30 @@
+"""Versioned datasets in Amazon S3."""
+
+__version__ = "0.1.0"
+
+from .client import DatasetClient, DatasetSummary, Release
+from .errors import (
+    AccessDeniedError,
+    ConfigurationError,
+    DatasetError,
+    IntegrityError,
+    NotFoundError,
+    TransferError,
+    VersionExistsError,
+)
+from .sources import ZipLimits
+
+__all__ = [
+    "DatasetClient",
+    "DatasetSummary",
+    "Release",
+    "ZipLimits",
+    "DatasetError",
+    "AccessDeniedError",
+    "ConfigurationError",
+    "IntegrityError",
+    "NotFoundError",
+    "TransferError",
+    "VersionExistsError",
+    "__version__",
+]

gicc_datasets-0.1.0/src/gicc_datasets/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())