Empaqueta y Distribuye tus Ideas

Contribución y Publicación en PyPI

@cr0wg4n

Mauricio Serginho Matias C.

Software Libre

Es un movimiento en pro de la libertad y la justicia.
Promueve la solidaridad social: compartir y cooperar.

https://www.gnu.org/philosophy/free-sw.html

"Es cuestion de libertad, no de precio"

Las libertades del Software Libre

0. Libertad de ejecutar el programa como se desee, con cualquier propósito.

1. Libertad de estudiar cómo funciona el programa, y cambiarlo para que haga lo que se desee

2. Libertad de redistribuir copias para ayudar a otros

3. Libertad de distribuir copias de sus versiones modificadas a terceros

https://www.gnu.org/philosophy/free-sw.html

Open Source

Se centra en prácticos que una unidad de software puede aportar. En otras palabras, es pragmático.

https://opensource.org/osd

"Open Source no solo significa acceso al código fuente"

Pautas (Guidelines)

Distribución Libre
Código fuente
Trabajos derivados
Integridad del código fuente del autor
No discriminación contra personas o grupos
No discriminación en función de la finalidad perseguida
Distribución de la licencia
La licencia no ha de ser específica de un producto
La licencia no debe restringir a otro
La licencia ha de ser tecnológicamente neutral

https://opensource.org/osd

Software Libre

Movimiento en pro de la libertad y justicia
Es estricto
Atienden al código fuente, autor y usuarios

Open Source

Movimiento pragmático
Menos estricto
Solo atienden a la licencia del código fuente "y su autor"

https://www.gnu.org/philosophy/open-source-misses-the-point.es.html

Python

Python is powerful... and fast
Plays well with others
Runs everywhere
Is friendly & easy to learn
is Open.

https://www.python.org/doc/essays/blurb/

https://insights.stackoverflow.com/trends?tags=r%2Cpython%2Cjavascript%2Cjava%2Cc%2B%2B%2Cc%23

https://www.jetbrains.com/lp/python-developers-survey-2020/

Python Package Index

Es el repositorio de software para el lenguaje de programación Python. Es donde se aloja cada paquete que instalas al usar PIP (Package Installer for Python)

pip install requests

https://pypi.org/simple/requests/

C:\Users\PC\AppData\Local\Programs\Python\Python38-32\Lib\site-packages

https://dev.to/alexbecker/how-pip-install-works-323j

Crea tu propio Package o Lib📦

Requisito

Tener un propósito, probablemente exista una biblioteca similar a la tuya, asi que puedes preguntarte ¿Qué hace esa lib que la tuya no?¿Porque la tuya es mejor?, las conclusiones vienen por si solas.

Conocimientos en GIT, si de software y contribución se trata, GIT resalta por su excelencia ya que aparte de usarlo para gestionar tu código, debes mantenerlo, muchas personas pueden forkear tu repo y hacer PRs esperando contribuir a tu lado, ¡es grandioso!, por lo tanto tu destreza con GIT es importante.

Estructura tu Código

pypi-package-guide

Recupera frases celebres de un archivo de texto y muestra una frase aleatoriamente.

.gitignore

__pycache__
dist
*.egg-info
.venv

LICENSE

https://blog.usejournal.com/understanding-open-source-and-free-software-licensing-c0fa600106c9

tests/tests.py

from pypi_package_guide import Phraser
import unittest 

class Test(unittest.TestCase):

    def test_get_random_phrase(self):
        phraser = Phraser()
        phrase = phraser.get_random_phrase()
        print('\n', phrase, '\n')
        self.assertGreater(len(phrase), 0)        

if __name__ == "__main__":
    unittest.main()

python -m unittest tests.tests

Ejecutar tests:

README.md

Descripción y características (features)
Requerimientos tecnológicos
Instalación
Estado de la biblioteca: active, unmaintained, deprecated, etc.
Ejemplos de uso
Detalles extra como: formulas matemáticas, referencias a documentación externa, explicaciones del funcionamiento interno del código, entre otros
Reglas de contribución
Se escribe en el lenguaje de marcado: markdown

https://guides.github.com/features/mastering-markdown/#intro

pypi_package_guide

Si o si necesita de una __init__.py que exteriorize o exporte las funciones, clases, constantes y variables necesarias para manejar tu Lib.

from .phraser import Phraser

__init__.py

from pypi_package_guide import Phraser

phraser = Phraser()
phrase = phraser.get_random_phrase()
print('\n', phrase, '\n')

main.py

setup.py

import setuptools

with open("README.md", "r", encoding="utf-8") as description:
    long_description = description.read()

