example_pypi_package
v0.1.0
Это пример пакета PYPI (Python Package Index), настроенный с автоматическими тестами и рабочим процессом публикации пакетов с использованием GitHub Actions CI/CD. Он сделан в основном для пользователей GitHub + VS (Windows / Mac / Linux), которые собираются написать и опубликовать свой первый пакет PYPI. Пакет может служить стартером / коткой / демонстрацией, а учебник может дать вам быстрое и краткое объяснение, чтобы решить некоторые небольшие, но раздражающие проблемы, с которыми вы можете столкнуться, такие как путаница с именем пакета / модуля и проблемы с конфигурацией тестирования кода.
Этот пример пакет вдохновлен / основан на официальном образце проекта Pypa / SampleProject, но этот пакет:
master или main Branch и публикуется при создании выпускаPYTHONPATH , чтобы тестовые файлы не имели ошибок на листаре и могут работать с Pytest в коде VS(Нажмите кнопку выше, чтобы использовать этот пакет примеров в качестве шаблона для вашего нового репозитория GitHub, это инициализирует новый репозиторий, и мои коммиты не будут в вашей истории GIT)
(Если вы не используете GitHub, вы можете загрузить архив примеров пакета)
Многие используют одинаковый имя пакета и модуля, вы определенно можете это сделать. Но этот пример пакета и имена его модуля отличаются: example_pypi_package и examplepy .
Откройте папку example_pypi_package с кодом Visual Studio, Ctrl + Shift + F (Windows / Linux) или CMD + Shift + F (MacOS), чтобы найти все входы обоих имен и заменить их на имена пакета и модуля. Также не забудьте изменить имя папки SRC/Примерпи .
Просто и очень грубо говоря, имя пакета используется в pip install <PACKAGENAME> , а имя модуля используется в import <MODULENAME> . Оба имена должны состоять из строчных основных букв (AZ). У них могут быть недостатки ( _ ), если они вам действительно нужны. Дефис -минус ( - ) не должен использоваться.
Вам также необходимо убедиться, что URL "https://pypi.org/project/example-pypi-package/" (замените example-pypi-package под именем вашего пакета, причем _ - ) не заняты.
Подчеркивание ( _ ) может быть использовано, но такое использование не рекомендуется. Числа могут использоваться, если имя не начинается с номера, но такое использование также не рекомендуется.
Имя, начиная с числа и/или содержащего дефис -минус ( - ) importlib не должно использоваться: хотя технически законно, такое имя вызывает много проблем.
Не одурачивайте URL "pypi.org/project/example-pypi-package/" и название "Пример Pypi-package" на pypi.org. System Pypi.org и PIP преобразуют все _ to - и используйте последнее на веб -сайте / в команде pip , но настоящее имя все еще с _ , которое пользователи должны использовать при импорте пакета.
Есть также пространство имен для использования, если вам нужны подпакинги.
Внесите необходимые изменения в setup.py .
Номер версии пакета __version__ находится в src/examplepy/__ init__.py . Вы можете изменить это.
Пример пакета предназначен для совместимости с Python 3.6, 3.7, 3.8, 3.9, и будет протестирован на эти версии. Если вам нужно изменить диапазон версий, вам следует изменить:
classifiers , python_requires in setup.pyenvlist в Tox.inimatrix: python: в .github/workflows/test.yml Если вы планируете загрузить в TestPypi, которая является игровой площадкой PYPI для цели тестирования, измените twine upload --repository pypi dist/* на twine upload --repository testpypi dist/* в файле .github/workflows/release.yml .
PIP - это менеджер пакетов Python. У вас уже есть PIP, если вы используете Python 3.4 и более позднюю версию, которая включает ее по умолчанию. Прочитайте это, чтобы узнать, как проверить, установлен ли PIP. Прочитайте это, если вам нужно установить его.
Visual Studio Code - самый популярный редактор кода сегодня, наш пример пакет настроен на работу с VS -кодом.
Установите расширение кода "Python".
«Python» против расширения кода предложит вам установить Pylint. Кроме того, пример пакета настроен на использование Pytest с расширениями VS Code + Python, поэтому установите Pylint и Pytest:
pip install pylint pytest(Вполне вероятно, что вам будет предложено установить их, если это так, вам не нужно печатать и выполнять команду)
Содержание vscode.env теперь является PYTHONPATH=/;src/;${PYTHONPATH} , который хорош для Windows. Если вы используете Linux или MacOS, вам нужно изменить его на PYTHONPATH=/:src/:${PYTHONPATH} (замена ; с : . Если путь не установлен должным образом, вы увидите ошибки вкладки в тестовых файлах, а Pytest не сможет запускать тесты/тест _*. PY -файлы правильно.
Закрыть и открыть код. Теперь вы можете щелкнуть значок лабораторной колбы в левом меню и запустить все тесты там, с Pytest. Pytest кажется лучше, чем стандартная структура Unittest, он поддерживает unittest таким образом, вы можете продолжать использовать import unittest в своих тестовых файлах.
Пример пакета также имеет файл .editorConfig . Вы можете установить расширение кода VS «EditorConfig для VS -кода», который использует файл. С текущей конфигурацией, инструмент EditorConfig может автоматически использовать пространства (4 пространства для .py, 2 для других) для вдавления, установить кодирование UTF-8 , LF конец линий, пробелы для обрезки в файлах без уценки и т. Д.
В коде VS вы можете перейти к File -> Preferences -> Настройки, введите «Поставщик форматирования Python» в поле поиска и выбрать один из трех инструментов форматирования кода Python (Autopep8, Black и YAPF), вам будет предложено установить его. Ярлыки для форматирования кодового файла являются Shift + Alt + F (Windows); Shift + Option (alt) + F (macOS); Ctrl + shift + i (linux).
В папке src/ examplepy/ ( examplepy должен быть заменен на имя модуля), ренезовая модуль1.py и напишите в нем ваш код. Добавьте больше файлов модуля .py, если вам нужно.
В тестах/ папке переименование test_module1.py (для тестирования _*. Py ) и напишите в нем код вашего модульного тестирования (с Unittest). Добавьте больше теста _*. PY -файлов, если вам нужно.
Установите Tox и запустите его:
pip install tox
tox В нашей конфигурации Tox запускает проверку распределения источника, используя Manifest Check-Manifest (который требует, чтобы ваш репо был инициализирован GIT ( git init ) и добавлен (по крайней мере git add . ), по крайней мере), проверку Setuptools и модульные тесты с использованием Pytest. Вам не нужно устанавливать чек-манифест и Pytest, хотя Tox установит их в отдельной среде.
Автоматизированные тесты выполняются против нескольких версий Python, но на вашей машине вы можете использовать только одну версию Python, если это Python 3.9, затем запустите:
tox -e py39 Если вы добавите больше файлов в корневый каталог ( example_pypi_package/ ), вам необходимо добавить свой файл в список check-manifest --ignore в tox.ini .
Установите или обновите setuptools и wheel :
python -m pip install --user --upgrade setuptools wheel (Если python3 является командой на вашей машине, измените python на python3 в вышеуказанной команде или добавьте alias python=python3 на ~/.bashrc или ~/.bash_aliases , если вы используете Bash на Linux)
dist Из каталога example_pypi_package запустите следующую команду, чтобы создать производственную версию для распределения источника (SDIST) в dist Polder:
python setup.py sdist bdist_wheelНеобязательно, вы можете установить Dist версию вашего пакета локально перед загрузкой в PYPI или TestPypi:
pip install dist/example_pypi_package-0.1.0.tar.gz(Возможно, вам нужно сначала удалить существующий пакет:
pip uninstall example_pypi_package Может быть несколько установленных пакетов с одним и тем же именем, поэтому запустите pip uninstall несколько раз, пока он не скажет, что нет пакета для удаления.)
Зарегистрируйте учетную запись на PYPI, перейдите в настройки учетной записи § Токены API, «добавьте токен API». Токен PYPI появляется только один раз, скопируйте его где -нибудь. Если вы пропустили это, удалите старый и добавьте новый токен.
(Зарегистрируйте учетную запись TestPypi, если вы загружаете в TestPypi)
На странице вашего вновь созданного или существующего репозитория GitHub нажмите «Настройки» -> «Секреты» -> Новый секрет хранилища , имя должно быть PYPI_API_TOKEN , и значение должно быть вашим токеном pypi (который начинается с pypi- ).
Пример пакета имеет автоматизированные тесты и загрузку (публикация) уже настроены с помощью GitHub Actions:
git push или запрос на вытягивание в вашем master или main ветви, пакет автоматически проверяется на желаемые версии Python с действиями GitHub. После того, как ваш пакет опубликован на PYPI, перейдите по адресу https://pypi.org/project/example-pypi-package/ ( _ - ). Скопируйте команду на странице, выполните ее, чтобы загрузить и установить пакет из PYPI. (или test.pypi.org, если вы используете это)
Если вы хотите изменить описание / readme вашего пакета на pypi.org, вы должны опубликовать новую версию.
Установить или обновить шпагат:
python -m pip install --user --upgrade twineСоздайте файл .pypirc в вашем каталоге $ home ( ~ ), его содержание должно быть:
[pypi]
username = __token__
password = <PyPI token> (Используйте [testpypi] вместо [pypi] , если вы загружаете в TestPypi)
Замените <PyPI token> на ваш настоящий токен PYPI (который начинается с pypi- ).
(Если вы не создаете вручную $ home/.pypirc , вам будет предложено для имени пользователя (которое должно быть __token__ ) и пароль (который должен быть вашим токеном PYPI), когда вы запускаете шпагат)
Запустите шпагат, чтобы загрузить все архивы в папке Dist :
python -m twine upload --repository pypi dist/ * (Используйте testpypi вместо pypi , если вы загружаете в TestPypi)
Когда вы закончите разработку более новой версии своего пакета, сделайте следующие вещи.
Измените номер версии __version__ в src examplepy__init __. Py .
Удалить все старые версии в Dist .
Запустите следующую команду еще раз, чтобы регенерировать Dist :
python setup.py sdist bdist_wheelЗапустите следующую команду еще раз, чтобы загрузить Dist :
python -m twine upload --repository pypi dist/ * (Используйте testpypi вместо pypi , если это необходимо)
Кстати, если вы хотите опубликовать пакет TypeScript (JavaScript) в реестр NPM, перейдите в пример пакета TypeScript, готовые к опубликованию в NPM за 2021 год.
