example_pypi_package
v0.1.0
Il s'agit d'un exemple de package PYPI (Python Package Index) configuré avec des tests automatisés et un flux de travail de publication de packages à l'aide des actions GitHub CI / CD. Il est principalement conçu pour les utilisateurs GitHub + VS Code (Windows / Mac / Linux) qui sont sur le point d'écrire et de publier leur premier package PYPI. Le package pourrait servir de démarreur / passe-partout / démo et le tutoriel pourrait vous donner une explication rapide et concise pour résoudre des problèmes petits mais ennuyeux que vous pourriez rencontrer, tels que la confusion du nom de package / module, et des problèmes de configuration de test de code contre le code.
Cet exemple de package est inspiré par / basé sur l'exemple de projet officiel PYPA / SampleProject, mais ce package:
master ou de la branche main , et est publié lors de la création d'une versionPYTHONPATH , afin que les fichiers de test ne disposent pas d'erreurs de liaison et peuvent exécuter avec PyTest dans VS Code(Cliquez sur le bouton ci-dessus pour utiliser cet exemple de package comme modèle pour votre nouveau dépôt GitHub, cela initialisera un nouveau référentiel et mes validations ne seront pas dans votre historique GIT)
(Si vous n'utilisez pas GitHub, vous pouvez télécharger l'archive de l'exemple de package)
Beaucoup utilisent un même package et un même nom de module, vous pourriez certainement le faire. Mais cet exemple de package et les noms de son module sont différents: example_pypi_package et examplepy .
Ouvrez le dossier example_pypi_package avec le code Visual Studio, Ctrl + Shift + F (Windows / Linux) ou CMD + Shift + F (macOS) pour trouver toutes les occurrences des deux noms et les remplacer par les noms de votre package et de votre module. N'oubliez pas non plus de modifier le nom du dossier src / examplepy .
Simplement et très grossièrement, le nom du package est utilisé dans pip install <PACKAGENAME> et le nom du module est utilisé dans import <MODULENAME> . Les deux noms doivent être constitués de lettres de base en minuscules (AZ). Ils peuvent avoir des soulignements ( _ ) si vous en avez vraiment besoin. Hyphen-minus ( - ) ne doit pas être utilisé.
Vous devrez également vous assurer que l'URL "https://pypi.org/project/example-pypi-package/" (remplacez example-pypi-package par le nom de votre package, avec tout _ devenant - ) n'est pas occupé.
Les soulignements ( _ ) peuvent être utilisés mais une telle utilisation est découragée. Les numéros peuvent être utilisés si le nom ne commence pas par un nombre, mais une telle utilisation est également découragée.
Le nom commençant par un nombre et / ou contenant des traits d'union-moins ( - ) ne doit pas être utilisé: bien que techniquement légal, ce nom cause beaucoup de problèmes - les utilisateurs doivent utiliser importlib pour l'importer.
Ne vous laissez pas berner par l'URL "pypi.org/project/example-pypi-package/" et le nom "Exemple-PyPi-Package" sur PYPI.org. PYPI.org et PIP System Convert tous _ en - et utilisez ce dernier sur la commande SITE WEB / IN pip , mais le vrai nom est toujours avec _ , que les utilisateurs doivent utiliser lors de l'importation du package.
Il y a aussi un espace de noms à utiliser si vous avez besoin de sous-packages.
Faire les modifications nécessaires dans setup.py .
Le numéro de version du package __version__ est dans src / examplepy / __ init__.py . Vous voudrez peut-être changer cela.
L'exemple de package est conçu pour être compatible avec Python 3.6, 3.7, 3.8, 3.9, et sera testé contre ces versions. Si vous devez modifier la plage de versions, vous devez changer:
classifiers , python_requires dans setup.pyenvlist dans tox.inimatrix: python: dans .github / workflows / test.yml Si vous prévoyez de télécharger sur TestPyPi qui est un terrain de jeu de PYPI à des fins de test, modifiez twine upload --repository pypi dist/* vers twine upload --repository testpypi dist/* Dans le fichier .github / workflows / release.yml .
PIP est un gestionnaire de packages Python. Vous avez déjà PIP si vous utilisez Python 3.4 et une version ultérieure qui l'inclut par défaut. Lisez ceci pour savoir comment vérifier si PIP est installé. Lisez ceci si vous devez l'installer.
Visual Studio Code est l'éditeur de code le plus populaire aujourd'hui, notre exemple de package est configuré pour fonctionner avec VS Code.
Installez vs Extension de code "Python".
L'extension "Python" contre le code vous suggèrera d'installer Pylint. De plus, le package d'exemple est configuré pour utiliser PyTest avec des extensions VS Code + Python, donc, installez Pylint et PyTest:
pip install pylint pytest(Il est probable que vous serez invité à les installer, si c'est le cas, vous n'avez pas besoin de taper et d'exécuter la commande)
Le contenu de Vscode.env est maintenant PYTHONPATH=/;src/;${PYTHONPATH} qui est bon pour Windows. Si vous utilisez Linux ou MacOS, vous devez le changer en PYTHONPATH=/:src/:${PYTHONPATH} (remplacement ; par : . Si le chemin n'est pas correctement défini, vous verrez des erreurs de liaison dans les fichiers de test et Pytest ne pourra pas exécuter correctement les tests / test _ *. Py .
Fermer et rouvrir le code vs. Vous pouvez maintenant cliquer sur l'icône du flacon de laboratoire dans le menu de gauche et y exécuter tous les tests, avec Pytest. Pytest semble meilleur que le cadre unittest standard, il prend en charge unittest vous pouvez donc continuer à utiliser import unittest dans vos fichiers de test.
L'exemple de package dispose également d'un fichier .EditorConfig . Vous pouvez installer une extension de code contre le code "EditorConfig pour le code vs" qui utilise le fichier. Avec la configuration actuelle, l'outil EditorConfig peut utiliser automatiquement des espaces (4 espaces pour .py, 2 pour d'autres) pour l'indentation, définissez le codage LF UTF-8 , la fin des lignes, la finition des espaces blancs en arrière dans les fichiers non marqués, etc.
Dans VS Code, vous pouvez accéder au fichier -> Préférences -> Paramètres, tapez "Python Formatting Provider" dans la zone de recherche, et choisissez l'un des trois outils de formatage de code Python (AutoPep8, Black et YAPF), vous serez invité à l'installer. Les raccourcis pour le formatage d'un fichier de code sont Maj + Alt + F (Windows); Shift + Option (Alt) + F (macOS); Ctrl + Shift + I (Linux).
Dans SRC / ExampyPy / ( examplepy aurait dû être remplacé par le dossier de votre nom de module), renommez module1.py et écrivez votre code. Ajoutez plus de fichiers de module .py si vous en avez besoin.
Dans Tests / Folder, renommez Test_Module1.py (pour tester _ *. Py ) et écrivez votre code de test unitaire (avec unittest). Ajoutez plus de test _ *. Fichiers PY si vous en avez besoin.
Installez TOX et exécutez-le:
pip install tox
tox Dans notre configuration, TOX exécute une vérification de la distribution des sources à l'aide de Check-Manifest (qui nécessite que votre référentiel soit initialisé Git ( git init ) et ajouté ( git add . ) Au moins), la vérification de Setuptools et les tests unitaires à l'aide de PYTEST. Vous n'avez pas besoin d'installer Check-Manifest et Pytest cependant, Tox les installera dans un environnement séparé.
Les tests automatisés sont exécutés contre plusieurs versions Python, mais sur votre machine, vous n'utilisez peut-être qu'une seule version de Python, s'il s'agit de Python 3.9, puis exécutez:
tox -e py39 Si vous ajoutez plus de fichiers au répertoire racine ( Example_PYPI_PACKAGE / ), vous devrez ajouter votre fichier sur la liste check-manifest --ignore dans Tox.ini .
Installer ou mettre à niveau setuptools and wheel :
python -m pip install --user --upgrade setuptools wheel (Si python3 est la commande de votre machine, modifiez python en python3 dans la commande ci-dessus, ou ajoutez un alias python=python3 à ~ / .bashrc ou ~ / .bash_aliases fichier si vous utilisez bash sur linux)
dist À partir du répertoire example_pypi_package , exécutez la commande suivante, afin de générer une version de production pour la distribution source (SDIST) dans le dossier dist :
python setup.py sdist bdist_wheelFacultativement, vous pouvez installer la version dist. de votre package localement avant de télécharger sur PYPI ou TestPypi:
pip install dist/example_pypi_package-0.1.0.tar.gz(Vous devrez peut-être d'abord désinstaller le package existant:
pip uninstall example_pypi_package Il peut y avoir plusieurs packages installés avec le même nom, alors exécutez pip uninstall plusieurs fois jusqu'à ce qu'il ne dise plus de package à supprimer.)
Enregistrez un compte sur PYPI, accédez aux paramètres du compte § Tokens API, "Ajouter un jeton API". Le jeton PYPI n'apparaît qu'une seule fois, le copiez quelque part. Si vous l'avez manqué, supprimez l'ancien et ajoutez un nouveau jeton.
(Enregistrez un compte TestPyPi si vous téléchargez sur TestPy)
Sur la page de votre dépôt GitHub nouvellement créé ou existant, cliquez sur Paramètres -> Secrets -> Nouveau secret de référentiel , le nom doit être PYPI_API_TOKEN et la valeur devrait être votre jeton PYPI (qui commence par pypi- ).
L'exemple de package a des tests automatisés et un téléchargement (publication) déjà configuré avec des actions GitHub:
git push ou une demande de traction est soumis sur votre branche master ou main , le package est automatiquement testé par rapport aux versions Python souhaitées avec des actions GitHub. Une fois votre package publié sur PYPI, accédez à https://pypi.org/project/example-pypi-package/ ( _ devient - ). Copiez la commande sur la page, exécutez-la pour télécharger et installez votre package à partir de PYPI. (ou test.pypi.org si vous l'utilisez)
Si vous souhaitez modifier la description / réadme de votre package sur PYPI.org, vous devez publier une nouvelle version.
Installer ou mettre à niveau la ficelle:
python -m pip install --user --upgrade twineCréez un fichier .pypirc dans votre répertoire $ Home ( ~ ), son contenu doit être:
[pypi]
username = __token__
password = <PyPI token> (Utilisez [testpypi] au lieu de [pypi] si vous téléchargez sur TestPypi)
Remplacez <PyPI token> par votre vrai jeton PYPI (qui commence par pypi- ).
(Si vous ne créez pas manuellement $ home / .pypirc , vous serez invité à un nom d'utilisateur (qui devrait être __token__ ) et un mot de passe (qui devrait être votre jeton PYPI) lorsque vous exécutez du ficelle)
Exécutez Twine pour télécharger toutes les archives dans le dossier DIST :
python -m twine upload --repository pypi dist/ * (Utilisez testpypi au lieu de pypi si vous téléchargez sur TestPy)
Lorsque vous avez fini de développer une version plus récente de votre package, faites les choses suivantes.
Modifiez le numéro de version __version__ dans SRC Exampy__Init __. Py .
Supprimez toutes les anciennes versions de Dist .
Exécutez à nouveau la commande suivante pour régénérer DIST :
python setup.py sdist bdist_wheelExécutez à nouveau la commande suivante pour télécharger Dist :
python -m twine upload --repository pypi dist/ * (Utilisez testpypi au lieu de pypi si nécessaire)
BTW, si vous souhaitez publier un package TypeScript (JavaScript) dans le registre NPM, accédez à Exemple Package TypeScript prêt à être publié sur NPM pour 2021.
