paramsx 2.2.1__tar.gz → 2.3.0__tar.gz

{paramsx-2.2.1 → paramsx-2.3.0}/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 2.3.0
+
+### Añadido
+
+- **La descripción de los parámetros, editable como el valor.** El fichero exportado trae un campo `parameter_description` **debajo del nombre y antes del valor**: se lee de AWS, lo editas y al cargar se actualiza. Los cambios de descripción se detectan igual que los de valor y aparecen en la pantalla de confirmación como `Modificado (descripción)`. La opción 4 también la pide al crear un parámetro, entre la ruta y el valor.
+- Los backups incluyen la descripción, así que un backup restaura también las descripciones.
+- **Flag `forzar_securestring`** (por defecto `True`, el comportamiento de siempre): todo lo que sube ParamsX va cifrado como `SecureString`. Con `False` se respeta el tipo que ya tuviera el parámetro en AWS: al actualizar no se manda el tipo y AWS conserva el suyo (`Type` solo es obligatorio al crear). El fichero exportado trae además un campo `parameter_type` editable, por si quieres cambiar el tipo a propósito, y sus cambios se detectan como los del valor o la descripción. El tipo se lee de la misma llamada que el valor, así que no hace falta ningún permiso nuevo.
+
+### Nota sobre el valor y la descripción
+
+`put_parameter` con `Overwrite=True` reescribe la definición del parámetro, así que ParamsX **manda siempre la descripción que trae el fichero**, incluso cuando lo único que cambió fue el valor. Antes no se mandaba, y una descripción que ya existiera en AWS podía quedarse vacía al editar el valor.
+
+### Nota sobre permisos
+
+Leer las descripciones necesita **`ssm:DescribeParameters`**, porque no vienen en `GetParametersByPath` (son metadatos, no valores). Si tu rol no lo tiene, ParamsX te avisa al leer, el campo no aparece en el fichero y al cargar **no se toca** la descripción que haya en AWS. El resto sigue funcionando igual.
+
+## 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

{paramsx-2.2.1/paramsx.egg-info → paramsx-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: paramsx
-Version: 2.2.1
+Version: 2.3.0
 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:
@@ -70,7 +70,7 @@ Al ejecutar ```paramsx``` desde la terminal, accedes a un menú interactivo con
 - Navega por la lista de parámetros configurada en tu archivo de configuración y selecciona cuál descargar.
 - Elige el entorno deseado (por ejemplo, dev o prod).
 - Archivos generados:
-    - parameters_dev.py o parameters_prod.py → Edita estos archivos para modificar, añadir o eliminar parámetros (valores y tags).
+    - parameters_dev.py o parameters_prod.py → Edita estos archivos para modificar, añadir o eliminar parámetros (descripciones, valores y tags).
     - parameters_dev_backup.py → Respaldo automático del archivo descargado, incluidas las tags.
 Los archivos se crean en la misma ruta desde donde ejecutas paramsx, evitando movernos innecesariamente entre carpetas.
 - Si tu rol IAM no tiene permisos sobre la ruta configurada, verás un mensaje claro en lugar de una traza de boto3:
@@ -97,10 +97,11 @@ 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.
+    - La descripción, opcional: para qué sirve el parámetro. Se guarda en AWS y luego se puede editar en el fichero exportado.
     - 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`.
 
@@ -135,7 +136,7 @@ Ejemplo del contenido de paramsx_config.py:
 ```python
 ## Configuraciones ParamsX
 
-# --- Perfiles de 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:
@@ -177,7 +178,7 @@ Ejemplo del contenido de paramsx_config.py:
 # Combina los tres campos como necesites: no hay una lista cerrada de perfiles. En el
 # README tienes más ejemplos.
 
-naming = {
+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"},
@@ -190,19 +191,19 @@ 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": "/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", "convencion": "mixto_max"},  # -> /API/MULTIAPI/DEV/stan_ai
+        {"path": "/API/MULTIAPI/*/stan_ai", "perfil": "mixto_max"},  # -> /API/MULTIAPI/DEV/stan_ai
     ]
 }
 
-# Perfil de naming que se usa al crear un parámetro nuevo (opción 4 del menú).
-# Si no lo defines, se usa el primer perfil de 'naming'.
-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)
@@ -212,6 +213,16 @@ convencion_nuevos = "min"
 # segunda lectura te machaque el fichero de la primera.
 fichero_por_ruta = False
 
+# ¿Todo lo que sube ParamsX va cifrado como SecureString?
+#   True  (por defecto) -> sí, siempre. Es lo recomendable: los parámetros de una cuenta
+#          suelen tener secretos, y así no depende de acordarse.
+#   False -> se respeta el tipo que ya tuviera el parámetro en AWS (String, StringList o
+#          SecureString): al actualizar no se manda el tipo, así que AWS conserva el suyo.
+#          En este modo el fichero exportado trae además un campo 'parameter_type' que
+#          puedes editar si quieres cambiarlo a propósito. Los parámetros que crees con
+#          la opción 4 se siguen creando como SecureString.
+forzar_securestring = True
+
 
 ## Configuraciones Tags
 
