example_pypi_package
v0.1.0
Este es un paquete PYPI (Python Package Index) configurado con pruebas automatizadas y flujo de trabajo de publicación de paquetes utilizando GitHub Actions CI/CD. Está hecho principalmente para usuarios de Código GitHub + VS (Windows / Mac / Linux) que están a punto de escribir y publicar su primer paquete PYPI. El paquete podría servir como un iniciador / caldera / demostración y el tutorial podría darle una explicación rápida y concisa para resolver algunos problemas pequeños pero molestos que puede encontrar, como confusión de nombre de paquete / módulo y problemas de configuración de prueba de código.
Este paquete de ejemplo está inspirado en / basado en el proyecto de muestra oficial PYPA / SampleProject, pero este paquete:
master o main , y se publica cuando se crea una versiónPYTHONPATH , para que los archivos de prueba no tengan errores de pelusa y puedan ejecutarse con Pytest en VS Code(Haga clic en el botón anterior para usar este paquete de ejemplo como plantilla para su nuevo repositorio de GitHub, esto inicializará un nuevo repositorio y mis compromisos no estarán en su historial de Git)
(Si no usa GitHub, puede descargar el archivo del paquete de ejemplo)
Muchos usan un mismo paquete y nombre del módulo, definitivamente podrían hacerlo. Pero este paquete de ejemplo y los nombres de su módulo son diferentes: example_pypi_package y examplepy .
Abra la carpeta example_pypi_package con el código Visual Studio, Ctrl + Shift + F (Windows / Linux) o CMD + Shift + F (MacOS) para encontrar todas las ocurrencias de ambos nombres y reemplacelos con los nombres de su paquete y módulo. También recuerde cambiar el nombre de la carpeta SRC/Ejemplopy .
Simplemente y muy aproximadamente en términos generales, el nombre del paquete se usa en pip install <PACKAGENAME> y el nombre del módulo se usa en import <MODULENAME> . Ambos nombres deben consistir en letras básicas en minúsculas (AZ). Es posible que tengan subrayos ( _ ) si realmente los necesita. No se debe usar el guión -minus ( - ).
También deberá asegurarse de que la URL "https://pypi.org/project/example-pypi-package/" (reemplace example-pypi-package por nombre de su paquete, con todo _ - ) no está ocupado.
Se pueden usar subrayos ( _ ), pero se desaconseja dicho uso. Los números se pueden usar si el nombre no comienza con un número, pero tal uso también se desaconseja.
El nombre que comienza con un número y/o que contiene hyphen -minus ( - ) no debe usarse: aunque técnicamente legal, dicho nombre causa muchos problemas: los usuarios deben usar importlib para importarlo.
No se deje engañar por la URL "pypi.org/project/example-pypi-package/" y el nombre "ejemplo-pypi-package" en pypi.org. Pypi.org y el sistema PIP convierten todo _ a - y usan este último en el comando Sitio web / en pip , pero el nombre real todavía está con _ , que los usuarios deben usar al importar el paquete.
También hay un espacio de nombres para usar si necesita subgrupos.
Haga los cambios necesarios en Setup.py .
El número de versión del paquete __version__ está en SRC/ESPPY/__ init__.py . Es posible que desee cambiar eso.
El paquete de ejemplo está diseñado para ser compatible con Python 3.6, 3.7, 3.8, 3.9, y se probará con estas versiones. Si necesita cambiar el rango de versiones, debe cambiar:
classifiers , python_requires en setup.pyenvlist en tox.inimatrix: python: en .github/Workflows/test.yml Si planea cargar a TestPypi, que es un patio de recreo de PYPI para fines de prueba, cambie twine upload --repository pypi dist/* a twine upload --repository testpypi dist/* en el archivo .github/workflows/releers.yml .
Pip es un administrador de paquetes de Python. Ya tiene PIP si usa la versión Python 3.4 y posterior que lo incluyen de forma predeterminada. Lea esto para saber cómo verificar si PIP está instalado. Lea esto si necesita instalarlo.
Visual Studio Code es el editor de código más popular hoy en día, nuestro paquete de ejemplo está configurado para funcionar con el código VS.
Instalar VS Extensión del código "Python".
La extensión de código "Python" vs sugerirá que instale Pylint. Además, el paquete de ejemplo está configurado para usar Pytest con VS Code + Python Extensions, por lo tanto, instale Pylint y Pytest:
pip install pylint pytest(Es probable que se le solicite que los instale, si ese es el caso, no necesita escribir y ejecutar el comando)
El contenido de VScode.env ahora es PYTHONPATH=/;src/;${PYTHONPATH} que es bueno para Windows. Si usa Linux o macOS, debe cambiarlo a PYTHONPATH=/:src/:${PYTHONPATH} (reemplazar ; con : . Si la ruta no se establece correctamente, verá errores de peluche en los archivos de prueba y Pytest no podrá ejecutar pruebas/prueba _*. Py archivos correctamente.
Cerrar y reabrir el código. Ahora puede hacer clic en el icono de frascos de laboratorio en el menú izquierdo y ejecutar todas las pruebas allí, con Pytest. Pytest parece mejor que el marco de Unittest estándar, admite unittest por lo que puede seguir usando import unittest en sus archivos de prueba.
El paquete de ejemplo también tiene un archivo .EditorConfig . Puede instalar VS Code Extension "EditorConfig para el código VS" que usa el archivo. Con la configuración actual, la herramienta EditorConfig puede usar automáticamente espacios (4 espacios para .py, 2 para otros) para la sangría, establecer la codificación UTF-8 , el extremo de las líneas LF , recortar espacios en blanco en archivos sin marque, etc.
En VS Code, puede ir a Archivo -> Preferencias -> Configuración, escriba "Python Formatting Provider" en el cuadro de búsqueda, y elija una de las tres herramientas de formato de código Python (AutoPep8, Black y Yapf), se le pedirá que lo instale. Los atajos para el formato de un archivo de código son Shift + Alt + F (Windows); Shift + Opción (Alt) + F (macOS); Ctrl + Shift + I (Linux).
En src/ ejemplopy/ ( examplepy debería haber sido reemplazado por la carpeta de su módulo), cambiar el nombre de módulo1.py y escribir su código en ella. Agregue más archivos de módulo .py si lo necesita.
En las pruebas/ carpeta, cambie el nombre de test_module1.py (para probar _*. Py ) y escriba su código de prueba unitario (con unittest) en él. Agregue más pruebas _*. PY Archivos si lo necesita.
Instale tox y ejecutarlo:
pip install tox
tox En nuestra configuración, Tox ejecuta una verificación de la distribución de la fuente utilizando Check-Manifest (que requiere que su repositorio se inicie ( git init ) y se agregue (al menos git add . ), SetupTools Check y pruebas unitarias usando PyTest. Sin embargo, no necesita instalar check-manifest y pytest, Tox los instalará en un entorno separado.
Las pruebas automatizadas se ejecutan contra varias versiones de Python, pero en su máquina, puede estar usando solo una versión de Python, si eso es Python 3.9, luego ejecute:
tox -e py39 Si agrega más archivos al directorio raíz ( ejemplo_pypi_package/ ), deberá agregar su archivo a check-manifest --ignore list en tox.ini .
Instalar o actualizar setuptools y wheel :
python -m pip install --user --upgrade setuptools wheel (Si python3 es el comando en su máquina, cambie python a python3 en el comando anterior, o agregue una línea alias python=python3 a ~/.bashrc o ~/.bash_aliases si usa bash en Linux)
dist Desde el directorio de example_pypi_package , ejecute el siguiente comando, para generar la versión de producción para la distribución de origen (SDIST) en la carpeta dist :
python setup.py sdist bdist_wheelOpcionalmente, puede instalar la versión Dist de su paquete localmente antes de cargar a Pypi o Testpypi:
pip install dist/example_pypi_package-0.1.0.tar.gz(Es posible que deba desinstalar el paquete existente primero:
pip uninstall example_pypi_package Puede haber varios paquetes instalados con el mismo nombre, así que ejecute pip uninstall varias veces hasta que no diga más paquete para eliminar).
Registre una cuenta en PYPI, vaya a Configuración de la cuenta § Tokens API, "Agregar token API". El token Pypi solo aparece una vez, cótalo en algún lugar. Si te lo perdiste, elimine el viejo y agregue un nuevo token.
(Registre una cuenta TestPypi si está cargando a TestPypi)
En la página de su repositorio de GitHub recién creado o existente, haga clic en Configuración -> Secretos -> Nuevo secreto del repositorio , el nombre debe ser PYPI_API_TOKEN y el valor debe ser su token Pypi (que comienza con pypi- ).
El paquete de ejemplo tiene pruebas automatizadas y carga (publicación) ya configurada con acciones de GitHub:
git push o se envía una solicitud de extracción en su rama master o main , el paquete se prueba automáticamente con las versiones de Python deseadas con acciones de GitHub. Después de publicar su paquete en Pypi, vaya a https://pypi.org/project/example-pypi-package/ ( _ se convierte - ). Copie el comando en la página, ejecutelo para descargar e instalar su paquete desde PYPI. (o test.pypi.org si lo usa)
Si desea modificar la descripción / lectura de su paquete en pypi.org, debe publicar una nueva versión.
Instalar o actualizar el hilo:
python -m pip install --user --upgrade twineCree un archivo .pypirc en su directorio $ home ( ~ ), su contenido debe ser:
[pypi]
username = __token__
password = <PyPI token> (Use [testpypi] en lugar de [pypi] si está cargando a testpypi)
Reemplace <PyPI token> con su verdadero token Pypi (que comienza con pypi- ).
(Si no crea manualmente $ home/.pypirc , se le solicitará un nombre de usuario (que debe ser __token__ ) y la contraseña (que debería ser su token Pypi) cuando ejecute Twine)
Ejecute el hilo para cargar todos los archivos en la carpeta Dist :
python -m twine upload --repository pypi dist/ * (Use testpypi en lugar de pypi si está cargando a TestPypi)
Cuando haya terminado de desarrollar una versión más nueva de su paquete, haga las siguientes cosas.
Modifique el número de versión __version__ en SRC ESPIEPY__Init __. Py .
Elimine todas las versiones antiguas en Dist .
Ejecute el siguiente comando nuevamente para regenerar DIST :
python setup.py sdist bdist_wheelEjecute el siguiente comando nuevamente para cargar DIST :
python -m twine upload --repository pypi dist/ * (Use testpypi en lugar de pypi si es necesario)
Por cierto, si desea publicar el paquete TypeScript (JavaScript) en el Registro NPM, vaya al paquete TypeScript de ejemplo listo para ser publicado en NPM para 2021.
