El objetivo de este tutorial es guiarte paso a paso en el proceso de creacin y publicacin de tu propia librera en Python. Aunque Python ofrece una biblioteca estndar muy completa, aprovechar las contribuciones de la comunidad en PyPI te permite extender sus capacidades y crear soluciones personalizadas que se adapten a tus necesidades.
La motivacin detrs de este proyecto es doble: por un lado, adquirir un conocimiento profundo sobre el proceso de preparacin, versionado, construccin y despliegue de paquetes; y por el otro, consolidar un repositorio centralizado de herramientas que funcione como una tarjeta de presentacin profesional en el mundo del desarrollo.
https://github.com/rafnixg/rafnixg-lib
🧭 Introduccin y primeros pasos
El primer paso es comprender el ecosistema de paquetes en Python, especialmente el rol fundamental que juega PyPI (Python Packaging Index). Este es el repositorio oficial de paquetes de Python, y alberga una vasta coleccin de libreras, desde implementaciones simples hasta complejas soluciones en reas como ciencia de datos, inteligencia artificial y desarrollo web.
Al entender cmo se organizan y distribuyen los paquetes en PyPI, puedes orientar el desarrollo de tu librera para que cumpla con los estndares que facilitan su instalacin y uso por parte de otros desarrolladores. Adems, al prepararla para su publicacin, te adentras en prcticas modernas como el versionado semntico y la automatizacin del despliegue.
Nuestro inicio en el mundo de las libreras lo vamos a tener en la prxima seccin donde ya iniciaremos el cdigo fuente que usaremos como base para todo el proceso de tener nuestra propia librera en PyPI.
https://pypi.org/project/rafnixg/
🏗 Crear la base de tu librera en Python
En esta seccin crearemos el cdigo base que usaremos para subir a PyPI, t puedes usar este cdigo como ejemplo o ser libre de usar el cdigo de tu preferencia, y saltar a la siguiente seccin.
Si te quedaste ac el paquete que vamos a crear se llama rafnixg y muestra por consola tus datos personales y por otro lado podr ser usado en tu propio cdigo para descargar post de tu blog de HashNode usando GraphQL. Este es bsicamente mi caso de uso de ejemplo, pero tu librera puede tener las funciones que tu consideres necesarias.
Para lograr obtener este diseo de card vamos a hacer uso de la librera rich que nos ayuda a crear diseos de tablas para la terminal de forma fcil, los invito a revisar el potencial de rich, puede agregar iconos, gestionar paleta de colores, Markdown.
https://pypi.org/project/rich/
🧪Preparacin del entorno de desarrollo
Para este caso hare uso de VSCode pero puedes usar el editor que prefieras, ac lo importante es crear un entorno virtual de Python para aislar las dependencias y no tener problemas en el futuro.
$ python -m venv env$ source env/bin/activate # Para Linux$ env\Scripts\activate # Para Windows(env) $ pip install rich
Lo segundo ser crear un archivo .gitignore que nos ayudar a indicar que no queremos que se suba a nuestro repositorio, podemos hacer uso de la siguiente web para generar uno con la configuracin para Python.
Create Useful .gitignore Files For Your Project
# Created by https://www.toptal.com/developers/gitignore/api/python# Edit at https://www.toptal.com/developers/gitignore?templates=python### Python #### Byte-compiled / optimized / DLL files __pycache__ /*.py[cod]*$py.classenv.env/venvvenv# End of https://www.toptal.com/developers/gitignore/api/python
Debemos recordar que es importante evitar subir archivos con contenido sensibles como API Keys, Claves o algn tipo de informacin que permita acceso no autorizado.
Luego de esto inicializamos nuestro repositorio de git y creamos nuestra estructura de archivos.
(env) $ git init
📁 Estructura del proyecto
Toda librera de Python inicia dentro de una carpeta, as que para esto cree el directorio rafnixg-lib y dentro creo la siguiente estructura de archivos:
rafnixg-lib/ src/ rafnixg/ __init__.py __main__.py rafnixg.py LICENSE README.md pyproject.toml
Todo el cdigo fuente se encuentra de src/ esto no es obligatorio, pero es una buena prctica. Si estas usando tu propio cdigo, dentro de src/ es donde debera ir para mantener la mejor estructura.
En esta seccin nos enfocaremos en los archivos de Python y en las siguientes secciones veremos estos archivos especiales LICENSE, README.md, pyproject.toml.
🧾 Crear el archivo principal src/rafnixg/rafnixg.py
"""src/rafnixg/rafnixg.pyRafnixG - Personal Card"""from rich.console import Consolefrom rich.table import Tableclass RafnixG: """RafnixG - Personal Card""" def __init__ (self): self.username = "rafnixg" self.name = "Rafnix Guzmn" self.position = "Python Software Developer" self.links = "https://links.rafnixg.dev" self.web = "https://rafnixg.dev" self.blog = "https://blog.rafnixg.dev" self.cv = "https://resume.rafnixg.dev" self.github = "https://github.com/rafnixg" self.twitter = "@rafnixg" self.about = "Experienced software developer with 10+ years of expertise in designing, developing and implementing web systems across various sectors. Backend specialist skilled in Python, Linux, and Git. Passionate about continuous learning and open-source technology." def __str__ (self): return f"{self.name} (@{self.username}) - {self.position}" def display(self): """Display personal card""" # Crea un objeto Console para imprimir en la consola console = Console() table = Table( show_header=False, # No mostrar encabezados title=str(self), # Ttulo de la tabla highlight=True, # Resaltar la tabla title_style="bold magenta", # Estilo del ttulo ) # Agrega columnas a la tabla table.add_column("Attribute", style="bold", width=16) table.add_column("Value") # Agrega filas a la tabla con los atributos y valores de la clase # Itera sobre los atributos de la clase y los agrega a la tabla for key, value in self. __dict__.items(): if isinstance(value, dict): for sub_key, sub_value in value.items(): table.add_row(sub_key, ", ".join(sub_value)) elif isinstance(value, list): table.add_row(key, ", ".join(value)) else: table.add_row(key, value) # Imprime la tabla en la consola console.print(table)
🧩 Inicializar el paquete con src/rafnixg/__init__.py
"""src/rafnixg/ __init__.pyRafnixG - Personal Card"""from rafnixg.rafnixg import RafnixG __version__ = "1.0.0"
🧩 Ejecutar como modulo con src/rafnixg/__main__.py
"""src/rafnixg/ __main__.pyRafnixG - Personal Card"""from rafnixg import RafnixGdef main(): """Main function.""" me = RafnixG() me.display()if __name__ == ' __main__': main()
🖥 Ejecutar y probar tu cdigo localmente
Para probar nuestro cdigo debemos movernos a la carpeta src/ y luego correr el paquete como un mdulo de Python:
(env) $ cd src(env) $ ls rafnixg/(env) $ python -m rafnixg
Recuerda que si estas usando tu cdigo aqu debes colocar el nombre la carpeta que contiene tu cdigo fuente.
📦 Preparar la librera para ser publicada
📘Documentando nuestra librera
Un README es esencial para cualquier proyecto ya que aqu es donde otros desarrolladores y usuarios obtendrn informacin sobre tu librera, en este archivo no solo se explica que es y lo que hace tu proyecto, sino que tambin contiene informacin de como instalarlo, utilizarlo y contribuir. En una prxima publicacin profundizaremos ms sobre el README y que debera contener, por los momentos creamos el archivo README.md con el siguiente contenido:
# Rafnix Guzmn - Personal Card (README.md)## Hi there 👋This is my personal card [rafnixg.dev](https://rafnixg.dev)## How to use it? 🤔Install using pip:```
bashpip install rafnixg
```Then run it:```
bashrafnixg
### 🛠Configurar el sistema de construccin (build system)
Para preparar nuestra librera para ser publicada en **_PyPI_** necesitamos configurar algunas secciones en el archivo `pyproject.toml` primero debemos indicar el **build system** que es la parte responsable de crear los archivos que se suben a PyPI, usualmente se usa el formato **wheel** o **sdist**.
Nosotros usaremos el [setuptools](https://setuptools.pypa.io/) como **build system.**
```toml
# pyproject.toml[build-system]requires = ["setuptools>=61.0.0", "wheel"]build-backend = "setuptools.build_meta"
🗂 Organizar el archivo pyproject.toml
Ahora agregaremos una seccin para configurar informacin del proyecto, ac es donde indicaremos el nombre de nuestro paquete, recordemos que debemos verificar que el nombre no este usado por ningn otro paquete dentro del ecosistema PyPI.
# pyproject.toml...[project]name = "rafnixg"version = "1.0.0"description = "Rafnix Guzman Personal Card"readme = "README.md"authors = [{ name = "Rafnix Guzman", email = "rafnixg@gmail.com" }]license = { file = "LICENSE" }classifiers = ["License :: OSI Approved :: MIT License", "Programming Language :: Python", "Programming Language :: Python :: 3",]keywords = ["personal card", "console"]dependencies = ["rich",]requires-python = ">=3.9"[project.optional-dependencies]dev = ["black", "bumpver", "isort", "pip-tools", "pytest"][project.urls]Homepage = "https://github.com/rafnixg/rafnixg-lib"[project.scripts]rafnixg = "rafnixg. __main__ :main"
No toda esta informacin es obligatoria, pero es importante dar la mayor cantidad de informacin posible sobre nuestra librera, la informacin mnima que podemos ingresar es
nameyversion.
Las siguientes secciones son importantes por la informacin que le proporcionan a PyPI:
classifiers: Lista de classifiers de PyPI que ayudan a la bsqueda.keywords: Lista de etiquetas que seran usadas para identicar y categorizar la libreria.dependencies: Lista de dependencias que tu librera necesita, en nuestro caso rich.project.optional-dependencies: Lista de las dependencias de desarrollo.project.urls: Links que relacione a tu proyecto en github o alguna pgina web.project.scripts: Punto de entrada para tu librera. en este caso el comando serrafnixgy el punto de entrada serrafnixg. __main__ :main
Toda esta informacin hace que en PyPI tu librera se vea mucho mejor y cuando se haga una bsqueda tambin sea ms fcil de encontrar. ac un ejemplo de la informacin que se muestra en PyPI :
Vemos como tambin usa el archivo README.md para mostrar del lado derecho la documentacin de la librera en PyPI , y los datos del archivo pyproject.toml tambin se muestran a la izquierda.
Para saber ms sobre este archivo de configuracin ac esta la documentacin.
🔢 Usar versionamiento semntico
Toda librera debe tener un versionamiento para poder tener un control de lo que se publica, existen diferentes esquemas de versionamiento, en nuestro caso usaremos Semantic Versioning que es una forma simple de gestionar el versionamiento formado por 3 grupo de nmeros, ejemplo: MAJOR.MINOR.PATCH las recomendaciones para cambiar estos nmeros son:
MAJOR : Cuando tus cambios son tan grandes que rompen tu API anterior.
MINOR : Cuando agregas nuevas funciones y todo se mantiene compatible, Vuelve a 0 cuando MAJOR cambia.
PATCH : Cuando agregas bug fixes, vuelve a 0 cuando MINOR cambia.
Para gestionar esto en Python haremos uso de una librera llamada bumpver esto modifica directamente los archivos y as mantiene sincronizado en todos lados la versin.
(venv) $ python -m pip install bumpver(venv) $ bumpver initWARNING - Couldn't parse pyproject.toml: Missing version_patternUpdated pyproject.toml
Este comando inicializa en pyproject.toml la gestin de las versiones, si vemos agrego una nueva seccin:
[tool.bumpver]current_version = "1.0.0"version_pattern = "MAJOR.MINOR.PATCH"commit_message = "bump version {old_version} -> {new_version}"commit = truetag = truepush = false[tool.bumpver.file_patterns]"pyproject.toml" = ['current_version = "{version}"', 'version = "{version}"']"src/rafnixg/ __init__.py" = ["{version}"]
Si no se parece a esta ajustar el version_pattern para que sean iguales, despus de configurar esto, t puedes cambiar la versin usando los comandos de bumpver:
(venv) $ bumpver update --minorINFO - Old Version: 1.0.0INFO - New Version: 1.1.0INFO - git commit --message 'bump version 1.0.0 -> 1.1.0'INFO - git tag --annotate 1.1.0 --message '1.1.0'
📜 Elegir una licencia adecuada
Cuando creamos una librera debemos elegir que permisos queremos que los dems tengan sobre nuestro cdigo, as se podr saber qu es lo que quiere que se haga o no con tu librera. Una licencia muy usada para compartir cdigo es la Licencia MIT con esta licencia simple y bastante permisiva.
Lo que debemos hacer es crear un archivo de texto llamado LICENSE que contenga el texto de nuestra licencia, si no sabes que licencia escoger existe esta web que permite ver cul es la ms conveniente segn tus necesidades: Choose an open source license
📥 Instalar tu librera localmente
Para este punto ya tenemos nuestra librera lista para ser publicada, ahora lo que vamos a necesitar hacer es probar nuestra librera instalndola directamente en nuestro entorno virtual, para esto haremos uso de los siguientes comandos:
(env) $ python -m pip install -e .
Con el flag -e se instala tu librera en modo editable y con . indicamos donde se encuentra el archivo pyproject.toml esto ya deja disponible nuestro comando rafnixg que est definido en la seccin project.scripts indicando el punto de entrada.
(env) $ rafnixg Rafnix Guzmn Garcia (@rafnixg) - Python Software Developer username rafnixg name Rafnix Guzmn Garcia position Python Software Developer links https://links.rafnixg.dev web https://rafnixg.dev blog https://blog.rafnixg.dev cv https://resume.rafnixg.dev github https://github.com/rafnixg twitter @rafnixg about Experienced software developer with 10+ years of expertise in designing, developing and implementing web systems across various sectors. Backend specialist skilled in Python, Linux, and Git. Passionate about continuous learning and open-source technology.
🚀 Publica tu librera a PyPI
Ya nuestra librera se encuentra lista y a la espera de conocer el mundo, en esta seccin haremos el empaquetado y despliegue a PyPI.
🧑💻 Crear cuentas en PyPI y TestPyPI
Lo primero que debemos tener es una cuenta en PyPI , as que si no la tienes este es tu momento de registrarte: https://pypi.org/account/register/
Tambin deberamos crear una cuenta en el ambiente de pruebas de PyPI , as siempre podemos verificar que todo va bien antes de lanzar algo a produccin: https://test.pypi.org/account/register/
Recuerden crear sus API Key porque en el proceso de publicacin mas adelante sern necesarias.
🔐 Generar una API Key
Para esto ingresamos a Configuracion de la cuenta bajamos y buscamos la opcin Fichas de API , hacemos clic en el botn Aadir ficha de API
Luego le ponen algn nombre descriptivo a esta Key , seleccionamos el Alcance y por ltimo clic al botn Create Token
Con esto nos mostrara nuestra API Key que siempre empieza por pypy- como se muestra en la imagen de abajo:
Hacemos clic en Copiar Ficha y guardamos nuestra API Key en algn lugar seguro**.** Siempre van a tener la posibilidad de borrar la key y generar otra si es necesario la pierden.
🚩
Nunca debemos compartir la API Key o agregarla directamente a un archivo que pueda estar trackeado en GIT.
Luego de todo esto debemos instalar 2 libreras que nos ayudaran a construir y publicar nuestro paquete:
(env) $ python -m pip install build twine
🛠 Construir el paquete con build
Ahora que tenemos nuestra librera lista, ya podemos hacer la distribucin del cdigo a PyPI , para esto primero debemos empaquetar nuestra librera en formato wheels , un formato que consiste en empaquetar en un archivo tar todo el cdigo fuente de la librera. Para crear este archivo haremos uso de la librera build:
(env) $ python -m build[...]Successfully built rafnixg-1.0.0.tar.gz and rafnixg-1.0.0-py3-none-any.whl
Esto nos crea una nueva carpeta llamada dist/ que contiene el archivo .tar.gz con el cdigo de nuestra librera y el archivo .whl que es nuestro archivo wheels , esto es todo lo que necesitamos para subir a PyPI.
Verificar el paquete con twine check
Para validar que todo fue empaquetado correctamente podemos usar twine:
(env) $ twine check dist/*Checking dist/rafnixg-1.0.0-py3-none-any.whl: PASSEDChecking dist/rafnixg-1.0.0.tar.gz: PASSED
Subir el paquete a PyPI
Ahora que tenemos todo listo y verificado, podemos subir a TestPyPI para ver que todo va con normalidad y no tenemos ningn error en nuestra librera:
(env) $ twine upload -r testpypi dist/*
Nos pedir nuestra API Key. Ya con esto podemos probar nuestra librera usando el siguiente comando:
(env) $ pip install -i https://test.pypi.org/simple/ rafnixg
Si todo sali con normalidad, podemos subir a l repositorio principal de PyPI :
(env) $ twine upload dist/*
Con esto tendramos nuestro proyecto ya disponible para usar con pip, podemos a PyPI y buscar nuestra librera.
https://pypi.org/project/rafnixg
📥 Instalar tu paquete desde PyPI
Ya con nuestra librera publicada en PyPI podemos usarla con el siguiente comando:
(env) $ python -m pip install rafnixg(env) $ rafnixg
🧠 Conclusiones
Crear y publicar tu propio paquete en Python es una experiencia enriquecedora que va ms all de compartir cdigo: es una oportunidad para aprender sobre la estructuracin de proyectos, el versionado semntico y las buenas prcticas de la comunidad. A lo largo de este tutorial, hemos recorrido desde la configuracin del entorno de desarrollo hasta la publicacin en PyPI , enfatizando la importancia de una documentacin clara y una estructura ordenada. Con estos conocimientos, no solo mejoras tus habilidades tcnicas, sino que tambin das un paso significativo hacia la consolidacin de tu perfil profesional en el mundo del desarrollo. Atrvete a experimentar, optimizar tu paquete y contribuir al ecosistema open source!
📰
En una prxima publicacin veremos cmo podemos crear un flujo de CI/CD con Github Actions para automatizar la publicacin de nuestra librera, tambin como documentarla y publicar con Github Pages esta documentacin. Cualquier duda o consulta djalo en la seccin de comentarios.
]]>
Top comments (0)