To contribute, just fork this repository, start a new branch and open a pull request.
cpanel-cli
is written in Python 3.9. I organized the code into a standard tree:
cpanel-cli ├── CONTRIBUTING.rst ├── cpanel │ ├── cli.py │ ├── core.py │ ├── __init__.py │ └── __main__.py ├── doc │ ├── conf.py │ ├── index.rst │ ├── locale │ │ └── es │ │ └── LC_MESSAGES │ │ └── index.po │ └── requirements.txt ├── LICENSE ├── Makefile ├── README.rst ├── .readthedocs.yaml ├── requirements-dev.txt ├── requirements.txt ├── setup.py ├── test │ ├── cpanelrc.test.example │ └── test_core.py └── tox.ini
cpanel-cli
contains the main source code.
doc
contains the documentation sources, written in reStructuredText and processed using Sphinx.
The main configuration file for Sphinx is doc/conf.py
. The Sphinx version and theme used
to build the documentation are in doc/requirements.txt
.
.readthedocs.yaml
is a configuration file for Read the Docs. The remote Sphinx build system
uses this file.
I maintain a Spanish translation of the documentation, generated using strings from a
catalog file locale/es/LC_MESSAGES/index.po
.
I’m using a Makefile
to automate all phases of the development life cycle. (Make and Makefiles are awesome.)
requirements-dev.txt
contains the required packages for the Python Development environment,
while requirements.txt
contains the runtime dependencies.
setup.py
is the main script for setuptools, used for packaging and distributing this project.
I know that the use of setup.py
is currently discouraged, so I will probably replace it
with a more modern packaging system like Poetry, but I’m being conservative here and sticking
with setup.py
for now. (But notice I’m calling it indirectly using python -m build
,
as recommended.)
test
contains a set of unit API tests. They’re written using the tox automation framework.
The code driving the tests is in test/test_core.py
; the main tox configuration file is tox.ini
.
These are not simple standalone unit tests, but API tests running against
a live cPanel instance. See Running tests below for further details.
I developed cpanel-cli
on Ubuntu Linux 21.10 “Impish Indri”. There are no
special requirements, so any Linux distro or macOS version supporting at least
Python 3.9 should work.
On macOS “Catalina” or higher
Install Python 3.9:
$ brew install python@3.9
Then add the following to your PATH
:
PATH="$PATH:/usr/local/opt/python@3.9/Frameworks/Python.framework/Versions/3.9/bin"
export $PATH
Install GNU Make:
$ brew install make
On Ubuntu Linux 21.04 or higher
Install Python 3.9:
$ sudo apt install python3.9 python3-pip python3.9-venv
GNU Make is installed by default on Ubuntu. Check its availability using:
$ make --version
Other Linux distros
Use your distro’s package manager to install Python 3.9 (or higher) and GNU Make.
You can build and install a local cpanel-cli
package using:
$ make install
This will:
- Create a new virtual Python 3 environment in a
venv
directory - Install on it the required development packages listed in
requirements-dev.txt
- Build a local Python package
cpanel-cli
To run the executable from the locally installed package, first activate the virtual environment (you need to run this only once per session):
$ source venv/bin/activate
Then you can execute the cpanel
utility:
$ cpanel --help
If you edit the sources, simply run make install
to build and reinstall the local package.
The Python sources are in the cpanel
directory. You will notice they’re annotated using type
hints. I use them because IMHO they add clarity and robustness to Python
code. Read the Python Type Checking Guide for a good introduction to type checking in Python.
Since type hints are not actually checked by Python itself, you need an additional utility: a type checker. (You can think of the type checker as another kind of linter.) My type checker of choice for Python is Pyright.
Running the type checker is optional — you can ignore this step.
To run Pyright, install it first:
$ pip3 install --user pyright
Then run it using:
$ make typecheck
I’m using the tox automation framework for a series of unit API tests.
The main code driving the tests is in test/test_core.py
; the main tox configuration file is
tox.ini
.
These are not simple unit tests, but unit API tests running against a live cPanel instance. To run the tests, you need access to a cPanel instance running on another host reachable from the host you’re running the tests on.
To set the remote hosts credentials, make a copy of the provided cpanelrc.test.example
file
and name it cpanelrc.test
(keep in the test
directory):
$ cp test/cpanelrc.test.example test/cpanelrc.test
Then edit cpanelrc.test
and set:
- The hostname of your cPanel instance
- The username of your cPanel account
- An API token associated to that username
Token-based authentication is the only supported authentication method.
To run the tests, use:
$ make test
The above command will hit the cPanel UAPI REST interface with most of the functions
implemented in cpanel-cli
. The remote state of cPanel is left unchanged, i.e.,
the tests are strictly non-destructive.
Packaging is done via good old setup.py
, which is the main script used as a backend for setuptools.
This script is called indirectly via python -m build
. (I will probably replace it with
a more modern pyproject.toml
soon.)
To run the packager, use:
$ make package
The above command should generate the following two distribution files in the temporary dist
directory:
cpanel_cli-<version>-py3-none-any.whl
cpanel-cli-<version>.tar.gz
where <version>
is the release number set in cpanel/__init__.py
.
The tarball is the source archive; the wheel file is the built distribution archive. These files are ready to be uploaded to the Python Package Index.
The API documentation source files are in the doc
directory. These comprise reStructuredText
(.rst
) files which are processed using Sphinx into groups of static HTML trees.
To build the documentation, use:
$ make doc
The above command will generate several static HTML trees in doc/build/html
.
For example, it generates the default English documentation in doc/build/html/en
—
the start page is a conventional index.html
file.
This GitHub repository is currently connected to my Read the Docs account, so that any committed (or merged) change that updates the documentation sources will automatically trigger a remote Sphinx rebuild. The resulting updated HTML documentation will always be available at https://cpanel-cli.readthedocs.io/en/latest/
The main configuration file for Sphinx is doc/conf.py
. The Sphinx version and theme used
to build the documentation are in doc/requirements.txt
.
The English language *.rst
files in doc
are the source documentation files. Any
translation is based on these documents. Translation is done on a string-by-string basis,
using the original English string as a key (msgid
), and the corresponding translated
string as a value (msgstr
). For example, for Spanish:
msgid "To be, or not to be, that is the question" msgstr "Ser o no ser, he ahí el dilema"
These msgid
and msgstr
pairs are kept in a catalog file (*.po
), which is a
simple text file. These catalog files are stored in the doc/locale
subdirectory.
I personally maintain a Spanish translation of the documentation in catalog files
doc/locale/es/LC_MESSAGES/*.po
.
Catalog .po
files are compiled into .mo
files using the Sphinx internationalization
utility. These compiled .mo
files are later used to compose translated versions when
Building the documentation.
To add a new translation:
Create a new catalog using:
$ make locale iso=<language code>
where
<language code>
is the ISO 639-1 code corresponding to the new language. For example, to add a French translation you would use:$ make locale iso=fr
This would add a new
locale/fr/LC_MESSAGES/index.po
directory with several.po
files in it.Edit the
.po
files created in step 1 and insert the translated strings asmsgstr
fields. For example:msgid "Indices and tables" msgstr "Indices et tableaux"
Rebuild the documentation:
$ make doc
The above command will create a new static HTML tree in
doc/build/html/<language code>
. For example, for French, it will create a new tree indoc/build/html/fr
.
if you edit the original doc/*.rst
source documentation files, you need to update the
translations as well:
Run the following to update the catalog files:
$ make locale iso=<language code>
where
<language code>
is the ISO 639-1 code. You need to run it for every translated language.The previous step will emit a report telling you which
.po
files need to be updated, for example:Update: doc/locale/es/LC_MESSAGES/reference.po +5, -2 Update: doc/locale/es/LC_MESSAGES/contributing.po +9, -0
Open the mentioned
.po
files and edit or add newmsgstr
strings. Be advised that some entries might get annotated as#, fuzzy
, which means the internationalization engine is not sure if there already exists a translation for the entry because of similarities with another entry. Just edit themsgstr
text and delete thefuzzy
line.
For further information, see the Internationalization Guide
Para contribuir, simplemente haga un fork de este repositorio, inicie una nueva rama y abra un pull request.
cpanel-cli
está escrito en Python 3.9. He organizado el código en un árbol estándar:
cpanel-cli ├── CONTRIBUTING.rst ├── cpanel │ ├── cli.py │ ├── core.py │ ├── __init__.py │ └── __main__.py ├── doc │ ├── conf.py │ ├── index.rst │ ├── locale │ │ └── es │ │ └── LC_MESSAGES │ │ └── index.po │ └── requirements.txt ├── LICENSE ├── Makefile ├── README.rst ├── .readthedocs.yaml ├── requirements-dev.txt ├── requirements.txt ├── setup.py ├── test │ ├── cpanelrc.test.example │ └── test_core.py └── tox.ini
cpanel-cli
contiene el código fuente principal.
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
.
.readthedocs.yaml
es un archivo de configuración para Read the Docs. El sistema remoto
de construcción de Sphinx utiliza este archivo.
La traducción al español de la documentación se genera usando cadenas de un archivo de catálogo
locale/es/LC_MESSAGES/index.po
.
Uso un Makefile
para automatizar las fases del ciclo de vida del desarrollo. (Make y los Makefiles son increíbles.)
requirements-dev.txt
contiene los paquetes necesarios para el Entorno de desarrollo de Python;
requirements.txt
contiene las dependencias de ejecución.
setup.py
es el script principal de setuptools, utilizado para empaquetar y distribuir este proyecto.
Sé que actualmente se desaconseja el uso de setup.py
, así que probablemente lo reemplace con un sistema
de empaquetado más moderno como Poetry, pero por ahora sigo usando setup.py
.
(Aunque sigo la recomendación de llamarlo indirectamente usando python -m build
.)
test
contiene un conjunto de pruebas unitarias de la API. Están escritas usando el framework de automatización tox.
El código que realiza las pruebas está en test/test_core.py
; el archivo de configuración principal de tox es tox.ini
.
Nótese que no se trata de pruebas unitarias independientes simples, sino de pruebas de API que se ejecutan
contra una instancia activa de cPanel. Vea Ejecución de pruebas más abajo para más detalles.
cpanel-cli
se desarrolló en Ubuntu Linux 21.10 “Impish Indri”. No hay
requisitos especiales, así que cualquier distribución de Linux o versión de macOS que soporte al
menos Python 3.9 debería funcionar.
En macOS “Catalina” o superior
Instale Python 3.9:
$ brew install python@3.9
Luego agregue lo siguiente al PATH
:
PATH="$PATH:/usr/local/opt/python@3.9/Frameworks/Python.framework/Versions/3.9/bin"
export $PATH
Instale GNU Make:
$ brew install make
En Ubuntu Linux 21.04 o superior
Instale Python 3.9:
$ sudo apt install python3.9 python3-pip python3.9-venv
GNU Make está instalado por defecto en Ubuntu. Compruebe su disponibilidad utilizando:
$ make --version
Otras distribuciones de Linux
Use el gestor de paquetes de su distribución para instalar Python 3.9 (o superior) y GNU Make.
Para construir e instalar localmente el paquete cpanel-cli
use:
$ make install
Esto hace lo siguiente:
- Crea un nuevo entorno virtual de Python 3 en un directorio
venv
- Instala en éste los paquetes de desarrollo listados en
requirements-dev.txt
- Construye un paquete local de
cpanel-cli
Para ejecutar el utilitario desde el paquete instalado localmente, primero active el entorno virtual (sólo hay que hacerlo una vez por sesión):
$ source venv/bin/activate
Luego puede ejecutar el utilitario cpanel
:
$ cpanel --help
Si edita las fuentes, simplemente ejecute make install
para construir y reinstalar el paquete local.
Las fuentes de Python están en el directorio cpanel
. Nótese que tienen anotaciones de sugerencias de tipos,
las cuales uso porque, en mi opinión, añaden claridad y robustez al código Python. Lea la
Guía de verificación de tipos de Python para una buena introducción.
Dado que las sugerencias de tipo no son verificadas por el propio Python, se necesita un utilitario especial: un verificador de tipos. (Éste es como otra clase de linter.) Mi verificador de tipos preferido para Python es Pyright.
La ejecución del verificador de tipos es opcional; se puede ignorar este paso.
Para ejecutar Pyright, primero instálelo:
$ pip3 install --user pyright
Luego ejecútelo usando:
$ make typecheck
Uso el framework de automatización tox para una serie de pruebas unitarias de la API.
El código principal de las pruebas está en test/test_core.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 activa de cPanel. Para ejecutar las pruebas necesita conectarse a una instancia de cPanel instalada en otro host accesible desde el host donde ejecuta las pruebas.
Para establecer las credenciales del host remoto, haga una copia del archivo
cpanelrc.test.example
y llámelo cpanelrc.test
(guárdelo en el directorio test
):
$ cp test/cpanelrc.test.example test/cpanelrc.test
Luego edite cpanelrc.test
y establezca:
- El nombre de host de su 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 utilice:
$ make test
El comando anterior acceda a la interfaz REST UAPI de cPanel con la mayoría de las funciones
implementadas en cpanel-cli
. El estado remoto de cPanel se deja sin cambios, es decir,
las pruebas son estrictamente no destructivas.
El empaquetado se realiza a través del tradicional setup.py
, que es el script principal
utilizado como backend para setuptools.
Este script se invoca indirectamente a través de python -m build
. (Probablemente lo sustituya por
un pyproject.toml
más moderno en un futuro cercano).
Para ejecutar el empaquetador utilice:
$ make package
El comando anterior debería generar los siguientes dos archivos de distribución en el directorio temporal dist
:
cpanel_cli-<versión>-py3-none-any.whl
cpanel-cli-<versión>.tar.gz
donde <versión>` es el número de versión establecido en ``cpanel/__init__.py
.
El tarball es el archivo de fuentes; el archivo wheel es el archivo de distribución. Estos archivos generados se pueden subir al Python Package Index.
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/latest/
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
.
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
.
Personalmente mantengo una traducción al español de la documentación 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.
Para añadir una nueva traducción:
Cree un nuevo catálogo:
$ make locale iso=<código de idioma>
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
Esto añadiría un nuevo directorio
locale/fr/LC_MESSAGES
con varios archivos.po
.Edite los archivo
.po
creados en el paso 1 e inserte las cadenas traducidas como camposmsgstr
. Por ejemplo:msgid "Indices and tables" msgstr "Indices et tableaux"
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 endoc/build/html/fr
.
Si se edita el texto de los archivos de documentación originales doc/*.rst
, también hay
que actualizar las traducciones:
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.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 cadenasmsgstr
. 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 demsgstr
y eliminar la líneafuzzy
.
Para más información consulte la Guía de internacionalización.