arcgisx-cli

arcgisx-cli es un MVP de un CLI llamado arcgisx para publicar un CSV con coordenadas como Hosted Feature Layer en ArcGIS Online o ArcGIS Enterprise usando ArcGIS API for Python.

El comando principal es publish-csv. Valida el CSV, autentica contra ArcGIS, sube el CSV como item, publica un Hosted Feature Layer, verifica que exista al menos una layer, consulta el conteo de entidades y devuelve un resultado estructurado.

Qué Hace

• Publica un CSV con columnas de latitud y longitud como Hosted Feature Layer.
• Inspecciona items por ID con arcgisx item describe.
• Permite borrado seguro por ID con arcgisx item delete, siempre en dry-run salvo --yes.
• Valida existencia, extensión, lectura, columnas, valores numéricos y rangos de coordenadas.
• Usa ARCGIS_URL, ARCGIS_USERNAME y ARCGIS_PASSWORD desde entorno o .env.
• Si faltan credenciales, puede pedirlas por terminal y guardarlas en el almacén seguro del sistema con keyring.
• Soporta salida humana con Rich o JSON con --json.
• Permite --sharing private|org|public; el valor por defecto es private.

Qué No Hace Todavía

• No usa OAuth.
• No usa ArcPy.
• No implementa overwrite.
• No crea webmaps.
• No crea ni gestiona grupos.
• No incluye integración MCP.
• No borra items desde el comando normal; la limpieza solo existe en tests de integración.
• No implementa borrado masivo ni borrado por búsqueda.

Instalación

Requisitos:

• Python 3.11 o superior
• Acceso a ArcGIS Online o ArcGIS Enterprise para publicación real

Instalación editable con dependencias de desarrollo:

python -m pip install -e ".[dev]"

Comprobar el CLI:

arcgisx --help
arcgisx publish-csv --help

Configuración

Puedes usar variables de entorno:

$env:ARCGIS_URL="https://www.arcgis.com"
$env:ARCGIS_USERNAME="your_username"
$env:ARCGIS_PASSWORD="your_password"

O copiar .env.example a .env:

Copy-Item .env.example .env
notepad .env

Contenido esperado:

ARCGIS_URL=https://www.arcgis.com
ARCGIS_USERNAME=your_username
ARCGIS_PASSWORD=your_password

.env está excluido de Git. .env.example sí debe versionarse.

Si no hay credenciales en entorno, .env ni keyring, el CLI las pedirá por terminal. La contraseña no se imprime y no se guarda en el repositorio; se almacena mediante keyring en el almacén seguro del sistema.

Uso en PowerShell

Advertencia: este comando crea contenido real en ArcGIS.

arcgisx publish-csv .\samples\points.csv `
  --title "Ciudades de ejemplo" `
  --lat latitude `
  --lon longitude `
  --tags "demo,cities" `
  --description "CSV de ejemplo con ciudades españolas" `
  --sharing private `
  --json

Usa --sharing private para pruebas. public nunca es el valor por defecto y solo se aplica si lo indicas explícitamente.

Si quieres que el comando intente borrar items creados cuando falle después de empezar la publicación:

arcgisx publish-csv .\samples\points.csv `
  --title "Ciudades de ejemplo" `
  --lat latitude `
  --lon longitude `
  --sharing private `
  --cleanup-on-failure

Sin --cleanup-on-failure, el comando no borra nada si una publicación parcial falla.

Gestión de Items

Inspeccionar un item:

arcgisx item describe "ITEM_ID"

Inspeccionar con JSON:

arcgisx item describe "ITEM_ID" --json

Borrado seguro en dry-run, no borra nada:

arcgisx item delete "ITEM_ID"

Borrado real:

arcgisx item delete "ITEM_ID" --yes

Advertencia: arcgisx item delete ITEM_ID --yes borra contenido real en ArcGIS. No hay borrado masivo ni borrado por búsqueda; solo borra el ID explícito que indiques.

Ejemplo JSON

Salida correcta:

{
  "ok": true,
  "csv_item_id": "abc123",
  "feature_layer_item_id": "def456",
  "feature_layer_url": "https://services.arcgis.com/.../FeatureServer/0",
  "title": "Ciudades de ejemplo",
  "feature_count": 3,
  "sharing": "private",
  "warnings": []
}

Salida de error con --json:

{
  "ok": false,
  "error": {
    "type": "CsvValidationError",
    "message": "Latitude column not found: latitude"
  }
}

Salida de item delete en dry-run:

{
  "ok": true,
  "deleted": false,
  "dry_run": true,
  "item": {
    "ok": true,
    "id": "abc123",
    "title": "Ciudades de ejemplo",
    "type": "Feature Service",
    "owner": "your_username",
    "url": "https://services.arcgis.com/.../FeatureServer",
    "created": 1710000000000,
    "modified": 1710000100000,
    "access": "private"
  },
  "warnings": []
}

Con --json, el comando imprime JSON parseable en stdout. Los prompts interactivos, si hacen falta, se muestran por stderr.

Tests Unitarios

Los tests unitarios están mockeados y no se conectan a ArcGIS.

pytest

pytest normal no publica contenido real. El test de integración aparece como skipped si no está activado.

Tests de Integración ArcGIS

Advertencia: estos tests crean contenido real en ArcGIS Online o ArcGIS Enterprise usando samples/points.csv.

Para ejecutarlos:

$env:RUN_ARCGIS_INTEGRATION_TESTS="true"
$env:CLEANUP_ARCGIS_TEST_ITEMS="true"
$env:ARCGIS_URL="https://www.arcgis.com"
$env:ARCGIS_USERNAME="your_username"
$env:ARCGIS_PASSWORD="your_password"
pytest -m integration

El test crea un título único con formato arcgisx-mvp-test-YYYYMMDD-HHMMSS, publica el Hosted Feature Layer como privado y verifica IDs, URL, conteo y sharing.

Si CLEANUP_ARCGIS_TEST_ITEMS=true, el test intenta borrar el CSV item y el Hosted Feature Layer al terminar. Si la limpieza falla, imprimirá los IDs.

Borrado Manual de Residuos

Si un test de integración deja residuos, busca en ArcGIS los items cuyo título empiece por:

arcgisx-mvp-test-

También puedes borrar manualmente usando los IDs impresos por el test:

python -c "from arcgisx.config import load_config; from arcgisx.auth import connect; gis=connect(load_config()); item=gis.content.get('ITEM_ID'); print(item.delete() if item else 'not found')"

Borra tanto el CSV item como el Hosted Feature Layer item si ambos existen.

Seguridad

• No pegues contraseñas en tickets, logs o commits.
• No subas .env; está en .gitignore.
• .env.example no debe contener credenciales reales.
• La contraseña se modela con SecretStr y no aparece en repr(config).
• Los errores de autenticación enmascaran la contraseña si la librería la incluyera en una excepción.
• Revisa siempre --sharing antes de publicar.

Lint

ruff check .