@@ -244,9 +255,9 @@ tags_obligatorias = [
 ```
 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
+### Los perfiles
 
-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. Los tres campos de un perfil y sus valores están explicados en el propio fichero de configuración, ahí arriba.
+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.
 
@@ -266,15 +277,47 @@ 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` |
+
+### La descripción de los parámetros
+
+El fichero exportado trae un campo `parameter_description` **debajo del nombre y antes del valor**. Se lee de AWS, se edita como cualquier otro campo y se aplica al cargar:
+
+```python
+parametros = [
+    {'parameter_name': '/dev/api/sta/token',
+     'parameter_description': "Token JWT de la API, rota cada 90 dias",
+     'parameter_value': """abc123"""},
+]
+```
+
+Dos cosas que conviene saber:
+
+- **Hace falta el permiso `ssm:DescribeParameters`.** La descripción no viaja en `GetParametersByPath` como el valor: es un metadato y se pide con `DescribeParameters`. Si tu rol no lo tiene, ParamsX te avisa, el campo **no aparece** en el fichero y al cargar no se toca la descripción que haya en AWS.
+- **Al actualizar un parámetro, AWS reescribe su definición entera.** Por eso ParamsX manda siempre la descripción del fichero cuando cambia el valor, aunque no la hayas tocado: si no la mandara, se perdería. Y como no existe una API para cambiar solo la descripción, editarla crea una versión nueva del parámetro igual que cambiar el valor.
+
+Un cambio de descripción se ve en la pantalla de confirmación como `Modificado (descripción)`, y si cambias las dos cosas, `Modificado (valor | descripción)`.
+
+### Cifrado: `forzar_securestring`
+
+ParamsX sube todo como **SecureString** por defecto, y así se recomienda dejarlo: los parámetros de una cuenta acaban teniendo secretos, y con esto no depende de que nadie se acuerde.
+
+| `forzar_securestring` | Qué hace |
+|---|---|
+| `True` (por defecto) | Todo lo que se sube va cifrado como `SecureString`, sea del tipo que sea en AWS. |
+| `False` | Se respeta el tipo que ya tuviera el parámetro (`String`, `StringList` o `SecureString`): al actualizar no se manda el tipo, y AWS conserva el suyo. El fichero exportado trae además un campo `parameter_type` que puedes editar si quieres cambiarlo a propósito, y ese cambio cuenta como uno más: verás `Modificado (tipo: SecureString)`. |
+
+Los parámetros que creas con la opción 4 se crean siempre como `SecureString`, en los dos modos.
+
+El tipo se lee de la misma llamada que el valor, así que **no hace falta ningún permiso extra** para esto (a diferencia de la descripción).
 
 ### 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.
 
@@ -300,6 +343,7 @@ Formato del fichero exportado con `tags_activas = True`:
 ```python
 parametros = [
     {'parameter_name': '/dev/email/users',
+     'parameter_description': "Buzon que recibe los avisos de altas",
      'parameter_value': """agpetrovici@stanalytics.es""",
      'tagApplication': "",
      'tagEnvironment': "",
@@ -383,7 +427,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
@@ -404,7 +448,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.1 → paramsx-2.3.0}/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:
@@ -50,7 +50,7 @@ Al ejecutar ```paramsx``` desde la terminal, accedes a un menú interactivo con
 - Navega por la lista de parámetros configurada en tu archivo de configuración y selecciona cuál descargar.
 - Elige el entorno deseado (por ejemplo, dev o prod).
 - Archivos generados:
-    - parameters_dev.py o parameters_prod.py → Edita estos archivos para modificar, añadir o eliminar parámetros (valores y tags).
+    - parameters_dev.py o parameters_prod.py → Edita estos archivos para modificar, añadir o eliminar parámetros (descripciones, valores y tags).
     - parameters_dev_backup.py → Respaldo automático del archivo descargado, incluidas las tags.
 Los archivos se crean en la misma ruta desde donde ejecutas paramsx, evitando movernos innecesariamente entre carpetas.
 - Si tu rol IAM no tiene permisos sobre la ruta configurada, verás un mensaje claro en lugar de una traza de boto3:
@@ -77,10 +77,11 @@ 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.
+    - La descripción, opcional: para qué sirve el parámetro. Se guarda en AWS y luego se puede editar en el fichero exportado.
     - 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`.
 
@@ -115,7 +116,7 @@ Ejemplo del contenido de paramsx_config.py:
 ```python
 ## Configuraciones ParamsX
 
-# --- Perfiles de 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:
@@ -157,7 +158,7 @@ Ejemplo del contenido de paramsx_config.py:
 # Combina los tres campos como necesites: no hay una lista cerrada de perfiles. En el
 # README tienes más ejemplos.
 
-naming = {
+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"},
@@ -170,19 +171,19 @@ 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": "/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", "convencion": "mixto_max"},  # -> /API/MULTIAPI/DEV/stan_ai
+        {"path": "/API/MULTIAPI/*/stan_ai", "perfil": "mixto_max"},  # -> /API/MULTIAPI/DEV/stan_ai
     ]
 }
 
-# Perfil de naming que se usa al crear un parámetro nuevo (opción 4 del menú).
-# Si no lo defines, se usa el primer perfil de 'naming'.
-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)
@@ -192,6 +193,16 @@ convencion_nuevos = "min"
 # segunda lectura te machaque el fichero de la primera.
 fichero_por_ruta = False
 
+# ¿Todo lo que sube ParamsX va cifrado como SecureString?
+#   True  (por defecto) -> sí, siempre. Es lo recomendable: los parámetros de una cuenta
+#          suelen tener secretos, y así no depende de acordarse.
+#   False -> se respeta el tipo que ya tuviera el parámetro en AWS (String, StringList o
+#          SecureString): al actualizar no se manda el tipo, así que AWS conserva el suyo.
+#          En este modo el fichero exportado trae además un campo 'parameter_type' que
+#          puedes editar si quieres cambiarlo a propósito. Los parámetros que crees con
+#          la opción 4 se siguen creando como SecureString.
+forzar_securestring = True
+
 
 ## Configuraciones Tags
 
@@ -224,9 +235,9 @@ tags_obligatorias = [
 ```
 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
+### Los perfiles
 
-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. Los tres campos de un perfil y sus valores están explicados en el propio fichero de configuración, ahí arriba.
+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.
 
@@ -246,15 +257,47 @@ 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` |
+
+### La descripción de los parámetros
+
+El fichero exportado trae un campo `parameter_description` **debajo del nombre y antes del valor**. Se lee de AWS, se edita como cualquier otro campo y se aplica al cargar:
+
+```python
+parametros = [
+    {'parameter_name': '/dev/api/sta/token',
+     'parameter_description': "Token JWT de la API, rota cada 90 dias",
+     'parameter_value': """abc123"""},
+]
+```
+
+Dos cosas que conviene saber:
+
+- **Hace falta el permiso `ssm:DescribeParameters`.** La descripción no viaja en `GetParametersByPath` como el valor: es un metadato y se pide con `DescribeParameters`. Si tu rol no lo tiene, ParamsX te avisa, el campo **no aparece** en el fichero y al cargar no se toca la descripción que haya en AWS.
+- **Al actualizar un parámetro, AWS reescribe su definición entera.** Por eso ParamsX manda siempre la descripción del fichero cuando cambia el valor, aunque no la hayas tocado: si no la mandara, se perdería. Y como no existe una API para cambiar solo la descripción, editarla crea una versión nueva del parámetro igual que cambiar el valor.
+
+Un cambio de descripción se ve en la pantalla de confirmación como `Modificado (descripción)`, y si cambias las dos cosas, `Modificado (valor | descripción)`.
+
+### Cifrado: `forzar_securestring`
+
+ParamsX sube todo como **SecureString** por defecto, y así se recomienda dejarlo: los parámetros de una cuenta acaban teniendo secretos, y con esto no depende de que nadie se acuerde.
+
+| `forzar_securestring` | Qué hace |
+|---|---|
+| `True` (por defecto) | Todo lo que se sube va cifrado como `SecureString`, sea del tipo que sea en AWS. |
+| `False` | Se respeta el tipo que ya tuviera el parámetro (`String`, `StringList` o `SecureString`): al actualizar no se manda el tipo, y AWS conserva el suyo. El fichero exportado trae además un campo `parameter_type` que puedes editar si quieres cambiarlo a propósito, y ese cambio cuenta como uno más: verás `Modificado (tipo: SecureString)`. |
+
+Los parámetros que creas con la opción 4 se crean siempre como `SecureString`, en los dos modos.
+
+El tipo se lee de la misma llamada que el valor, así que **no hace falta ningún permiso extra** para esto (a diferencia de la descripción).
 
 ### 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.
 
@@ -280,6 +323,7 @@ Formato del fichero exportado con `tags_activas = True`:
 ```python
 parametros = [
     {'parameter_name': '/dev/email/users',
+     'parameter_description': "Buzon que recibe los avisos de altas",
      'parameter_value': """agpetrovici@stanalytics.es""",
      'tagApplication': "",
      'tagEnvironment': "",
@@ -363,7 +407,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
@@ -384,7 +428,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.3.0/paramsx/__init__.py

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