Explicación detallada de métodos para empaquetar y publicar módulos Python

Introducción

Ayer paqueté y subí mi biblioteca de procesamiento de archivos VASP a PyPI, ahora puedes instalar VASPy directamente a través de pip y easy_install (y a todos los que utilizan VASP para la química computacional, les doy la bienvenida a dar estrellas y participar)

Dirección de GotHub de VASPy:https://github.com/PytLab/VASPy
Dirección de PyPI de VASPy:https://pypi.python.org/pypi/vaspy/

Debido a que mi memoria no es muy buena, me temo que con el tiempo me olvide, por lo que aquí, aprovechando el calor, hago una resumen de la paquetización y subida de python con mi propio programa VASPy como ejemplo.

Estructura del paquete VASPy

Primero escribo aquí la estructura completa del paquete VASPy, todo el contenido posterior se explica con este ejemplo:

VASPy/
├── LICENSE
├── MANIFEST
├── MANIFEST.in
├── README.rst
├── requirements.txt
├── scripts
│  ├── change_incar_parameters.py
│  ├── create_inputs.py
│  └── ...
├── setup.cfg
├── setup.py
├── tests
│  ├── incar_test.py
│  ├── __init__.py
│  ├── oszicar_test.py
│  ├── outcar_test.py
│  ├── testdata
│  │  ├── CONTCAR
│  │  ├── DOS_SUM
│  │  ├── ELFCAR
│  │  └── ...
│  └── ...
└── vaspy
  ├── __init__.py
  ├── iter.py
  ├── matstudio.py
  └── ...
4 directorios, 54 archivos

Herramienta para empacar e instalar paquetes de terceros

Aquí necesitamos usar herramientas como setuptools y pip para empacar, publicar e instalar nuestros paquetes propios. Si necesita construir un wheel, también debe instalar el módulo wheel. Si la versión de python>=2.7.9o >=3.4setuptools y pip ya están instalados, puede que necesite actualizarlos a la última versión

pip install -U pip setuptools

Puede usar herramientas de gestión de paquetes, como

yum install pip
sudo apt-get install pip

A través de get-Instalación de scripts pip.py, si se detecta que no se han instalado wheel y setuptools también se instalarán automáticamente

python get-pip.py

No se hablará mucho de la instalación y presentación de herramientas específicas, puede referirse a las necesidades de instalación de paquetes

El papel de diferentes archivos en el paquete

setup.py

Este archivo es el archivo más importante para empacar todo el proyecto, que proporciona dos funciones principales:

La función setup(), los parámetros de esta función especifican cómo configurar su propio proyecto.
Herramienta de línea de comandos, incluyendo paquete, prueba, publicación, etc. Puede verlos mediante los siguientes comandos;

python setup.py --ayuda-comandos

setup.cfg

Este archivo contiene algunos parámetros predeterminados de construcción, como cuando se construye bdist_wheel--Parámetro universal

[bdist_wheel]
universal=1

De esta manera, cada vez que empaquete, se utilizará por defecto--El parámetro universal, el efecto es similar:

python setup.py bdist_wheel --universal

README.rst

Este originalmente lo escribí en markdown, después de empaquetar y publicarlo en PyPI, descubrí que PyPI no admite la renderización de markdown, y la página estaba en una gran confusión, por lo que escribí de nuevo con la sintaxis de reStructuredText. Después de todo, la sintaxis de los lenguajes de marcado es básicamente fácil de aprender, y si no, siempre se puede encontrar un plantilla para seguir.
Las reglas de sintaxis de reStructureText pueden referirse a la documentación oficial: Quick reStructuredText

En realidad, hay otro método que es usar pandoc para convertir markdown a formato rst, una manera conveniente es usar el módulo pyandoc para convertir automáticamente al publicar.
La método específico puede referirse a: Use Markdown README's in Python modules

MANIFEST.in

Este archivo informa a setuptools qué archivos adicionales deben paquetizarse durante la creación del paquete, por ejemplo, en mi VASPy utilizo este archivo para incluir los archivos de datos de prueba de las pruebas unitarias. Por supuesto, README, LICENSE y otros también pueden paquetizarse juntos mediante él.
A continuación, se muestra el contenido de mi propio MANIFEST.in:

include README.rst
include requirements.txt
include LICENSE
recursive-include scripts *
recursive-include tests *

Las reglas de sintaxis específicas pueden referirse a: The MANIFEST.in template

vaspy/

Esta carpeta es el paquete donde se encuentra el código fuente de vaspy.

tests/

Esta carpeta también es un subpaquete que contiene scripts de prueba unitaria, para poder realizar pruebas unitarias con python setup.py test, se agregó especialmente __init__.pys para que se convierta en un paquete.

Parámetros de setup()

Aquí solo se describen algunos de los parámetros que utilizo, la utilización específica de otros parámetros puede referirse a:https://docs.python.org/3/distutils/setupscript.html

name

versions = "vaspy"

Es el nombre completo del proyecto, se utilizará este nombre y número de versión en el paquete.

