paramsx 2.2.0__tar.gz → 2.2.2__tar.gz

{paramsx-2.2.0 → paramsx-2.2.2}/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 2.2.2
+
+Un renombrado de la configuración, sin cambios de comportamiento. **Los nombres antiguos
+se siguen aceptando**, así que no tienes que tocar tu fichero para actualizar.
+
+### Cambiado
+
+- **Un solo nombre para el concepto: `perfiles` / `perfil`.** El mismo concepto se llamaba de tres formas distintas: el diccionario era `naming`, la clave de cada entrada de `parameter_list` era `convencion` y la documentación decía "perfil". Explicárselo a alguien obligaba a traducir dos veces. Ahora:
+
+  | Antes | Ahora |
+  |---|---|
+  | `naming = {...}` | `perfiles = {...}` |
+  | `{"path": "/rds", "convencion": "min"}` | `{"path": "/rds", "perfil": "min"}` |
+  | `convencion_nuevos = "min"` | `perfil_nuevos = "min"` |
+
+- `paramsx configure` te dice qué nombres antiguos usas y cómo se llaman ahora, incluidas las entradas de `parameter_list`. Los viejos (`naming`, `convencion`, `convencion_nuevos` y el `abac` de la 2.0) se traducen al cargar, así que dentro del programa solo existe el nombre nuevo.
+
+## 2.2.1
+
+Solo comandos de terminal y documentación: no cambia nada de la lectura, la carga ni la
+construcción de rutas. Si ya tienes la 2.2.0 funcionando, actualizar no te obliga a tocar
+tu configuración.
+
+### Añadido
+
+- **`paramsx --version`** (y `-v`), y la versión también en la cabecera de `paramsx --help`. La versión pasa a vivir en `paramsx/__init__.py` y `setup.py` la lee de ahí, para que el paquete y el comando no puedan decir cosas distintas.
+- **`paramsx configure` sobre una configuración que ya existe ya no se queda en "no se sobrescribirá".** Sigue sin tocar el fichero, pero ahora te dice qué opciones nuevas no tienes y con qué valor por defecto se rellenan, si usas el nombre antiguo `abac`, y si la configuración es válida.
+- **`paramsx configure --ejemplo`**: además de lo anterior, deja la plantilla de esta versión en `~/.xsoft/paramsx_config.ejemplo.py`, al lado de la tuya, para comparar. ParamsX no la lee: es solo referencia. Escribir en tu configuración es lo único que no se puede deshacer, así que va en un comando aparte y en otro fichero.
+- Mensaje de primer arranque más claro cuando todavía no hay configuración, explicando qué hace `paramsx configure` y dónde va el fichero.
+
+### Cambiado
+
+- **`paramsx --help` al día.** La opción 2 ya explica que eliges entre los ficheros que tengas en el directorio; el ejemplo de `mixto` usa el entorno en mayúscula como el resto de la documentación; `fichero_por_ruta` enseña el nombre real (`parameters_dev__API_STA__max.py`); y se documentan `profile_name`, `region_name` y `entornos`, que no aparecían aunque son obligatorios.
+- **El README muestra el contenido literal de `paramsx_config.py`**, con sus comentarios y tablas, en vez de una versión resumida: es exactamente lo que te crea `paramsx configure`, así que no pueden desincronizarse. Y una tabla con todos los comandos disponibles.
+
 ## 2.2.0
 
 ### Añadido