setuptools.setup(
    name="pypi-package-guide",
    version="0.0.2",
    author="Nombre de Autor",
    author_email="xxx@xxx.io",
    description="This is a PYPI package template",
    long_description=long_description,
    long_description_content_type="text/markdown",
    license='MIT',
    url="https://github.com/cr0wg4n/pypi-package-guide",
    project_urls={
        "Bug Tracker": "https://github.com/cr0wg4n/pypi-package-guide/issues",
    },
    # more classifiers: https://pypi.org/classifiers/
    classifiers=[
        'Programming Language :: Python :: 3.6',
        'Operating System :: POSIX :: Linux',
        'License :: OSI Approved :: MIT License',
        'Development Status :: 3 - Alpha',
        'Intended Audience :: Developers',
        'Topic :: Software Development :: Build Tools',
    ],
    keywords=["template", "pypi-guide", "pypi"],
    packages=["pypi_package_guide"],
    package_data={
        'pypi_package_guide': [
            'data/*.txt',
        ]
    },
    # install_requires = ['requests', 'numpy'] etc...
    install_requires=[],
    python_requires=">=3.6",
)

name, será el nombre de tu lib, es como aparecerá en PyPI la convención es usar el guion “-” como concatenador, por ejemplo: my-awesome-lib
version, por ejemplo 1.2.3
author, ahí va tu nombre de la forma que gustes.
author_email, ahí va tu correo electrónico, te recomiendo usar uno secundario.

(
  name="pypi-package-guide",
  version="0.0.2",
  author="Nombre de Autor",
  author_email="xxx@xxx.io",
  ...
)

description, será la descripción que usara PyPI para tu lib, procura que sea breve y concisa.
long_description, si lo notaste el valor que se encuentra en el ejemplo es tomado de una lectura del archivo README.md, es la descripción completa y se adhiere como un string cualquiera, PyPI tiene su propia forma de interpretarlo del lado del servidor ;D.
long_description_content_type, le dice a PyPI cual es el formato que tiene el long_description insertado, en este caso será: “text/markdown”

(
  ...
  description="This is a PYPI package template",
  long_description=long_description,
  long_description_content_type="text/markdown",
  ...
)

license, el nombre de la licencia seleccionada: MIT
url, es la URL del sitio principal o host dedicado a la documentación y explicación de tu lib, a menudo ahí se coloca la url del repositorio de tu lib.
project_urls, son URLs extra que se le puede pasar en formato de diccionario, esta es la lista completa de parámetros que admite.
classifiers, son metadatos que clasifican tu paquete, estos son algunos clasificadores extra.
keywords, son palabras claves con las que se relaciona tu proyecto es un arreglo de cadenas, por lo tanto, agrega algo como: [“web”, “machine-learning”, “robotics” ], selecciona algunos términos con los que se relacione tu proyecto.

(
  ...
  license='MIT',
  url="https://github.com/cr0wg4n/pypi-package-guide",
  project_urls={
    "Bug Tracker": "https://github.com/cr0wg4n/pypi-package-guide/issues",
  },
  # more classifiers: https://pypi.org/classifiers/
  classifiers=[
    'Programming Language :: Python :: 3.6',
    'Operating System :: POSIX :: Linux',
    'License :: OSI Approved :: MIT License',
    'Development Status :: 3 - Alpha',
    'Intended Audience :: Developers',
    'Topic :: Software Development :: Build Tools',
  ],
  keywords=["template", "pypi-guide", "pypi"],
  ...
)

packages, es un arreglo de cadenas que tiene como objetivo identificar la carpeta en la que se encuentra tu lib.
package_data, por defecto setup.py agrega archivos ".py" al paquete generado, se debe especificar explícitamente si se tiene otros tipos de archivos importantes para la lib.
install_requires, seguramente te suena a requirements.txt, es algo así solo que en este caso no se alimenta del requirements.txt como tal, si no de un proceso manual de selección de paquetes de los cuales depende la lib (en formato de arreglo de cadenas), por ejemplo: [“requests”, “numpy”, “pandas”].

python_requires, es importante ya que anuncia la compatibilidad de tu lib en función de la versión de Python en la que este programada, dependerá de que tan compatible hagas tu código a versiones menores (mientras más compatible, mejor), por ejemplo puede ser: “>=3.6” , “3.8”, “<2.7”, etc; link para más ejemplos.

(
  ...
  packages=["pypi_package_guide"],
  package_data={
    'pypi_package_guide': [
      'data/*.txt',
    ]
  },
  # install_requires = ['requests', 'numpy'] etc...
  install_requires=[],
  python_requires=">=3.6"
)

Demo Time

¡Subamos un paquete a PyPI! 📦


pip install -U sdist twine setuptools wheel build

python setup.py sdist

pip install -e ./dist/<your_package_name>-<your_version>.tar.gz

twine upload dist/*

Siguientes Pasos

Usar Read The Docs para generar una documentación más extensa, estructurada y dinámica
Añadir un flujo de CI/CD

Conclusiones

Anímate a subir un package o lib a PyPI no es místico ni excluyente.
Hacer un PRs (pull requests) con correcciones o mejora, levantar una issue como problema o wish (planteamiento de la implementación de algún feature o enhancement) en el repositorio ayudan a darle continuidad al package.