Cómo contribuir

Cómo contribuir#

Read in English

Para contribuir, haga un fork de este repositorio, cree una nueva rama y abra un pull request.

cpanel-cli está escrito en Python (versión 3.11 o posterior). El código está organizado en este árbol:

cpanel-cli
├── API.md
├── CONTRIBUTING.rst
├── cpanel
│   ├── cli.py
│   ├── core.py
│   ├── __init__.py
│   ├── __main__.py
│   ├── REFERENCE
│   └── USAGE
├── doc
│   ├── conf.py
│   ├── contributing.rst
│   ├── index.rst
│   ├── locale
│   │   └── es
│   │       └── LC_MESSAGES
│   │           ├── contributing.po
│   │           ├── index.po
│   │           ├── installation.po
│   │           ├── reference.po
│   │           └── reference
│   │               └─── *.po
│   ├── reference.sh
│   ├── requirements.txt
│   └── _static
│       ├─── *.svg
│       └─── *.png
├── hatch.py
├── LICENSE
├── Makefile
├── pyproject.toml
├── pyrightconfig.json
├── README.rst
├── .readthedocs.yaml
├── test
│   ├── cpanelrc.test.example
│   └── test_uapi.py
└── tox.ini

cpanel contiene el código fuente principal. Los archivos REFERENCE y USAGE contienen el texto para las opciones --help y --version y el comando help. (Los mantengo en archivos externos para que sea más fácil editarlos. Además, puedo analizar programáticamente REFERENCE para generar los archivos *.rst para el constructor de documentación Sphinx. Vea el script reference.sh más abajo).

El archivo pyproject.toml estándar contiene los metadatos del proyecto, las dependencias de desarrollo y publicación, y las definiciones del backend de compilación. (Vea Writing your pyproject.toml para más información.)

Uso el backend de construcción Hatchling, con un pequeño script personalizado hatch.py para obtener las propiedades de metadatos dynamic en pyproject.toml. El script hatch.py funciona analizando el archivo fuente cpanel/__init__.py.

pyrightconfig.json es el archivo de configuración para el verificador de tipos estáticos Pyright

test contiene un conjunto de pruebas unitarias de la API. Están escritas usando el framework de automatización tox. El código que controla las pruebas está en test/test_uapi.py; el archivo de configuración principal de tox es tox.ini. Nótese que no son simples pruebas unitarias independientes, sino pruebas de API que se ejecutan en una instancia de cPanel activa. Vea Ejecución de pruebas más abajo para más detalles.

doc contiene las fuentes de la documentación, escritas en reStructuredText y procesadas con Sphinx. El archivo de configuración principal de Sphinx es doc/conf.py. La versión de Sphinx y el tema utilizado para construir la documentación están en doc/requirements.txt.

