Movimiento Libre

Plataforma de divulgación de conocimiento libre por Ing. Guillermo Valdés Lozano (guivaloz)

Python Package Index (PyPI): primeros pasos

PyPI es el repositorio de paquetes de Python por excelencia. En este apunte están los pasos para preparar software que se instale con pip.

En este apunte se usa pypi_primeros_pasos como el nombre del paquete; debe cambiarlo por el nombre que vaya a usar.

Crear un nuevo repositorio en GitHub

Un buen punto de partida y futuro home de su paquete es hacer un nuevo repositorio en GitHub (o el servicio git que prefiera). Luego de crearlo baje una copia con las siguientes órdenes; sustituya USUARIO por su cuenta.

$ mkdir -p ~/Documentos/GitHub/USUARIO
$ cd ~/Documentos/GitHub/USUARIO
$ git clone git@github.com:USUARIO/pypi_primeros_pasos.git
$ cd pypi_primeros_pasos

Crear la estructura para el paquete

Prepare los directorios y archivos en la copia local de su repositorio así:

pypi_primeros_pasos
 |- LICENSE
 |- README.md
 |- ejemplo
 |   |- __init__.py
 |- setup.py
 |- tests

Donde LICENCE tiene el texto con la licencia de software y README.md una breve semblanza de lo que hace el paquete.

Debe crear el directorio tests para colocar pruebas; por el momento puede estar vacío.

$ mkdir tests

Edite el setup.py como en este ejemplo...

import setuptools

with open('README.md', 'r') as puntero:
    long_description = puntero.read()

setuptools.setup(
    name='pypi_primeros_pasos',
    version='0.1',
    author='Su nombre completo',
    author_email='correo@ejemplo.com',
    description='Una línea que lo describa.',
    long_description=long_description,
    long_description_content_type='text/markdown',
    url='https://github.com/USUARIO/pypi_primeros_pasos',
    python_requires='>=3.6',
    classifiers=[
        'Programming Language :: Python :: 3',
        'License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)',
        'Operating System :: POSIX :: Linux',
    ],
    packages=setuptools.find_packages(),
    include_package_data=True,
    install_requires=[
        'paquete_dependencia_1',
        'paquete_dependencia_2',
        'paquete_dependencia_3',
    ],
)

Los principales valores a declarar son...

  • name: el nombre único del paquete
  • version: número de versión
  • author: su nombre completo
  • author_email: dirección de correo electrónico
  • description: explique en una oración de que se trata
  • long_description: una descripción más larga que se cargará desde README.md
  • url: el repositorio público (puede ser de GitHub) donde encontrarlo
  • classifiers: metadatos que describen el lenguaje, la licencia y el sistema operativo
  • include_package_data: ordena que se incluyan archivos que no son parte ejecutable
  • install_requires: otros paquetes que se requieren instalar

Crear un entorno virtual Python 3

Prepare un entorno vitual Python 3 donde colocaremos el código del paquete así como los directorios y archivos para que se haga la entrega a PyPI. Recomiendo tenerlo por separado de la copia del repositorio; para este ejemplo uso PyPIPrimerosPasos.

$ mkdir ~/VirtualEnv
$ cd ~/VirtualEnv
$ virtualenv -p python3 PyPIPrimerosPasos
$ cd PyPIPrimerosPasos/
$ . bin/activate

Registro en Test PyPI

Ya sea para aprender o para poner a prueba su paquete use el servicio Pruebas de PyPI: https://test.pypi.org/. CUIDADO: Tenga en cuenta que Test es efímero, porque va eliminando las entregas más antiguas. Solicite su registro; le pedirá su nombre, correo electrónico, usuario y contraseña dos veces. Luego deberá confirmar su correo electrónico.

NOTA: Más adelante regístrese en PyPI https://pypi.org/; allí debe de repetir todo proceso de registro; por lo que las contraseñas y las llaves API deberán ser diferentes.

Genere una llave API de Test PyPI

En Account settings > API tokens de clic en Add API token

Escriba un nombre para la llave, le recomiendo que sea relativo al equipo donde la vaya a usar. Para que interactúe con todos sus paquetes elija Entire account (all projects). Luego de click Add token.

El token estará visible solo en esta ocasión; de clic en Copy token y NO cierre esa pestaña del navegador de internet hasta haberla guardado.

Prepare el archivo .pypirc para guardarlo; debe estar en su HOME...

$ nano -w ~/.pypirc

Y péguelo como password en un nuevo archivo como lo siguiente...

[testpypi]
username = __token__
password = pypi-xxxxxxxxxxxxxxxx...

Ya guardado puede cerrar la pestaña del naveador de internet con el token.

NOTA: Cuando tenga el registro en PyPI podrá repetir el proceso para generar la llave API para esa cuenta y agregarla al mismo archivo .pypirc de esta forma...

[pypi]
username = __token__
password = pypi-xxxxxxxxxxxxxxxx...

Generar los archivos para su distribución

Cámbiese al directorio donde está la copia local del repositorio

(PyPIPrimerosPasos) $ cd ~/Documentos/GitHub/USUARIO/pypi_primeros_pasos

Verifique que tenga setuptools y wheel instalados

(PyPIPrimerosPasos) $ pip list

Genere los archivos para distribuir con...

(PyPIPrimerosPasos) $ python3 setup.py sdist bdist_wheel

Esa orden creará el directorio dist que contiene un comprimido con los archivos del paquete.

Subir el paquete

Instale twine en este entorno...

(PyPIPrimerosPasos) $ pip install twine

Suba el paquete ejecutando...

(PyPIPrimerosPasos) $ python3 -m twine upload --repository testpypi dist/*

NOTA: En repository use testpypi para Test PyPI. En cambio para PyPI use pypi.

Verifique que puede ver su nuevo paquete en el navegador de internet con la URL que aparece.

Abandone el entorno virtual con...

(PyPIPrimerosPasos) $ decativate

Probar la descarga

Elabore un nuevo entorno virtual

$ cd ~/VirtualEnv
$ virtualenv -p python3 PruebaPyPIPrimerosPasos
$ cd PruebaPyPIPrimerosPasos/
$ . bin/activate

Instale su nuevo paquete desde Test PyPI con

(PruebaPyPIPrimerosPasos) $ pip install pypi_primeros_pasos

Referencias