version

from vaspy import __version__
version = __version__

description

Es una descripción breve del proyecto, generalmente una frase, que se mostrará en la parte inferior del nombre en pypi.

long_description

Es una descripción larga, equivalente a una descripción concisa del proyecto, si esta cadena es de formato rst, PyPI la renderizará automáticamente en HTML para mostrar. Aquí se puede leer directamente el contenido de README.rst.

url

Enlace al paquete, generalmente un enlace en GitHub o un enlace en readthedocs.

packages

Lista de subpaquetes que deben incluirse, setuptools proporciona la función find_packages() para encontrar paquetes en la ruta de nivel superior, una función que no existe en distutil.

setup_requires

Este parámetro define otras dependencias necesarias para la instalación y ejecución exitosa de VASPy, que se instalarán utilizando pip.
Para la diferencia entre este parámetro y requirements.txt, consulte: install_requires vs archivos de requisitos

classifier

Este parámetro proporciona una serie de clasificaciones, que se colocarán en diferentes directorios en PyPI para clasificar los proyectos.
El nombre específico de las categorías y las reglas se pueden consultar en:https://pypi.python.org/pypi#63;%3Aaction=list_classifiers

test_suite

Este parámetro nos ayuda a usar

python setup.py test

Para ejecutar pruebas unitarias, ya no es necesario escribir un script separado, como run_tests.py, para ejecutar las pruebas unitarias.
La explicación oficial de este parámetro:

Un string que nombra una subclase de unittest.TestCase (o un paquete o módulo que contiene una o más de ellas, o un método de dicha subclase), o que nombra una función que puede llamarse sin argumentos y que devuelve un unittest.TestSuite. Si la suite nombrada es un módulo y el módulo tiene una función additional_tests(), se la llama y los resultados se agregan a las pruebas que se van a ejecutar. Si la suite nombrada es un paquete, cualquier submódulo y subpaquete se agregan recursivamente al conjunto de pruebas general.

Es decir, este parámetro puede aceptar varios tipos de parámetros:

Recibe una subclase unittest.TestCase, podemos escribir todos los casos de prueba unitarios en un caso de prueba y luego importarlo, pasándoselo a test_suite
Recibe un objeto de función, este objeto de función no tiene parámetros y devuelve un unittest.TestSuite. De esta manera, podemos escribir una función separada, combinar varios casos de prueba en una suite y devolverla, luego importarla y pasarla a test_suite.

Nombres de módulos y paquetes, uso este método, pruebas propias anteriores siempre fueron separadas en varios scripts, de esta manera, al agregar un __init__.py, puedo convertirla en un paquete, y pasar el nombre del paquete a test_suite, setuptools ejecutará mágicamente todas las pruebas debajo de este paquete, por lo que al agregar scripts de prueba nuevos en el futuro, simplemente agregaré nuevos scripts y no se necesitarán cambios en otros.

Efecto de ejecución:

zjshao@SHAO-PC:/mnt/d/Dropbox/Código/CentOS_code/VASPy$ python setup.py prueba
ejecutando prueba
ejecutando egg_info
creando vaspy.egg-info
escribiendo vaspy.egg-info/PKG-INFO
escribiendo top-nombres de niveles a vaspy.egg-info/top_level.txt
escribiendo dependency_links a vaspy.egg-info/dependency_links.txt
Escribiendo archivo de manifiesto 'vaspy.egg'-info/SOURCES.txt'
leyendo archivo de manifestación 'vaspy.egg-info/SOURCES.txt'
Leyendo plantilla de manifiesto 'MANIFEST.in'
Escribiendo archivo de manifiesto 'vaspy.egg'-info/SOURCES.txt'
Ejecutando build_ext
test_compare (tests.incar_test.InCarTest)
Asegúrese de que podamos comparar dos objetos InCar correctamente. ... ok
test_eq (tests.incar_test.InCarTest)
Test __eq__() function. ... ok
...
Aquí se omiten varios outputs
----------------------------------------------------------------------
Ejecutadas 22 pruebas en 3.574s
OK

Publicar su paquete de python

1Primero, registre una cuenta en PyPI

2Configuración~/El archivo .pypirc debe estar así:

[distutils]
índice-servidores =
  pypi
  pypitest
[pypi]
usuario:ShaoZhengjiang
contraseña:mypassword
[pypitest]
usuario:ShaoZhengjiang
contraseña:mypassword

3Luego registrar y subir nuestro paquete al servidor de prueba

pypi ofrece un servidor de prueba, donde podemos hacer pruebas.

python setup.py register -r pypitest

Luego

python setup.py sdist upload -r pypitest

Si no hay problemas, no deberíamos recibir ningún error.

4Subir a PyPI

Si el test anterior tiene éxito, podemos seguir los mismos pasos para registrar y subir el paquete.

python setup.py register -r pypi
python setup.py sdist upload -r pypi

Ok, a partir de ahora podemos usar PyPI(https://pypi.python.org/pypi/vaspy/Vemos nuestros paquetes en el )