{paramsx-2.2.0/paramsx.egg-info → paramsx-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramsx
-Version: 2.2.0
+Version: 2.2.2
 Summary: Librería para gestionar y respaldar parámetros de AWS SSM de manera sencilla y eficiente.
 Home-page: https://github.com/pistatxos/paramsx
 Author: Mariox
@@ -24,7 +24,7 @@ ParamsX es una herramienta diseñada para gestionar y organizar parámetros de A
 
 ## ⚠ Breaking change en la versión 2.0.0
 
-Si vienes de la 1.x tienes que **actualizar a mano tu `~/.xsoft/paramsx_config.py`**: `parameter_list` ya no es una lista de strings, ahora cada entrada es un diccionario con su convención de naming. La versión antigua **no es compatible** y ParamsX se niega a arrancar mostrando cómo migrarla. Detalle completo en el [CHANGELOG](CHANGELOG.md).
+Si vienes de la 1.x tienes que **actualizar a mano tu `~/.xsoft/paramsx_config.py`**: `parameter_list` ya no es una lista de strings, ahora cada entrada es un diccionario que declara su perfil. La versión antigua **no es compatible** y ParamsX se niega a arrancar mostrando cómo migrarla. Detalle completo en el [CHANGELOG](CHANGELOG.md).
 
 ### Estructura Recomendada
 La convención de naming es de 5 niveles, donde los últimos segmentos son opcionales según el caso:
@@ -97,10 +97,10 @@ Esto te permitirá mantener respaldos seguros o realizar migraciones/reorganizac
 
 4. Crear nuevo parámetro
 - Crea un parámetro desde cero sin salir de la herramienta. Te pedirá, en este orden:
-    - La ruta **sin el entorno**, igual que la declaras en `parameter_list`: el perfil de naming se encarga de colocarlo. Verás en pantalla la ruta resultante en AWS antes de seguir.
+    - La ruta **sin el entorno**, igual que la declaras en `parameter_list`: el perfil se encarga de colocarlo. Verás en pantalla la ruta resultante en AWS antes de seguir.
     - El valor: texto plano o JSON en una línea (por ejemplo `{"host": "x", "user": "y", "pass": "z"}`), que se valida antes de continuar.
     - Las tags obligatorias, si tienes `tags_activas = True`.
-- El perfil que se usa es el que declares en `convencion_nuevos`. Si tu perfil es de tipo `mixto`, escribe el `*` en la ruta para indicar dónde va el entorno.
+- El perfil que se usa es el que declares en `perfil_nuevos`. Si tu perfil es de tipo `mixto`, escribe el `*` en la ruta para indicar dónde va el entorno.
 - Antes de subirlo verás una pantalla de confirmación con la ruta, el valor y las tags. El parámetro se crea con `Overwrite=False`, así que nunca machaca uno existente.
 - Tras crearlo aparecerá la próxima vez que leas la ruta correspondiente de tu `parameter_list`.
 
@@ -128,12 +128,56 @@ Este comando creará automáticamente una carpeta de configuración en tu direct
 
 Dentro de esta carpeta, encontrarás el archivo paramsx_config.py. Este archivo contiene la configuración inicial que debes ajustar según tu entorno.
 
+Si ya tenías configuración de una versión anterior, `paramsx configure` **no la sobrescribe**: te dice qué opciones nuevas no tienes y con qué valor por defecto se están rellenando, y si la configuración es válida. Con `paramsx configure --ejemplo` además deja la plantilla de esta versión en `paramsx_config.ejemplo.py`, al lado de la tuya, para que compares sin tocar nada.
+
 Ejemplo del contenido de paramsx_config.py:
 
 ```python
 ## Configuraciones ParamsX
 
-naming = {
+# --- Perfiles -------------------------------------------------------------
+# Un perfil dice CÓMO se construye la ruta real en AWS a partir de la ruta que declaras
+# en 'parameter_list' y del entorno que eliges en el menú. Los nombres son tuyos: define
+# solo los que uses y llámalos como quieras. Un perfil tiene tres campos:
+#
+#   campo             | valores                                  | qué decide
+#   ------------------+------------------------------------------+---------------------------
+#   posicion_entorno  | inicio | final | mixto | ninguno          | dónde va el entorno
+#   case_entorno      | lower | upper | capitalize                | cómo se escribe el entorno
+#   case_ruta         | lower | upper | capitalize | ninguno      | case de la ruta AL CREAR
+#
+# posicion_entorno -> dónde se coloca el entorno (ejemplos con el entorno 'dev'):
+#
+#   valor    | ruta declarada  | ruta real en AWS
+#   ---------+-----------------+--------------------------------------------------------
+#   inicio   | /rds            | /dev/rds
+#   final    | /API/STA        | /API/STA/DEV
+#   mixto    | /API/*/STA      | /API/DEV/STA    el '*' marca el sitio; uno y como segmento
+#   ninguno  | /api/sta/auth   | /api/sta/auth   una cuenta AWS por entorno; case_entorno da igual
+#
+# case_entorno -> cómo se escribe ese entorno en la ruta:
+#
+#   valor       | 'dev' se escribe | ruta real de /API/STA con posicion_entorno=final
+#   ------------+------------------+------------------------------------------------
+#   lower       | dev              | /API/STA/dev
+#   upper       | DEV              | /API/STA/DEV
+#   capitalize  | Dev              | /API/STA/Dev
+#
+# case_ruta -> a qué case se fuerza la ruta que TÚ escribes al CREAR un parámetro
+# (opción 4 del menú). No afecta a leer ni a editar: lo que ya existe en AWS se
+# respeta siempre tal cual esté.
+#
+#   valor       | si escribes /API/MULTIAPI/Token, se crea
+#   ------------+-----------------------------------------
+#   lower       | /api/multiapi/token
+#   upper       | /API/MULTIAPI/TOKEN
+#   capitalize  | /Api/Multiapi/Token
+#   ninguno     | /API/MULTIAPI/Token
+#
+# Combina los tres campos como necesites: no hay una lista cerrada de perfiles. En el
+# README tienes más ejemplos.
+
+perfiles = {
     "min": {"posicion_entorno": "inicio", "case_entorno": "lower", "case_ruta": "lower"},
     "max": {"posicion_entorno": "final", "case_entorno": "upper", "case_ruta": "ninguno"},
     "mixto_max": {"posicion_entorno": "mixto", "case_entorno": "upper", "case_ruta": "ninguno"},
@@ -146,101 +190,71 @@ configuraciones = {
     "region_name": "eu-south-2",         # Cambiar por tu región de AWS
     "entornos": ['dev', 'pre', 'prod'],  # SIEMPRE en minúscula, es la lista canónica única
     "parameter_list": [
-        {"path": "/common", "convencion": "min"},      # -> /dev/common
-        {"path": "/rds", "convencion": "min"},         # -> /dev/rds
-        {"path": "/EMAIL", "convencion": "max"},       # -> /EMAIL/DEV
-        {"path": "/API/STA", "convencion": "max"},     # -> /API/STA/DEV
-        {"path": "/API/MULTIAPI/*/stan_ai", "convencion": "mixto_max"},  # -> /API/MULTIAPI/DEV/stan_ai
+        {"path": "/common", "perfil": "min"},      # -> /dev/common
+        {"path": "/rds", "perfil": "min"},         # -> /dev/rds
+        {"path": "/EMAIL", "perfil": "max"},       # -> /EMAIL/DEV
+        {"path": "/API/STA", "perfil": "max"},     # -> /API/STA/DEV
+        # Con 'mixto' acotas por debajo del entorno: esto lee solo stan_ai, en vez de
+        # todo lo que cuelga de /API/MULTIAPI/DEV
+        {"path": "/API/MULTIAPI/*/stan_ai", "perfil": "mixto_max"},  # -> /API/MULTIAPI/DEV/stan_ai
     ]
 }
 
-convencion_nuevos = "min"
+# Perfil que se usa al crear un parámetro nuevo (opción 4 del menú).
+# Si no lo defines, se usa el primero de 'perfiles'.
+perfil_nuevos = "min"
 
+# ¿El nombre del fichero exportado incluye la ruta leída?
+#   False -> parameters_dev.py            (comportamiento de siempre)
+#   True  -> parameters_dev__API_STA__max.py  (uno por entrada y entorno: lleva el
+#            entorno, la ruta y el perfil, porque dos entradas pueden compartir ruta)
+# Ponlo en True si sueles leer varias rutas del mismo entorno y no quieres que la
+# segunda lectura te machaque el fichero de la primera.
 fichero_por_ruta = False
 
 
 ## Configuraciones Tags
 
+# Gestionar las tags de los parámetros: leerlas de AWS, exponerlas en el fichero
+# exportado para editarlas y validar las obligatorias al cargar.
+#   True  -> las tags viajan en el fichero y se validan.
+#   False -> no aparecen tags en el fichero y no se valida nada.
+# En cuentas cuyo control de acceso va por tags (ABAC vía IAM) esto debe estar en True.
 tags_activas = True
 
+# Solo aplica si tags_activas = True.
+#   False -> validación bloqueante: si a un parámetro le falta alguna tag obligatoria
+#            no se sube (ni su valor ni sus tags).
+#   True  -> se permiten vacías: el parámetro se sube igualmente y las tags sin valor
+#            simplemente NO se crean en AWS (no se suben como etiquetas vacías).
 obligatorias_vacias = False
 
+# Tags que se exigen en cada parámetro cuando tags_activas = True. La lista es libre:
+# estas 8 son las que sostienen el control de acceso ABAC vía IAM de nuestra cuenta.
 tags_obligatorias = [
-    "Application", "Environment", "Owner", "Project",
-    "Product", "Service", "Component", "ManagedBy",
+    "Application",
+    "Environment",
+    "Owner",
+    "Project",
+    "Product",
+    "Service",
+    "Component",
+    "ManagedBy",
 ]
 ```
 Nota: Si el archivo paramsx_config.py ya existe, no será sobrescrito durante la instalación para proteger las configuraciones personalizadas.
 
-### Los perfiles de naming
-
-Cada organización nombra sus parámetros a su manera, así que ParamsX no impone ninguna convención: **tú defines los perfiles que uses en el diccionario `naming` y les pones el nombre que quieras**. Cada entrada de `parameter_list` declara con qué perfil se construye su ruta completa.
-
-Un perfil tiene tres campos:
-
-| Campo | Valores | Qué decide |
-|---|---|---|
-| `posicion_entorno` | `inicio` \| `final` \| `mixto` \| `ninguno` | Dónde va el entorno dentro de la ruta. |
-| `case_entorno` | `lower` \| `upper` \| `capitalize` | Cómo se escribe el entorno. |
-| `case_ruta` | `lower` \| `upper` \| `capitalize` \| `ninguno` | Case de la ruta al crear parámetros. |
-
-Y en detalle:
-
-**`posicion_entorno`** — dónde se coloca el entorno, con el entorno `dev`:
+### Los perfiles
 
-| Valor | Ruta declarada | Ruta real en AWS | |
-|---|---|---|---|
-| `inicio` | `/rds` | `/dev/rds` | |
-| `final` | `/API/STA` | `/API/STA/DEV` | |
-| `mixto` | `/API/*/STA` | `/API/DEV/STA` | el `*` marca el sitio |
-| `ninguno` | `/api/sta/auth` | `/api/sta/auth` | una cuenta AWS por entorno |
-
-**`case_entorno`** — cómo se escribe ese entorno en la ruta:
-
-| Valor | `dev` se escribe | `/API/STA` con `posicion_entorno: final` |
-|---|---|---|
-| `lower` | `dev` | `/API/STA/dev` |
-| `upper` | `DEV` | `/API/STA/DEV` |
-| `capitalize` | `Dev` | `/API/STA/Dev` |
-
-**`case_ruta`** — a qué case se fuerza la ruta que escribes al **crear** un parámetro (opción 4). No afecta a leer ni a editar: lo que ya existe en AWS se respeta siempre tal cual esté.
-
-| Valor | Si escribes `/API/MULTIAPI/Token`, se crea |
-|---|---|
-| `lower` | `/api/multiapi/token` |
-| `upper` | `/API/MULTIAPI/TOKEN` |
-| `capitalize` | `/Api/Multiapi/Token` |
-| `ninguno` | `/API/MULTIAPI/Token` |
+Cada organización nombra sus parámetros a su manera, así que ParamsX no impone ninguna convención: **tú defines los perfiles que uses en el diccionario `perfiles` y les pones el nombre que quieras**. Cada entrada de `parameter_list` declara con qué perfil se construye su ruta completa, con la clave `perfil`. Los tres campos de un perfil y sus valores están explicados en el propio fichero de configuración, ahí arriba.
 
 **No hay una lista cerrada de perfiles.** Los tres campos se combinan libremente, así que la plantilla no intenta traértelos todos: define los dos o tres que use tu organización y olvídate del resto. `min` y `max` vienen predefinidos porque son los que ParamsX traía antes de que los perfiles fueran configurables.
 
-**`mixto` y el marcador `*`.** Cuando el entorno no va ni al principio ni al final, se marca su sitio con un `*` en la propia ruta. Es útil para acotar la lectura a un solo subárbol: con `/API/MULTIAPI/*/stan_ai` lees únicamente `/API/MULTIAPI/DEV/stan_ai`, en vez de todo lo que cuelga de `/API/MULTIAPI/DEV`. El `*` debe ser un segmento entero y aparecer **exactamente una vez**, y solo se admite en perfiles `mixto`: si el perfil y la ruta no cuentan la misma historia, ParamsX te lo dice al arrancar en vez de leer una ruta inexistente y devolverte una lista vacía.
+**Para qué sirve el `*`.** Además de colocar el entorno donde quieras, acota la lectura a un solo subárbol: con `/API/MULTIAPI/*/stan_ai` lees únicamente `/API/MULTIAPI/DEV/stan_ai`, en vez de todo lo que cuelga de `/API/MULTIAPI/DEV`. Debe ser un segmento entero, aparecer **exactamente una vez** y solo se admite en perfiles `mixto`: si el perfil y la ruta no cuentan la misma historia, ParamsX te lo dice al arrancar en vez de leer una ruta inexistente y devolverte una lista vacía.
 
-**`ninguno` y las cuentas sin entorno en la ruta.** Hay organizaciones que separan los entornos por cuenta de AWS y no meten `dev`/`prod` en el path. Con `posicion_entorno: "ninguno"` la ruta se usa tal cual; el selector de entorno del menú sigue existiendo, pero no toca la ruta. En este perfil el `case_entorno` es irrelevante, porque no se escribe ningún entorno.
+**Los entornos.** Ya no existe la lista `entornos_old`: el entorno sale siempre de la lista canónica `entornos` (en minúscula), aplicándole el `case_entorno` del perfil. Si en tus rutas se llama `staging` en vez de `pre`, ponlo así en `entornos`.
 
-Ya **no existe** la lista `entornos_old`: el entorno se escribe siempre a partir de la lista canónica `entornos` (en minúscula), aplicándole el `case_entorno` del perfil. Si en tus rutas el entorno se llama `staging` en vez de `pre`, ponlo así en `entornos`.
-
-Ejemplo completo de una `parameter_list` real, mezclando perfiles:
-
-```python
-    "parameter_list": [
-        {"path": "/common", "convencion": "min"},
-        {"path": "/rds", "convencion": "min"},
-        {"path": "/api", "convencion": "min"},
-        {"path": "/INFRA", "convencion": "max"},
-        {"path": "/API/STA", "convencion": "max"},
-        {"path": "/API/p15", "convencion": "max"},
-        {"path": "/API/MULTIAPI", "convencion": "max"},
-        {"path": "/APP/Alertas", "convencion": "max"},
-        {"path": "/BUCKETS", "convencion": "max"},
-        {"path": "/EMAIL", "convencion": "max"},
-        {"path": "/INFERENCIAS/TASA_DMI", "convencion": "max"},
-        {"path": "/CEE/CEXGEN", "convencion": "max"},
-        {"path": "/API/MULTIAPI/*/stan_ai", "convencion": "mixto_max"},
-    ]
-```
-
-Sobre mayúsculas y minúsculas: ParamsX **no renombra ni fuerza el case de los parámetros que ya existen**, los lee y edita tal cual estén. El `case_ruta` del perfil solo entra en juego al crear parámetros nuevos.
+Y ParamsX **no renombra ni fuerza el case de los parámetros que ya existen**: los lee y edita tal cual estén. El `case_ruta` del perfil solo entra en juego al crear parámetros nuevos.
 
 ### Un fichero por ruta: `fichero_por_ruta`
 
@@ -252,15 +266,15 @@ En el nombre van el entorno, la ruta y el perfil, porque dos entradas pueden com
 
 | Entrada | Fichero |
 |---|---|
-| `{"path": "/API/STA", "convencion": "max"}` | `parameters_dev__API_STA__max.py` |
-| `{"path": "/API/*/STA", "convencion": "mixto_max"}` | `parameters_dev__API_env_STA__mixto_max.py` |
+| `{"path": "/API/STA", "perfil": "max"}` | `parameters_dev__API_STA__max.py` |
+| `{"path": "/API/*/STA", "perfil": "mixto_max"}` | `parameters_dev__API_env_STA__mixto_max.py` |
 
 ### Cómo acotar tu parameter_list (recomendación)
 
 `parameter_list` es solo tu vista de trabajo: **la seguridad real la impone IAM, no este fichero**. La recomendación de uso es:
 
-- **Admins**: pueden configurar rutas raíz amplias, por ejemplo `{"path": "/rds", "convencion": "min"}` → `/dev/rds`.
-- **Usuarios normales**: conviene acotar la ruta a lo que su rol IAM tiene realmente autorizado, por ejemplo `{"path": "/rds/cee-dev/api", "convencion": "min"}` → `/dev/rds/cee-dev/api`.
+- **Admins**: pueden configurar rutas raíz amplias, por ejemplo `{"path": "/rds", "perfil": "min"}` → `/dev/rds`.
+- **Usuarios normales**: conviene acotar la ruta a lo que su rol IAM tiene realmente autorizado, por ejemplo `{"path": "/rds/cee-dev/api", "perfil": "min"}` → `/dev/rds/cee-dev/api`.
 
 Si configuras una ruta más amplia que tus permisos, no pasa nada grave: ParamsX te avisará con un mensaje claro de acceso denegado en vez de una traza de boto3. Pero afinar la ruta te ahorra el error.
 
@@ -342,7 +356,17 @@ En algunos sistemas (especialmente en entornos corporativos como Windows), el PA
 ```source ~/.zshrc    # Para zsh```
 
 Una vez instalado, verifica que el comando paramsx esté disponible ejecutando:
-```paramsx --help```
+```paramsx --version```
+
+Comandos disponibles:
+
+| Comando | Qué hace |
+|---|---|
+| `paramsx` | Abre el menú interactivo (necesita configuración). |
+| `paramsx configure` | Crea la configuración la primera vez; si ya existe, la revisa sin tocarla. |
+| `paramsx configure --ejemplo` | Además deja la plantilla de esta versión al lado, para comparar. |
+| `paramsx --version` | Versión instalada. |
+| `paramsx --help` | Ayuda, con el resumen de todas las opciones de configuración. |
 
 
 ## Modo de empleo
@@ -359,7 +383,7 @@ El programa mostrará un menú donde Podrás:
 - Crear un parámetro nuevo.
 
 ### Leer Parámetros:
-1. Selecciona la opción "Leer parámetros" en el menú. La lista muestra cada ruta con su perfil de naming, por ejemplo `/rds  [min]` o `/API/STA  [max]`.
+1. Selecciona la opción "Leer parámetros" en el menú. La lista muestra cada ruta con su perfil, por ejemplo `/rds  [min]` o `/API/STA  [max]`.
 2. Elige el prefijo y el entorno que deseas consultar.
 3. Los parámetros serán descargados y guardados en archivos como:
     - parameters_dev.py
@@ -380,7 +404,7 @@ El programa mostrará un menú donde Podrás:
 
 ### Crear un parámetro nuevo:
 1. Selecciona la opción "Crear nuevo parámetro" y elige el entorno.
-2. Escribe la ruta **sin el entorno**, como en tu `parameter_list`: ParamsX le aplica el perfil de `convencion_nuevos` y te enseña la ruta resultante en AWS para que la confirmes.
+2. Escribe la ruta **sin el entorno**, como en tu `parameter_list`: ParamsX le aplica el perfil de `perfil_nuevos` y te enseña la ruta resultante en AWS para que la confirmes.
 3. Escribe el valor: texto plano o JSON en una línea.
 4. Rellena las tags obligatorias (si `tags_activas = True`). `Environment` viene precargada con el entorno elegido. Con `obligatorias_vacias = True` puedes dejar alguna en blanco pulsando Enter: esas no se crearán en AWS.
 5. Confirma en la pantalla de resumen. Si es un parámetro de RDS y falta su contraparte (común o privado), verás el aviso de correlación de naming ahí mismo.

{paramsx-2.2.0 → paramsx-2.2.2}/README.md

@@ -4,7 +4,7 @@ ParamsX es una herramienta diseñada para gestionar y organizar parámetros de A
 
 ## ⚠ Breaking change en la versión 2.0.0
 
-Si vienes de la 1.x tienes que **actualizar a mano tu `~/.xsoft/paramsx_config.py`**: `parameter_list` ya no es una lista de strings, ahora cada entrada es un diccionario con su convención de naming. La versión antigua **no es compatible** y ParamsX se niega a arrancar mostrando cómo migrarla. Detalle completo en el [CHANGELOG](CHANGELOG.md).
+Si vienes de la 1.x tienes que **actualizar a mano tu `~/.xsoft/paramsx_config.py`**: `parameter_list` ya no es una lista de strings, ahora cada entrada es un diccionario que declara su perfil. La versión antigua **no es compatible** y ParamsX se niega a arrancar mostrando cómo migrarla. Detalle completo en el [CHANGELOG](CHANGELOG.md).
 
 ### Estructura Recomendada
 La convención de naming es de 5 niveles, donde los últimos segmentos son opcionales según el caso:
@@ -77,10 +77,10 @@ Esto te permitirá mantener respaldos seguros o realizar migraciones/reorganizac
 
 4. Crear nuevo parámetro
 - Crea un parámetro desde cero sin salir de la herramienta. Te pedirá, en este orden:
-    - La ruta **sin el entorno**, igual que la declaras en `parameter_list`: el perfil de naming se encarga de colocarlo. Verás en pantalla la ruta resultante en AWS antes de seguir.
+    - La ruta **sin el entorno**, igual que la declaras en `parameter_list`: el perfil se encarga de colocarlo. Verás en pantalla la ruta resultante en AWS antes de seguir.
     - El valor: texto plano o JSON en una línea (por ejemplo `{"host": "x", "user": "y", "pass": "z"}`), que se valida antes de continuar.
     - Las tags obligatorias, si tienes `tags_activas = True`.
-- El perfil que se usa es el que declares en `convencion_nuevos`. Si tu perfil es de tipo `mixto`, escribe el `*` en la ruta para indicar dónde va el entorno.
+- El perfil que se usa es el que declares en `perfil_nuevos`. Si tu perfil es de tipo `mixto`, escribe el `*` en la ruta para indicar dónde va el entorno.
 - Antes de subirlo verás una pantalla de confirmación con la ruta, el valor y las tags. El parámetro se crea con `Overwrite=False`, así que nunca machaca uno existente.
 - Tras crearlo aparecerá la próxima vez que leas la ruta correspondiente de tu `parameter_list`.
 
@@ -108,12 +108,56 @@ Este comando creará automáticamente una carpeta de configuración en tu direct
 
 Dentro de esta carpeta, encontrarás el archivo paramsx_config.py. Este archivo contiene la configuración inicial que debes ajustar según tu entorno.
 
+Si ya tenías configuración de una versión anterior, `paramsx configure` **no la sobrescribe**: te dice qué opciones nuevas no tienes y con qué valor por defecto se están rellenando, y si la configuración es válida. Con `paramsx configure --ejemplo` además deja la plantilla de esta versión en `paramsx_config.ejemplo.py`, al lado de la tuya, para que compares sin tocar nada.
+
 Ejemplo del contenido de paramsx_config.py:
 
 ```python
 ## Configuraciones ParamsX
 
-naming = {
+# --- Perfiles -------------------------------------------------------------
+# Un perfil dice CÓMO se construye la ruta real en AWS a partir de la ruta que declaras
+# en 'parameter_list' y del entorno que eliges en el menú. Los nombres son tuyos: define
+# solo los que uses y llámalos como quieras. Un perfil tiene tres campos:
+#
+#   campo             | valores                                  | qué decide
+#   ------------------+------------------------------------------+---------------------------
+#   posicion_entorno  | inicio | final | mixto | ninguno          | dónde va el entorno
+#   case_entorno      | lower | upper | capitalize                | cómo se escribe el entorno
+#   case_ruta         | lower | upper | capitalize | ninguno      | case de la ruta AL CREAR
+#
+# posicion_entorno -> dónde se coloca el entorno (ejemplos con el entorno 'dev'):
+#
+#   valor    | ruta declarada  | ruta real en AWS
+#   ---------+-----------------+--------------------------------------------------------
+#   inicio   | /rds            | /dev/rds
+#   final    | /API/STA        | /API/STA/DEV
+#   mixto    | /API/*/STA      | /API/DEV/STA    el '*' marca el sitio; uno y como segmento
+#   ninguno  | /api/sta/auth   | /api/sta/auth   una cuenta AWS por entorno; case_entorno da igual
+#
+# case_entorno -> cómo se escribe ese entorno en la ruta:
+#
+#   valor       | 'dev' se escribe | ruta real de /API/STA con posicion_entorno=final
+#   ------------+------------------+------------------------------------------------
+#   lower       | dev              | /API/STA/dev
+#   upper       | DEV              | /API/STA/DEV
+#   capitalize  | Dev              | /API/STA/Dev
+#
+# case_ruta -> a qué case se fuerza la ruta que TÚ escribes al CREAR un parámetro
+# (opción 4 del menú). No afecta a leer ni a editar: lo que ya existe en AWS se
+# respeta siempre tal cual esté.
+#
+#   valor       | si escribes /API/MULTIAPI/Token, se crea
+#   ------------+-----------------------------------------
+#   lower       | /api/multiapi/token
+#   upper       | /API/MULTIAPI/TOKEN
+#   capitalize  | /Api/Multiapi/Token
+#   ninguno     | /API/MULTIAPI/Token
+#
+# Combina los tres campos como necesites: no hay una lista cerrada de perfiles. En el
+# README tienes más ejemplos.
+
+perfiles = {
     "min": {"posicion_entorno": "inicio", "case_entorno": "lower", "case_ruta": "lower"},
     "max": {"posicion_entorno": "final", "case_entorno": "upper", "case_ruta": "ninguno"},
     "mixto_max": {"posicion_entorno": "mixto", "case_entorno": "upper", "case_ruta": "ninguno"},
@@ -126,101 +170,71 @@ configuraciones = {
     "region_name": "eu-south-2",         # Cambiar por tu región de AWS
     "entornos": ['dev', 'pre', 'prod'],  # SIEMPRE en minúscula, es la lista canónica única
     "parameter_list": [
-        {"path": "/common", "convencion": "min"},      # -> /dev/common
-        {"path": "/rds", "convencion": "min"},         # -> /dev/rds
-        {"path": "/EMAIL", "convencion": "max"},       # -> /EMAIL/DEV
-        {"path": "/API/STA", "convencion": "max"},     # -> /API/STA/DEV
-        {"path": "/API/MULTIAPI/*/stan_ai", "convencion": "mixto_max"},  # -> /API/MULTIAPI/DEV/stan_ai
+        {"path": "/common", "perfil": "min"},      # -> /dev/common
+        {"path": "/rds", "perfil": "min"},         # -> /dev/rds
+        {"path": "/EMAIL", "perfil": "max"},       # -> /EMAIL/DEV
+        {"path": "/API/STA", "perfil": "max"},     # -> /API/STA/DEV
+        # Con 'mixto' acotas por debajo del entorno: esto lee solo stan_ai, en vez de
+        # todo lo que cuelga de /API/MULTIAPI/DEV
+        {"path": "/API/MULTIAPI/*/stan_ai", "perfil": "mixto_max"},  # -> /API/MULTIAPI/DEV/stan_ai
     ]
 }
 
-convencion_nuevos = "min"
+# Perfil que se usa al crear un parámetro nuevo (opción 4 del menú).
+# Si no lo defines, se usa el primero de 'perfiles'.
+perfil_nuevos = "min"
 
+# ¿El nombre del fichero exportado incluye la ruta leída?
+#   False -> parameters_dev.py            (comportamiento de siempre)
+#   True  -> parameters_dev__API_STA__max.py  (uno por entrada y entorno: lleva el
+#            entorno, la ruta y el perfil, porque dos entradas pueden compartir ruta)
+# Ponlo en True si sueles leer varias rutas del mismo entorno y no quieres que la
+# segunda lectura te machaque el fichero de la primera.
 fichero_por_ruta = False
 
 
 ## Configuraciones Tags
 
+# Gestionar las tags de los parámetros: leerlas de AWS, exponerlas en el fichero
+# exportado para editarlas y validar las obligatorias al cargar.
+#   True  -> las tags viajan en el fichero y se validan.
+#   False -> no aparecen tags en el fichero y no se valida nada.
+# En cuentas cuyo control de acceso va por tags (ABAC vía IAM) esto debe estar en True.
 tags_activas = True
 
+# Solo aplica si tags_activas = True.
+#   False -> validación bloqueante: si a un parámetro le falta alguna tag obligatoria
+#            no se sube (ni su valor ni sus tags).
+#   True  -> se permiten vacías: el parámetro se sube igualmente y las tags sin valor
+#            simplemente NO se crean en AWS (no se suben como etiquetas vacías).
 obligatorias_vacias = False
 
+# Tags que se exigen en cada parámetro cuando tags_activas = True. La lista es libre:
+# estas 8 son las que sostienen el control de acceso ABAC vía IAM de nuestra cuenta.
 tags_obligatorias = [
-    "Application", "Environment", "Owner", "Project",
-    "Product", "Service", "Component", "ManagedBy",
+    "Application",
+    "Environment",
+    "Owner",
+    "Project",
+    "Product",
+    "Service",
+    "Component",
+    "ManagedBy",
 ]
 ```
 Nota: Si el archivo paramsx_config.py ya existe, no será sobrescrito durante la instalación para proteger las configuraciones personalizadas.
 
-### Los perfiles de naming
-
-Cada organización nombra sus parámetros a su manera, así que ParamsX no impone ninguna convención: **tú defines los perfiles que uses en el diccionario `naming` y les pones el nombre que quieras**. Cada entrada de `parameter_list` declara con qué perfil se construye su ruta completa.
-
-Un perfil tiene tres campos:
-
-| Campo | Valores | Qué decide |
-|---|---|---|
-| `posicion_entorno` | `inicio` \| `final` \| `mixto` \| `ninguno` | Dónde va el entorno dentro de la ruta. |
-| `case_entorno` | `lower` \| `upper` \| `capitalize` | Cómo se escribe el entorno. |
-| `case_ruta` | `lower` \| `upper` \| `capitalize` \| `ninguno` | Case de la ruta al crear parámetros. |
-
-Y en detalle:
-
-**`posicion_entorno`** — dónde se coloca el entorno, con el entorno `dev`:
+### Los perfiles
 
-| Valor | Ruta declarada | Ruta real en AWS | |
-|---|---|---|---|
-| `inicio` | `/rds` | `/dev/rds` | |
-| `final` | `/API/STA` | `/API/STA/DEV` | |
-| `mixto` | `/API/*/STA` | `/API/DEV/STA` | el `*` marca el sitio |
-| `ninguno` | `/api/sta/auth` | `/api/sta/auth` | una cuenta AWS por entorno |
-
-**`case_entorno`** — cómo se escribe ese entorno en la ruta:
-
-| Valor | `dev` se escribe | `/API/STA` con `posicion_entorno: final` |
-|---|---|---|
-| `lower` | `dev` | `/API/STA/dev` |
-| `upper` | `DEV` | `/API/STA/DEV` |
-| `capitalize` | `Dev` | `/API/STA/Dev` |
-
-**`case_ruta`** — a qué case se fuerza la ruta que escribes al **crear** un parámetro (opción 4). No afecta a leer ni a editar: lo que ya existe en AWS se respeta siempre tal cual esté.
-
-| Valor | Si escribes `/API/MULTIAPI/Token`, se crea |
-|---|---|
-| `lower` | `/api/multiapi/token` |
-| `upper` | `/API/MULTIAPI/TOKEN` |
-| `capitalize` | `/Api/Multiapi/Token` |
-| `ninguno` | `/API/MULTIAPI/Token` |
+Cada organización nombra sus parámetros a su manera, así que ParamsX no impone ninguna convención: **tú defines los perfiles que uses en el diccionario `perfiles` y les pones el nombre que quieras**. Cada entrada de `parameter_list` declara con qué perfil se construye su ruta completa, con la clave `perfil`. Los tres campos de un perfil y sus valores están explicados en el propio fichero de configuración, ahí arriba.
 
 **No hay una lista cerrada de perfiles.** Los tres campos se combinan libremente, así que la plantilla no intenta traértelos todos: define los dos o tres que use tu organización y olvídate del resto. `min` y `max` vienen predefinidos porque son los que ParamsX traía antes de que los perfiles fueran configurables.
 
-**`mixto` y el marcador `*`.** Cuando el entorno no va ni al principio ni al final, se marca su sitio con un `*` en la propia ruta. Es útil para acotar la lectura a un solo subárbol: con `/API/MULTIAPI/*/stan_ai` lees únicamente `/API/MULTIAPI/DEV/stan_ai`, en vez de todo lo que cuelga de `/API/MULTIAPI/DEV`. El `*` debe ser un segmento entero y aparecer **exactamente una vez**, y solo se admite en perfiles `mixto`: si el perfil y la ruta no cuentan la misma historia, ParamsX te lo dice al arrancar en vez de leer una ruta inexistente y devolverte una lista vacía.
+**Para qué sirve el `*`.** Además de colocar el entorno donde quieras, acota la lectura a un solo subárbol: con `/API/MULTIAPI/*/stan_ai` lees únicamente `/API/MULTIAPI/DEV/stan_ai`, en vez de todo lo que cuelga de `/API/MULTIAPI/DEV`. Debe ser un segmento entero, aparecer **exactamente una vez** y solo se admite en perfiles `mixto`: si el perfil y la ruta no cuentan la misma historia, ParamsX te lo dice al arrancar en vez de leer una ruta inexistente y devolverte una lista vacía.
 
-**`ninguno` y las cuentas sin entorno en la ruta.** Hay organizaciones que separan los entornos por cuenta de AWS y no meten `dev`/`prod` en el path. Con `posicion_entorno: "ninguno"` la ruta se usa tal cual; el selector de entorno del menú sigue existiendo, pero no toca la ruta. En este perfil el `case_entorno` es irrelevante, porque no se escribe ningún entorno.
+**Los entornos.** Ya no existe la lista `entornos_old`: el entorno sale siempre de la lista canónica `entornos` (en minúscula), aplicándole el `case_entorno` del perfil. Si en tus rutas se llama `staging` en vez de `pre`, ponlo así en `entornos`.
 
-Ya **no existe** la lista `entornos_old`: el entorno se escribe siempre a partir de la lista canónica `entornos` (en minúscula), aplicándole el `case_entorno` del perfil. Si en tus rutas el entorno se llama `staging` en vez de `pre`, ponlo así en `entornos`.
-
-Ejemplo completo de una `parameter_list` real, mezclando perfiles:
-
-```python
-    "parameter_list": [
-        {"path": "/common", "convencion": "min"},
-        {"path": "/rds", "convencion": "min"},
-        {"path": "/api", "convencion": "min"},
-        {"path": "/INFRA", "convencion": "max"},
-        {"path": "/API/STA", "convencion": "max"},
-        {"path": "/API/p15", "convencion": "max"},
-        {"path": "/API/MULTIAPI", "convencion": "max"},
-        {"path": "/APP/Alertas", "convencion": "max"},
-        {"path": "/BUCKETS", "convencion": "max"},
-        {"path": "/EMAIL", "convencion": "max"},
-        {"path": "/INFERENCIAS/TASA_DMI", "convencion": "max"},
-        {"path": "/CEE/CEXGEN", "convencion": "max"},
-        {"path": "/API/MULTIAPI/*/stan_ai", "convencion": "mixto_max"},
-    ]
-```
-
-Sobre mayúsculas y minúsculas: ParamsX **no renombra ni fuerza el case de los parámetros que ya existen**, los lee y edita tal cual estén. El `case_ruta` del perfil solo entra en juego al crear parámetros nuevos.
+Y ParamsX **no renombra ni fuerza el case de los parámetros que ya existen**: los lee y edita tal cual estén. El `case_ruta` del perfil solo entra en juego al crear parámetros nuevos.
 
 ### Un fichero por ruta: `fichero_por_ruta`
 
@@ -232,15 +246,15 @@ En el nombre van el entorno, la ruta y el perfil, porque dos entradas pueden com
 
 | Entrada | Fichero |
 |---|---|
-| `{"path": "/API/STA", "convencion": "max"}` | `parameters_dev__API_STA__max.py` |
-| `{"path": "/API/*/STA", "convencion": "mixto_max"}` | `parameters_dev__API_env_STA__mixto_max.py` |
+| `{"path": "/API/STA", "perfil": "max"}` | `parameters_dev__API_STA__max.py` |
+| `{"path": "/API/*/STA", "perfil": "mixto_max"}` | `parameters_dev__API_env_STA__mixto_max.py` |
 
 ### Cómo acotar tu parameter_list (recomendación)
 
 `parameter_list` es solo tu vista de trabajo: **la seguridad real la impone IAM, no este fichero**. La recomendación de uso es:
 
-- **Admins**: pueden configurar rutas raíz amplias, por ejemplo `{"path": "/rds", "convencion": "min"}` → `/dev/rds`.
-- **Usuarios normales**: conviene acotar la ruta a lo que su rol IAM tiene realmente autorizado, por ejemplo `{"path": "/rds/cee-dev/api", "convencion": "min"}` → `/dev/rds/cee-dev/api`.
+- **Admins**: pueden configurar rutas raíz amplias, por ejemplo `{"path": "/rds", "perfil": "min"}` → `/dev/rds`.
+- **Usuarios normales**: conviene acotar la ruta a lo que su rol IAM tiene realmente autorizado, por ejemplo `{"path": "/rds/cee-dev/api", "perfil": "min"}` → `/dev/rds/cee-dev/api`.
 
 Si configuras una ruta más amplia que tus permisos, no pasa nada grave: ParamsX te avisará con un mensaje claro de acceso denegado en vez de una traza de boto3. Pero afinar la ruta te ahorra el error.
 
@@ -322,7 +336,17 @@ En algunos sistemas (especialmente en entornos corporativos como Windows), el PA
 ```source ~/.zshrc    # Para zsh```
 
 Una vez instalado, verifica que el comando paramsx esté disponible ejecutando:
-```paramsx --help```
+```paramsx --version```
+
+Comandos disponibles:
+
+| Comando | Qué hace |
+|---|---|
+| `paramsx` | Abre el menú interactivo (necesita configuración). |
+| `paramsx configure` | Crea la configuración la primera vez; si ya existe, la revisa sin tocarla. |
+| `paramsx configure --ejemplo` | Además deja la plantilla de esta versión al lado, para comparar. |
+| `paramsx --version` | Versión instalada. |
+| `paramsx --help` | Ayuda, con el resumen de todas las opciones de configuración. |
 
 
 ## Modo de empleo
@@ -339,7 +363,7 @@ El programa mostrará un menú donde Podrás:
 - Crear un parámetro nuevo.
 
 ### Leer Parámetros:
-1. Selecciona la opción "Leer parámetros" en el menú. La lista muestra cada ruta con su perfil de naming, por ejemplo `/rds  [min]` o `/API/STA  [max]`.
+1. Selecciona la opción "Leer parámetros" en el menú. La lista muestra cada ruta con su perfil, por ejemplo `/rds  [min]` o `/API/STA  [max]`.
 2. Elige el prefijo y el entorno que deseas consultar.
 3. Los parámetros serán descargados y guardados en archivos como:
     - parameters_dev.py
@@ -360,7 +384,7 @@ El programa mostrará un menú donde Podrás:
 
 ### Crear un parámetro nuevo:
 1. Selecciona la opción "Crear nuevo parámetro" y elige el entorno.
-2. Escribe la ruta **sin el entorno**, como en tu `parameter_list`: ParamsX le aplica el perfil de `convencion_nuevos` y te enseña la ruta resultante en AWS para que la confirmes.
+2. Escribe la ruta **sin el entorno**, como en tu `parameter_list`: ParamsX le aplica el perfil de `perfil_nuevos` y te enseña la ruta resultante en AWS para que la confirmes.
 3. Escribe el valor: texto plano o JSON en una línea.
 4. Rellena las tags obligatorias (si `tags_activas = True`). `Environment` viene precargada con el entorno elegido. Con `obligatorias_vacias = True` puedes dejar alguna en blanco pulsando Enter: esas no se crearán en AWS.
 5. Confirma en la pantalla de resumen. Si es un parámetro de RDS y falta su contraparte (común o privado), verás el aviso de correlación de naming ahí mismo.

paramsx-2.2.2/paramsx/__init__.py

@@ -0,0 +1 @@
+__version__ = "2.2.2"