django-squirrell-materialize 1.4

A Docker and AWS utility package

Guía de los Paquetes de Python (PIP)

Estos paquetes nos permiten instalar los proyectos que deseemos con un simple comando. Tenemos dos formas de compartir dichos paquetes, dependiendo de si lo queremos publicar para todo el mundo o de forma privada. Si lo subimos a su propio repositorio oficial: PyPi los archivos serán completamente públicos. Por lo que si queremos mantener nuestro paquete privado debemos utilizar cualquier via que nos permita almacenar el directorio, como GitHub con un repositorio privado.

1. Registrarnos en PyPi

Si queremos compartirlo de forma pública tenemos que registrarnos aquí. Este repositorio nos permitirá almacenar las diferentes versiones del proyecto.

2. Herramientas necesarias

Tenemos que comprobar que tenemos Python y Pip instalado.

python -V  # para python version (2/3)
python -m pip --version

De no estar instalados no podremos continuar, así que instálalos de no tenerlos.

Instalamos los paquetes necesarios, teniendo en cuenta de que si tenemos diferentes librerias de Python en el sistema tenemos que instalarle los paquetes a la que vayamos a usar posteriormente. Simplemente indicándole sudo phyton3 -m pip install ... sustituyendo el 3 por la versión que queramos.

• Setuptools: Setuptools se utiliza para crear y distrubuir los paquetes de Python.
• Wheel: El paquete Wheel nos permite realizar el comando bdist_wheel que crea el archivo ejecutable .whl, pip install se encarga de su ejecución.
• Twine: El paquete Twine nos aporta una conexión segura para subir los archivos a PyPi.
• Tqdm: Es usado internamente por Twine.

sudo python -m pip install --upgrade pip setuptools wheel
sudo python -m pip install tqdm
sudo python -m pip install --user --upgrade twine

Al indicarle --user tenemos que cercionarnos posteriormente de usar siempre los comandos con permisos sudo, de lo contrario no funcionarán y tampoco nos arrojará un error descriptivo.

3. Creación del proyecto

Creamos un directorio para nuestro paquete, en este ejemplo se va a llamar paquete_pkg, el nombre de este directorio no va a una vez que esté subido, así que mientras maś descriptivo mejor.

Ahora entramos en nuestro directorio y creamos un archivo vacio que será nuestro script. A nuestro script lo vamos a llamar hola.

cd paquete_pkg

touch hola

Ahora abriremos hola.

nano hola

Y le añadimos solo un par de líneas:

#!/usr/bin/env python3

echo "hey there, this is my first pip package"

Una vez guardado, vamos a hacerlo ejectuable: chmod +x hola

Lo siguiente es crear el archivo setup.py touch setup.py

Y le añadimos toda la información del paquete:

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()


setuptools.setup(
     name='nombre de nuestro paquete',  
     version='0.1',
     scripts=['hola'] ,
     author="Deepak Kumar",
     author_email="[e-mail]",
     description="A Docker and AWS utility package",
     long_description=long_description,
   long_description_content_type="text/markdown",
     url="https://github.com/javatechy/dokr",
     packages=setuptools.find_packages(),
     include_package_data=True,
     zip_safe=True,
     classifiers=[
         "Programming Language :: Python :: 3",
         "License :: OSI Approved :: MIT License",
         "Operating System :: OS Independent",
     ],
 )

El nombre que le demos más arriba será el nombre con el que se subirá.

4. Compilar el paquete

Vamos a la carpeta de nuestro proyecto y ejecutamos python setup.py bdist_wheel. Esto creará la toda la estructura del paquete.

5. Instalar en local

Si queremos comprobar su funcionamiento lo instalamos localmente así: python -m pip install dist/hola-0.1-py3-none-any.whl

Recuerda usar la versión de Python en la que has instalado todo lo anterior.

6. Subir el pip

1. Creamos el archivo .pypirc en nuestro directorio principal.

   • Para Windows: C:\Users\UserName\.pypirc
   • Para Linux: ~/.pypirc

2. Añadimos el siguiente contenido al archivo y reemplazamos usuario con nuestro nombre de usuario.

[distutils] 
index-servers=pypi
[pypi] 
repository = https://upload.pypi.org/legacy/ 
username =usuario

3. Finalmente, para subir nuestro paquete usamos Twine: python -m twine upload dist/*

Si queremos instalar dicho paquete simplemente hacemos: pip install nombredelpaquete

7. Actualizar nuestro paquete

Abrimos nuestro setup.py y aumentamos su versión. Ejemplo: version='0.1' -> version='0.2'. Podemos aumentar su versión cómo queramos, es decir, podemos añadirle otro decimal.

Abrimos la terminal en nuestro paquete y ejecutamos python setup.py sdist para que actualice el paquete con los nuevos cambios.

Volvemos a subir nuestro paquete con: python -m twine upload dist/*

Añadir archivos No Python

Si queremos añadir a nuestro paquete archivos que no sean de Python tenemos que crear un archivo MANIFEST.in en la raíz de nuestro paquete. Nuestro archivo de ejemplo queda así:

include MANIFEST.in
graft templates
graft static
global-include *.html *.js *.css

• include -> se utiliza para indicar qué archivo y/o tipo de archivo incluye.
• global-include -> incluye todos los archivos listados.
• graft -> incluye todos los archivos de la carpeta que elijamos.

Cosas importantes

• Si tenemos problemas a la hora de subir una nueva versión y nos indica que esa versión ya existe, entramos en dist/ y borramos las versiones anteriores.
• Si borramos el paquete en el repositorio oficial ese repositorio desaparece y se convierten en inutilizable.
• Los subdirectorios que se queramos que se instalen tienen que llevar el archivo __init__.py. De lo contrario, al instalarlo en el entorno virtual no lo traera.

El último punto hay que comprobar si hay que añadirlo a todas las carpetas o solo a la primera.

Enlaces de referencia

• Build Your First pip Package.
• PyPI How to upload a new version.
• Adding Non-Code Files.
• Creating a Source Distribution.