Diferencias

Muestra las diferencias entre dos versiones de la página.

--- python:instalable [2025/07/15 12:47] – [Local] alberto
+++ python:instalable [2025/07/16 12:05] (actual) – [main.py] alberto
@@ Línea 26: / Línea 26: @@
 ==== __init__.py ====
-Este archivo indica a Python que esta carpeta es un paquete (podría estar vacía)
+Este archivo indica a Python que esta carpeta es un paquete (podría estar vacía). \\
 Funciona como un "expositor" de las funciones principales del paquete, de modo que puede incluir código que define qué funciones o clases están disponibles al hacer import.
@@ Línea 35: / Línea 35: @@
 ==== main.py ====
-Es el punto de entrada al paquete cuando lo ejecutas desde consola.
+Es el punto de entrada al paquete cuando lo ejecutas desde consola. \\
-Es donde se define la interfaz de línea de comandos (CLI): qué comandos, opciones y argumentos puede introducir el usuario, incluidos los //--help//.
+Es donde se define la interfaz de línea de comandos (CLI, //Command Line Interface//): qué comandos, opciones y argumentos puede introducir el usuario, incluidos los //--help//. En ocasiones el archivo donde se encuentra la función main() también suele llamarse cli.py\\
-Utiliza la biblioteca **argparse** para leer argumentos desde línea de comandos.
+Utiliza la biblioteca **argparse** para leer argumentos desde línea de comandos. \\
 En main.py se puede:
   - Leer argumentos desde la terminal.
@@ Línea 44: / Línea 44: @@
   - Mostrar mensajes, progreso (por ejemplo con barras con la librería tqdm) o errores.
   - Devolver resultados al usuario (PDF generados, logs, rutas, etc.).
+\\
+En definitiva, realiza el flujo del programa.\\
+Cuando añadimos parámetros con add_argument, tenemos las siguientes opciones:
+^ Parámetro             ^ Descripción                                                                                     ^ Ejemplo                                              ^
+| `name or flags`       | Nombre del argumento (posicional o con guiones).                                                | `'--verbose'`, `'-v'`, `'archivo'`                   |
+| `action`              | Qué hacer con el argumento al encontrarlo (ver tabla de abajo).                                | `'store'`, `'store_true'`, `'append'`, etc.          |
+| `nargs`               | Número de valores esperados (`?`, `*`, `+`, número entero, etc).                                | `nargs='?'`, `nargs=2`                               |
+| `const`               | Valor constante usado cuando se emplea con ciertas acciones como `store_const`.                 | `const=42`                                           |
+| `default`             | Valor por defecto si no se proporciona el argumento.                                            | `default='salida.txt'`                               |
+| `type`                | Tipo de dato al que convertir el argumento.                                                     | `type=int`, `type=float`, `type=Path`                |
+| `choices`             | Lista de valores permitidos.                                                                    | `choices=['bajo', 'medio', 'alto']`                  |
+| `required`            | Si el argumento es obligatorio (solo para argumentos opcionales).                              | `required=True`                                      |
+| `help`                | Texto de ayuda mostrado al ejecutar `--help`.                                                   | `help='Archivo de entrada.'`                         |
+| `metavar`             | Nombre que aparece en la ayuda en lugar del nombre real del argumento.                         | `metavar='FICHERO'`                                  |
+| `dest`                | Nombre del atributo en `args` donde se guarda el valor.                                         | `dest='nivel'`                                       |
+Para el parámetro "action" disponemos e estas posibilidades:
+^ Acción           ^ Descripción                                                                                   ^ Ejemplo de uso                                     ^
+| `'store'`        | Guarda el valor dado (por defecto).                                                           | `--salida salida.txt`                              |
+| `'store_const'`  | Guarda un valor constante (requiere `const=`).                                                | `--modo`, `action='store_const', const='debug'`    |
+| `'store_true'`   | Guarda `True` si se especifica, `False` si no.                                                | `--verbose`, `action='store_true'`                 |
+| `'store_false'`  | Guarda `False` si se especifica, `True` si no.                                                | `--no-cache`, `action='store_false'`               |
+| `'append'`       | Añade cada valor a una lista.                                                                | `--tag urgente --tag personal` → `['urgente',...]` |
+| `'append_const'` | Añade un valor constante a una lista (requiere `const=`).                                     | (menos común)                                       |
+| `'count'`        | Cuenta cuántas veces aparece el argumento.                                                   | `-v -v -v` → `3`                                    |
+| `'help'`         | Muestra el mensaje de ayuda y termina. (automática con `--help`)                             | `--help`                                            |
+| `'version'`      | Muestra el número de versión y termina. (requiere `version=`)                                | `--version`                                         |
-En definitiva, realiza el flujo del programa.
 A continuación un ejemplo, en el que se define el comando "gendocs" y 3 subcomandos "simples", "compuestos" y "cruce", cada uno con sus parámetros de entrada:
@@ Línea 193: / Línea 220: @@
 ==== setup.py ====
-Es el script de instalación. Usa la librería setuptools para convertir este proyecto en un paquete instalable con pip.
+Es el script de instalación. Usa la librería setuptools para convertir este proyecto en un paquete instalable con pip. \\
-Describe los metadatos (nombre, versión, dependencias, etc.), permite que el proyecto se instale localmente o se distribuya y configura comandos que puedas ejecutar desde cualquier terminal.
+Describe los metadatos (nombre, versión, dependencias, etc.), permite que el proyecto se instale localmente o se distribuya y configura comandos que puedas ejecutar desde cualquier terminal. \\
-Crea el comando: "gendocs --help", que ejecuta la función main() que está en nombre_programa/main.py
+Crea el comando: "gendocs --help", que ejecuta la función main() que está en nombre_programa/main.py \\
 Ejemplo:
 <code python>
@@ Línea 220: / Línea 247: @@
 </code>
+El bloque entry_points["console_scripts"] de setup.py sirve para registrar comandos de terminal que apuntan a funciones Python:
+<code toml>
+"console_scripts": [
+    "mi_comando = paquete.modulo:funcion_que_se_ejecuta"
+]
+</code>
+mi_comando → nombre que escribirás en la terminal. \\
+paquete.modulo → ruta al módulo dentro del paquete. \\
+funcion_que_se_ejecuta → debe ser una función sin argumentos (o que gestione sys.argv) que actuarán como el “main()” del comando. \\
+\\
+Si se desea cambiar el comando para ejecutar un programa, es suficiente con indicarlo en "console_scripts" y cambiar el campo "mi_comando". A continuación **es necesario reinstalar** con "pip install -e .", por ejemplo.
 ==== readme.md ====
-Es un archivo de texto (usualmente en formato Markdown, de ahí la extensión .md) que explica de qué trata el proyecto.
+Es un archivo de texto (usualmente en formato Markdown, de ahí la extensión .md) que explica de qué trata el proyecto. \\
 Sirve como presentación o guía rápida del proyecto. Suele incluir:
   * Qué hace el software
@@ Línea 256: / Línea 296: @@
-No es obligatorio incluirlo, pero sin licencia, legalmente nadie puede usar tu código, aunque esté en GitHub.
+No es obligatorio incluirlo, pero sin licencia, legalmente nadie puede usar tu código, aunque esté en GitHub. \\
 Pueden encontrarse en sus respectivas páginas web.
@@ Línea 280: / Línea 320: @@
 </code>
-El instalador añade el comando (el nombre que hayas puesto en entry_points) al PATH de tu entorno Python.
+El instalador añade el comando (el nombre que hayas puesto en entry_points) al PATH de tu entorno Python. \\
 Además, la carpeta desde donde haces la instalación en modo editable (pip install -e .) es, literalmente, la carpeta donde está el código que se ejecuta: Python crea un enlace simbólico (acceso directo interno) desde el entorno Python hacia la carpeta donde está tu código (donde está setup.py). \\
 Por eso cualquier cambio en esa carpeta afecta directamente al paquete instalado y ejecutable, sin necesidad de reinstalar.
+==== Local en otro equipo ====
+Lógicamente si se lleva el paquete a otro equipo, podría instalarse de la forma anterior.\\
+Sin embargo, también podría instalar se esta manera:
+<code bash>
+pip install . # Sustituye '.' por la ruta, si no estás en el mismo directorio que setup.py
+</code>
+Al prescindir del parámetro '-e' no ya no estamos en modo editable: se copiar el código fuente dentro de la carpeta interna de paquetes de Python (site-packages). \\
+En este caso, la ejecución del programa ya no depende de la carpeta de instalación original y es posible mover, borrar o renombrar la carpeta del proyecto, y el comando seguirá funcionando igual, porque ya tiene su copia interna.
+==== Desde GitHub ====
+Puedes instalar tu paquete desde cualquier máquina con:
+<code bash>
+pip install git+https://github.com/usuario/repositorio.git
+</code>
+O para una versión específica:
+<code bash>
+# Esto instalará la versión exactamente como estaba en el tag v1.0.0.
+pip install git+https://github.com/usuario/repositorio.git@v1.0.0
+</code>
+Desde GitHub, el programa se instala en modo no editable. \\
+Cada vez que se realice una mejora, corrección o cambio relevante, se hace un //commit// con un mensaje descriptivo. \\
+Al completar un conjunto de cambios estables (por ejemplo, una versión funcional completa), se hace un release/tag con un número de versión:
+<code bash>
+git tag v1.0.0
+git push origin v1.0.0
+# Ahora en GitHub aparece ese tag como versión 1.0.0. Puedes descargar ese estado exacto o instalar desde ahí.
+</code>
+Y para actualizar a la nueva versión (por ejemplo la v1.1.0):
+<code bash>
+pip install --upgrade git+https://github.com/usuario/repositorio.git@v1.1.0
+</code>