Las fuentes de la documentación están en doc/*.rst. El archivo index.rst es la página principal. Nótese una carpeta doc/reference y una serie de archivos *.rst en ésta. Éstos son generados programáticamente por el script reference.sh y no necesitan ser editados manualmente. (Los subo al repositorio porque Sphinx los usa como sus archivos fuentes).

El script reference.sh genera doc/reference.rst y los archivos dentro de doc/reference/ analizando el archivo de texto REFERENCE, dividiéndolo en secciones y convirtiéndolas a restructuredText. Esto me permite mantener REFERENCE como una única fuente de verdad para la documentación y mantener los archivos de Sphinx actualizados.

_static contiene las imágenes y archivos SVG utilizados en la documentación.

.readthedocs.yaml es un archivo de configuración para Read the Docs. El sistema remoto de construcción de Sphinx utiliza este archivo.

También mantengo una traducción al español de la documentación, generada usando cadenas de una serie de archivos de catálogo (*.po) dentro de locale/es/LC_MESSAGES/. Vea Traducciones para más información.

Finalmente, uso un Makefile para automatizar todas las fases del ciclo de vida del desarrollo. (Make y los Makefiles son increíbles.)

Entorno de desarrollo#

cpanel-cli fue desarrollado en Ubuntu Linux 23.10 “Mantic” con Python 3.11. Sin embargo cpanel-cli no tiene ningún requerimiento especial, por lo que cualquier distribución de Linux que soporte al menos Python 3.11 debería funcionar. También puede utilizar macOS “Ventura” o posterior.

Para crear un entorno de desarrollo en macOS:

Instale Python 3:

$ brew install python

Homebrew instala la última versión de Python disponible. Si desea instalar una versión específica, puede usar el excelente utilitario Pyenv para gestionar diferentes versiones de Python en paralelo.

Instale GNU Make:

$ brew install make

Para crear un entorno de desarrollo en Linux:

Para distros basadas en Debian (Ubuntu, Mint), instale Python 3 con:

$ sudo apt install python3 python3-pip python3-venv

Para distros basadas en RPM (RHEL, Fedora), instale Python 3 con:

$ sudo dnf install python3 python3-pip

apt y dnf instalan la última versión de Python disponible. Si quiere instalar una versión específica, puede usar el excelente utilitario Pyenv para gestionar diferentes versiones de Python.

GNU Make está instalado por defecto en la mayoría de las distros de Linux. Verifique su disponibilidad usando:

$ make --version

Construcción del paquete cpanel-cli a partir del código fuente#

Para construir e instalar un paquete local cpanel-cli use:

$ make install

Lo anterior ejecuta lo siguiente:

  1. Crea un nuevo entorno virtual de Python 3 en un directorio venv

  2. Instala en venv los paquetes de desarrollo listados en la sección [project.optional-dependencies] de pyproject.toml

  3. Construye un paquete local de cpanel-cli

Ejecución local#

Para ejecutar el paquete instalado localmente, primero active el entorno virtual (necesita ejecutar esto sólo una vez por sesión):

$ source venv/bin/activate

Luego ejecute el utilitario cpanel:

$ cpanel --help

Si edita las fuentes, simplemente ejecute pip3 install . (nótese el punto .) para reconstruir el paquete local.

Ejecución (opcional) del verificador de tipos#

El verificador de tipos es opcional; puede ignorar este paso si lo desea.

El código fuente de Python está anotado con sugerencias de tipos (type hints). Las uso hacer más legible el código. Lea la Guía de verificación de tipos en Python para una excelente introducción al uso de sugerencias de tipos en Python.

Las sugerencias de tipos no son realmente verificadas por el runtime de Python; necesita un utilitario de un tercero. Para este proyecto uso Pyright, que es mi verificador de tipos preferido para Python..

Para instalar Pyright:

$ pip3 install --user pyright

Ejecútelo con:

$ make typecheck

La configuración del verificador está en pyrightconfig.json.

Tenga en cuenta que Pyright está basado en Node.js, por lo que pip instalará indirectamente Node.js y un montón de dependencias de JavaScript necesarias para Pyright.

Ejecución de pruebas#

Para las pruebas unitarias del API uso el framework de automatización tox. El código que controla las pruebas está en test/test_uapi.py; el archivo de configuración principal de tox es tox.ini.

Éstas no son pruebas unitarias simples, sino pruebas unitarias de API que se ejecutan contra una instancia en vivo de cPanel. Por esto, tox necesita acceso a una instancia de cPanel activa en algún host remoto accesible desde el host local

Para establecer las credenciales del host remoto, haga una copia del archivo proporcionado cpanelrc.test.example y cámbiele el nombre a cpanelrc.test (manténgalo en el directorio test):

$ cp test/cpanelrc.test.example test/cpanelrc.test

Luego edite cpanelrc.test y proporcione los siguientes datos:

  • El nombre del host remoto de la instancia de cPanel

  • El nombre de usuario de su cuenta de cPanel

  • Un token de API asociado a ese nombre de usuario.

La autenticación basada en tokens es el único método de autenticación soportado.

Para ejecutar las pruebas, use:

$ make test

El comando anterior accede a un subconjunto de la interfaz REST de cPanel UAPI con las funciones implementadas en cpanel-cli.

El estado remoto de cPanel se deja sin cambios, es decir, las pruebas son estrictamente no destructivas.

Empaquetado#

El empaquetado se realiza a través del backend de construcción Hatchling, como se especifica en la sección [build-system] de pyproject.toml.

Para ejecutar el empaquetador, use:

$ make package

El comando anterior debería generar los siguientes dos archivos de distribución en el directorio temporal dist:

cpanel_cli-<version>-py3-none-any.whl
cpanel-cli-<version>.tar.gz

donde <versión> es el número de versión establecido en cpanel/__init__.py.

El archivo tar contiene el código fuente; el archivo wheel es el archivo de distribución binaria para instalación. Los archivos incluidos para estos paquetes de distribución están listados en las secciones [tool.hatch.build.targets.sdist] y [tool.hatch.build.targets.wheel] de pyproject.toml respectivamente.

Estos paquetes están listos para ser subidos al Python Package Index.

Construcción de la documentación#

Los archivos fuente de la documentación de la API están en el directorio doc. Estos comprenden archivos reStructuredText (.rst) que se procesan con Sphinx para generar árboles HTML estáticos.

Para construir la documentación utilice:

$ make doc

El comando anterior genera varios árboles HTML estáticos en doc/build/html. Por ejemplo, la documentación por defecto en inglés se genera en doc/build/html/en; la página de inicio es un archivo convencional index.html.

Este repositorio de GitHub está actualmente conectado a mi cuenta de Read the Docs, de modo que cualquier cambio en un commit (o merge) que actualice las fuentes de documentación dispara automáticamente una reconstrucción remota de Sphinx. La documentación HTML resultante está siempre disponible en https://cpanel-cli.readthedocs.io/es/stable/

El archivo de configuración principal para Sphinx es doc/conf.py. La versión de Sphinx y el tema usado para construir la documentación están en doc/requirements.txt.

Traducciones#

Los archivos .*rst en doc son las fuentes de los archivos de documentación. Todas las traducciones se basan en estos documentos. La traducción se realiza cadena por cadena, utilizando la cadena original en inglés como clave (.msgid), y la correspondiente cadena traducida como valor (msgstr). Por ejemplo, para español:

msgid "To be, or not to be, that is the question"
msgstr "Ser o no ser, he ahí el dilema"

Estos pares msgid y msgstr se guardan en un archivo de catálogo (.*po), que es un archivo de texto simple. Estos archivos de catálogo se almacenan en el subdirectorio doc/locale.

La traducción al español de la documentación la mantengo personalmente en los archivos de catálogo .doc/locale/es/LC_MESSAGES/*.po.

Los archivos .po de catálogo se compilan en archivos .mo con el utilitario de internacionalización de Sphinx. Estos archivos .mo compilados se utilizan luego para componer las versiones traducidas durante la Construcción de la documentación.

Cómo añadir una traducción#

Para añadir una nueva traducción:

  1. Cree un nuevo catálogo:

    $ make locale iso=<language code>

    donde <código de idioma> es el código ISO 639-1 correspondiente al nuevo idioma. Por ejemplo, para añadir una traducción al francés se utilizaría:

    $ make locale iso=fr

    Este añadiría un nuevo directorio locale/fr/LC_MESSAGES con varios archivos .po.

  2. Edite los archivos .po creado en el paso 1 e inserte las cadenas traducidas como campos msgstr. Por ejemplo:

    msgid "Indices and tables"
msgstr "Indices et tableaux"

  3. Reconstruya la documentación:

    $ make doc

    El comando anterior crea un nuevo árbol HTML estático en doc/build/html/<código de idioma>. Por ejemplo, para el francés, crearía un nuevo árbol en doc/build/html/fr.

Cómo corregir y ampliar una traducción existente#

Si se edita el texto de los archivos de documentación originales doc/*.rst, también hay que actualizar las traducciones:

  1. Ejecute lo siguiente para actualizar los catálogos:

    $ make locale iso=<language code>

    donde <language code> es el código ISO 639-1. Tiene que ejecutarlo para cada lenguaje traducido.

  2. El paso anterior emite un informe con los archivos .po que necesitan ser actualizados, por ejemplo:

    Update: doc/locale/es/LC_MESSAGES/reference.po +5, -2
Update: doc/locale/es/LC_MESSAGES/contributing.po +9, -0

    Abra los archivos .po mencionados y edite o agregue nuevas cadenas msgstr. Tenga en cuenta que algunas entradas pueden ser anotadas como #, fuzzy, lo que significa que el motor de internacionalización no está seguro si ya existe una traducción para esa entrada debido a similitudes con otra entrada. Sólo se necesita editar el texto de msgstr y eliminar la línea fuzzy.

Para más información consulte la Guía de internacionalización.