example_pypi_package
v0.1.0
Dies ist ein Beispiel für PYPI (Python Package Index) -Paket mit automatisierten Tests und Paketveröffentlichungs -Workflow mit GitHub -Aktionen CI/CD. Es wird hauptsächlich für GitHub + VS -Code (Windows / Mac / Linux) -Nutzer hergestellt, die ihr erstes PYPI -Paket schreiben und veröffentlichen möchten. Das Paket könnte als Starter / Boilerplate / Demo dienen, und das Tutorial könnte Ihnen eine schnelle und präzise Erklärung geben, um einige kleine, aber ärgerliche Probleme zu lösen, auf die Sie möglicherweise begegnen, z. B. Verwirrung des Pakets / Moduls und VS -Code -Testkonfigurationsprobleme.
Dieses Beispielpaket ist von / basierend auf dem offiziellen Beispielprojekt PYPA / SampleProject inspiriert, aber dieses Paket:
master oder main Branch getestet und beim Erstellen einer Veröffentlichung veröffentlichtPYTHONPATH hinzufügt, sodass Testdateien keine Linkerfehler haben und mit PyTest im VS -Code ausgeführt werden können(Klicken Sie auf die oben genannte Schaltfläche, um dieses Beispielpaket als Vorlage für Ihr neues Github -Repo zu verwenden. Dadurch wird ein neues Repository initialisiert und meine Commits sind nicht in Ihrem Git -Verlauf.)
(Wenn Sie GitHub nicht verwenden, können Sie das Archiv des Beispielpakets herunterladen)
Viele verwenden denselben Paket- und Modulnamen, das könnten Sie definitiv tun. Dieses Beispielpaket und die Namen seines Moduls sind jedoch unterschiedlich: example_pypi_package und examplepy .
Öffnen Sie example_pypi_package -Ordner mit Visual Studio Code, Strg + Shift + F (Windows / Linux) oder CMD + Shift + F (MacOS), um alle Vorkommen beider Namen zu finden und sie durch die Namen Ihres Pakets und Moduls zu ersetzen. Denken Sie auch daran, den Namen des Ordners SRC/Beispielpy zu ändern.
Einfach und sehr groberweise wird der Paketame in pip install <PACKAGENAME> und Modulname in import <MODULENAME> verwendet. Beide Namen sollten aus Kleinbuchstaben (AZ) bestehen. Möglicherweise haben sie Unterstriche ( _ ), wenn Sie sie wirklich brauchen. Bindestens -Minus ( - ) sollte nicht verwendet werden.
Sie müssen außerdem sicherstellen, dass die URL "https://pypi.org/project/example-pypi-package/" ( example-pypi-package ersetzen Sie durch Ihren Packungsnamen, mit allen _ - ) nicht besetzt.
Unterstriche ( _ ) können verwendet werden, aber eine solche Verwendung wird entmutigt. Zahlen können verwendet werden, wenn der Name nicht mit einer Nummer beginnt, aber auch diese Verwendung entmutigt wird.
Der Name beginnt mit einer Nummer und/oder mit Bindestrich -Minus ( - ) sollte nicht verwendet werden: Obwohl technisch legal, verursacht ein solcher Name eine Menge Probleme - Benutzer müssen importlib verwenden, um sie zu importieren.
Lassen Sie sich nicht von der URL "pypi.org/project/example-pypi-package/" und dem Namen "Beispiel-Pypi-Package" auf pypi.org täuschen. PYPI.org und PIP -System konvertieren alle _ in - letztere auf der Website / im pip -Befehl, aber der richtige Name ist immer noch mit _ , was Benutzer beim Importieren des Pakets verwenden sollten.
Es gibt auch einen Namespace zu verwenden, wenn Sie Unterpackungen benötigen.
Nehmen Sie die erforderlichen Änderungen in Setup.py vor.
Die Versionsnummer des Pakets __version__ befindet sich in SRC/Beispielpy/__ init__.py . Vielleicht möchten Sie das ändern.
Das Beispielpaket ist so konzipiert, dass sie mit Python 3.6, 3.7, 3.8, 3.9 kompatibel ist und gegen diese Versionen getestet wird. Wenn Sie den Versionsbereich ändern müssen, sollten Sie sich ändern:
classifiers , python_requires in setup.pyenvlist in tox.inimatrix: python: in .github/Workflows/test.yml Wenn Sie planen, auf TestPypi hochzuladen, ist ein Spielplatz von PYPI zum Testzweck, ändern Sie twine upload --repository pypi dist/* to twine upload --repository testpypi dist/* in der Datei .github/Workflows/Release.yml .
PIP ist ein Python -Paketmanager. Sie haben bereits PIP, wenn Sie Python 3.4 und eine spätere Version verwenden, die es standardmäßig enthalten. Lesen Sie dies, um zu wissen, wie Sie überprüft werden, ob PIP installiert ist. Lesen Sie dies, wenn Sie es installieren müssen.
Visual Studio Code ist heute der beliebteste Code -Editor. Unser Beispielpaket ist so konfiguriert, dass sie mit VS -Code funktioniert.
Installieren Sie die VS -Code -Erweiterung "Python".
"Python" gegen Code -Erweiterung schlägt vor, dass Sie PyRINT installieren. Außerdem ist das Beispielpaket so konfiguriert, dass PyTest mit VS -Code + Python -Erweiterungen verwendet wird. Installieren Sie also Pyraint und PyTest:
pip install pylint pytest(Es ist wahrscheinlich, dass Sie aufgefordert werden, sie zu installieren. Wenn dies der Fall ist, müssen Sie den Befehl nicht eingeben und ausführen.)
Der Inhalt von VSCODE.Env ist jetzt PYTHONPATH=/;src/;${PYTHONPATH} was für Windows gut ist. Wenn Sie Linux oder macOS verwenden, müssen Sie es in PYTHONPATH=/:src/:${PYTHONPATH} (ersetzt ; mit : ändern. Wenn der Pfad nicht ordnungsgemäß festgelegt ist, werden Sie Linker in Testdateien feststellen und PyTest kann keine Tests/Tests _*. Py -Dateien korrekt ausführen.
Schließen und wiedereröffnen gegen Code. Sie können jetzt im linken Menü auf das Symbol für Laborflächen klicken und alle Tests mit PyTest ausführen. PyTest scheint besser zu sein als das Standard -Unittest -Framework. Es unterstützt unittest Daher können Sie in Ihren Testdateien weiterhin import unittest verwenden.
Das Beispielpaket hat auch eine .DitorConfig -Datei. Sie können die VS -Code -Erweiterung "EditorConfig für VS -Code" installieren, die die Datei verwendet. Mit der aktuellen Konfiguration kann das EditorConfig-Tool automatisch Leerzeichen (4 Leerzeichen für .py, 2 für andere) für die Eindrückung verwenden, UTF-8 -Codierung festlegen, LF Ende der Linien, die Trailing-Whitespaces in Nicht-Markdown-Dateien usw. trimmen, usw.
In VS -Code können Sie zu Datei -> Einstellungen -> Einstellungen, "Python -Formatierungsanbieter" in das Suchfeld eingeben und eines der drei Python -Code -Formatierungs -Tools (AutoPep8, Black und YaPF) auswählen. Sie werden aufgefordert, es zu installieren. Die Verknüpfungen zur Formatierung einer Codedatei sind Shift + Alt + F (Windows); Shift + Option (Alt) + F (macOS); Strg + Shift + I (Linux).
In SRC/ Beispielpy/ ( examplepy hätte durch Ihren Modulnamen ersetzt werden sollen) benennen Sie Modul1.py um und schreiben Sie Ihren Code darin. Fügen Sie bei Bedarf mehr Modul -.py -Dateien hinzu.
Benennen Sie in Tests/ Ordner test_module1.py (um _*. PY zu testen ) und schreiben Sie Ihren Unit -Testcode (mit unittest) darin. Fügen Sie mehr Test _*. Py -Dateien hinzu, wenn Sie benötigen.
Installieren Sie Tox und führen Sie es aus:
pip install tox
tox In unserer Konfiguration führt Tox eine Überprüfung der Quellverteilung mit dem Check-Manifest aus (wodurch Ihr Repo git-initialisiert wird ( git init ) und hinzugefügt ( git add . ), Setuptools's Check und Unit-Tests mit PyTest. Sie müssen das Check-Manifest und PyTest nicht installieren. Tox installiert sie in einer separaten Umgebung.
Die automatisierten Tests werden gegen mehrere Python -Versionen durchgeführt, aber auf Ihrer Maschine verwenden Sie möglicherweise nur eine Version von Python, wenn das Python 3.9 ist, dann laufen Sie:
tox -e py39 Wenn Sie dem Root-Verzeichnis weitere Dateien hinzufügen ( Beispiel_PYPI_PACKAGE/ ), müssen Sie Ihre Datei zum check-manifest --ignore -Liste in tox.ini hinzufügen.
Installieren oder aktualisieren Sie setuptools und wheel :
python -m pip install --user --upgrade setuptools wheel (Wenn python3 der Befehl auf Ihrer Maschine ist, ändern Sie python in python3 im obigen Befehl oder fügen Sie einen Zeilen alias python=python3 zu ~/.bashrc oder ~/.bash_alias -Datei hinzu, wenn Sie Bash auf Linux verwenden)
dist Führen Sie aus example_pypi_package -Verzeichnis den folgenden Befehl aus, um die Produktionsversion für die Quellverteilung (SDIST) im dist -Ordner zu generieren:
python setup.py sdist bdist_wheelOptional können Sie vor dem Hochladen auf PYPI oder TestPYPI die Dist -Version Ihres Pakets lokal installieren:
pip install dist/example_pypi_package-0.1.0.tar.gz(Möglicherweise müssen Sie zuerst das vorhandene Paket deinstallieren:
pip uninstall example_pypi_package Möglicherweise gibt es mehrere installierte Pakete mit demselben Namen. Führen Sie also pip uninstall mehrmals aus, bis es kein Paket mehr zum Entfernen besagt.)
Registrieren Sie ein Konto auf PYPI, wenden Sie sich zu den API -Token der Kontoseinstellungen, "API -Token hinzufügen". Das PYPI -Token erscheint nur einmal, kopieren Sie es irgendwo. Wenn Sie es verpasst haben, löschen Sie das Alte und fügen Sie ein neues Token hinzu.
(Registrieren Sie ein Testpypi -Konto, wenn Sie auf TestPypi hochladen.)
Klicken Sie auf der Seite Ihres neu erstellten oder vorhandenen Github -Repo auf Einstellungen -> Geheimnisse -> Neues Repository -Geheimnis , der Name sollte PYPI_API_TOKEN sein und der Wert sollte Ihr PYPI -Token sein (das mit pypi- startet).
Das Beispielpaket enthält automatisierte Tests und Upload (Veröffentlichungen), die bereits mit GitHub -Aktionen eingerichtet wurden:
git push oder eine Pull -Anfrage in Ihrem master oder main eingereicht werden, wird das Paket automatisch gegen die gewünschten Python -Versionen mit GitHub -Aktionen getestet. Nachdem Ihr Paket auf PYPI veröffentlicht wurde, besuchen Sie https://pypi.org/project/example-pypi-package/ ( _ - ). Kopieren Sie den Befehl auf der Seite und führen Sie ihn aus, um Ihr Paket von PYPI herunterzuladen und zu installieren. (oder test.pypi.org, wenn Sie das verwenden)
Wenn Sie die Beschreibung / Readme Ihres Pakets auf pypi.org ändern möchten, müssen Sie eine neue Version veröffentlichen.
TWINE Installieren oder aktualisieren:
python -m pip install --user --upgrade twineErstellen Sie eine .pypirc -Datei in Ihrem $ home ( ~ ) Verzeichnis, der Inhalt sollte sein:
[pypi]
username = __token__
password = <PyPI token> (Verwenden Sie [testpypi] anstelle von [pypi] , wenn Sie auf Testpypi hochladen)
Ersetzen Sie <PyPI token> durch Ihr echtes PYPI-Token (das mit pypi- beginnt).
(Wenn Sie $ home/.pyPirc nicht manuell erstellen, werden Sie für einen Benutzernamen (das __token__ ) und ein Passwort (das sein sollte Ihr PYPI -Token sein sollte) aufgefordert, wenn Sie Twine laufen lassen))
Führen Sie Twine aus, um alle Archive unter Dist -Ordner hochzuladen:
python -m twine upload --repository pypi dist/ * (Verwenden Sie testpypi anstelle von pypi , wenn Sie auf Testpypi hochladen.)
Wenn Sie eine neuere Version Ihres Pakets entwickelt haben, machen Sie die folgenden Dinge.
Ändern Sie die Versionsnummer __version__ in Src Beispielpy__init __. Py .
Löschen Sie alle alten Versionen in Dist .
Führen Sie den folgenden Befehl erneut aus, um Dist zu regenerieren:
python setup.py sdist bdist_wheelFühren Sie den folgenden Befehl erneut aus, um Dist hochzuladen:
python -m twine upload --repository pypi dist/ * (Verwenden Sie bei Bedarf testpypi anstelle von pypi )
Übrigens, wenn Sie das JavaScript -Paket (JavaScript) in der NPM -Registrierung veröffentlichen möchten, wenden Sie sich zum Beispiel -TypeScript -Paket, das auf NPM für 2021 veröffentlicht werden kann.
