Разпространение на Python пакети: Публикуване в PyPI и управление на версиите

Обширната екосистема на Python се задвижва от огромна колекция от пакети, лесно достъпни чрез Python Package Index (PyPI). Това ръководство предоставя изчерпателен преглед на това как да разпространявате вашите собствени Python пакети чрез PyPI, като гарантирате, че те са достъпни за разработчици по целия свят. Ще разгледаме основните инструменти, най-добрите практики за управление на версиите и работните процеси за създаване и публикуване на висококачествени Python пакети.

Защо да разпространявате своя Python пакет?

Разпространението на вашия Python пакет предлага множество предимства:

• Споделяне на вашата работа: Позволява на други разработчици лесно да преизползват вашия код, насърчавайки сътрудничеството и иновациите. Представете си глобален екип, който използва вашите специализирани инструменти за анализ на данни, създадени с Python.
• Управление на зависимости: Опростява процеса на управление на зависимости в други проекти. Вашият пакет може да бъде инсталиран с една команда, заедно с всичките му зависимости.
• Принос към общността с отворен код: Позволява ви да допринасяте за общността с отворен код и да получите признание за вашата работа. Много критични софтуерни компоненти са пакети с отворен код, поддържани от разработчици по целия свят.
• Контрол на версиите и актуализации: Осигурява структуриран начин за управление на версии, издаване на актуализации и отстраняване на грешки. Това гарантира, че потребителите винаги имат достъп до най-новата и най-надеждна версия на вашия пакет.
• Лесна инсталация: Опростява инсталацията за потребителите чрез `pip install име-на-вашия-пакет`.

Основни инструменти за разпространение на Python пакети

Няколко инструмента са от съществено значение за създаването и разпространението на Python пакети:

• setuptools: Широко използвана библиотека за дефиниране на метаданни на пакета, включително име, версия, зависимости и входни точки. Това е стандартът де факто за пакетиране на Python проекти.
• wheel: Формат за разпространение, който осигурява по-ефективен и надежден процес на инсталиране в сравнение с дистрибуциите от изходен код. Wheel пакетите са предварително компилирани дистрибуции, които могат да бъдат инсталирани без необходимост от компилация.
• twine: Инструмент за сигурно качване на вашия пакет в PyPI. Twine криптира вашите идентификационни данни и данни на пакета по време на предаване, предпазвайки от подслушване и атаки от типа „човек по средата“.
• venv/virtualenv: Това са инструменти за създаване на изолирани Python среди. Използването на виртуални среди е от решаващо значение за управлението на зависимости и избягването на конфликти между различни проекти.

Настройване на вашия проект

Преди да можете да разпространите своя пакет, трябва да структурирате проекта си правилно.

Примерна структура на проекта

my_package/
├── my_package/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── tests/
│   ├── __init__.py
│   ├── test_module1.py
│   └── test_module2.py
├── README.md
├── LICENSE
├── setup.py
└── .gitignore

Обяснение:

• my_package/: Главната директория, съдържаща изходния код на вашия пакет.
• my_package/__init__.py: Прави директорията `my_package` Python пакет. Може да бъде празен или да съдържа инициализационен код.
• my_package/module1.py, my_package/module2.py: Вашите Python модули, съдържащи действителния код.
• tests/: Директория, съдържаща вашите unit тестове. От решаващо значение е да пишете тестове, за да гарантирате качеството и надеждността на вашия пакет.
• README.md: Markdown файл, предоставящ описание на вашия пакет, инструкции за употреба и друга релевантна информация. Това често е първото нещо, което потребителите виждат в PyPI.
• LICENSE: Файл, съдържащ лиценза, под който се разпространява вашият пакет (напр. MIT, Apache 2.0, GPL). Изборът на подходящ лиценз е от съществено значение за уточняване как другите могат да използват вашия код.
• setup.py: Основният конфигурационен файл, който дефинира метаданните на вашия пакет и инструкциите за изграждане.
• .gitignore: Указва файлове и директории, които трябва да бъдат игнорирани от Git (напр. временни файлове, артефакти от изграждането).

Създаване на файла `setup.py`

Файлът `setup.py` е сърцето на разпространението на вашия пакет. Той съдържа метаданни за вашия пакет и инструкции за неговото изграждане и инсталиране. Ето един пример:

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="my_package",  # Заменете с името на вашия пакет
    version="0.1.0",
    author="Your Name",  # Заменете с вашето име
    author_email="your.email@example.com", # Заменете с вашия имейл
    description="Малък примерен пакет",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/yourusername/my_package", # Заменете с URL на вашето хранилище
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
    install_requires=[
        "requests", # Примерна зависимост
    ],
)

Обяснение:

• name: Името на вашия пакет, което ще се използва в PyPI. Изберете уникално и описателно име.
• version: Номерът на версията на вашия пакет. Следвайте семантичното версиониране (вижте по-долу).
• author, author_email: Вашето име и имейл адрес.
• description: Кратко описание на вашия пакет.
• long_description: По-дълго, по-подробно описание, обикновено прочетено от вашия `README.md` файл.
• long_description_content_type: Указва формата на вашето дълго описание (напр. "text/markdown").
• url: URL адресът на началната страница на вашия пакет (напр. GitHub хранилище).
• packages: Списък с пакети, които да бъдат включени във вашата дистрибуция. `setuptools.find_packages()` автоматично открива всички пакети във вашия проект.
• classifiers: Метаданни, които помагат на потребителите да намерят вашия пакет в PyPI. Изберете подходящи класификатори от списъка с Trove Classifiers. Обмислете включването на класификатори за поддържани версии на Python, операционни системи и лицензи.
• python_requires: Указва минималната версия на Python, необходима за използване на вашия пакет.
• install_requires: Списък със зависимости, които вашият пакет изисква. Тези зависимости ще бъдат автоматично инсталирани, когато вашият пакет бъде инсталиран.

Управление на версиите: Семантично версиониране

Семантичното версиониране (SemVer) е широко приета схема за версиониране, която осигурява ясен и последователен начин за съобщаване на естеството на промените във вашия пакет.

Номерът на версията по SemVer се състои от три части: MAJOR.MINOR.PATCH.

• MAJOR: Увеличава се, когато правите несъвместими промени в API. Това показва значителна промяна, която може да изисква от потребителите да актуализират своя код.
• MINOR: Увеличава се, когато добавяте функционалност по обратно съвместим начин. Това означава нови функции или подобрения, които не нарушават съществуващия код.
• PATCH: Увеличава се, когато правите обратно съвместими поправки на грешки. Това е за малки поправки, които не добавят нови функции и не нарушават съществуващата функционалност.

Примери:

• 1.0.0: Първоначално издание.
• 1.1.0: Добавена е нова функция без да се нарушава съществуващият код.
• 1.0.1: Поправена е грешка в издание 1.0.0.
• 2.0.0: Направени са несъвместими промени в API.

Използването на SemVer помага на потребителите да разберат въздействието от надграждането до нова версия на вашия пакет.

Изграждане на вашия пакет

След като сте конфигурирали файла си `setup.py`, можете да изградите своя пакет.

1. Създайте виртуална среда: Силно се препоръчва да създадете виртуална среда, за да изолирате зависимостите на вашия пакет. Използвайте `python3 -m venv .venv` (или `virtualenv .venv`) и след това я активирайте (`source .venv/bin/activate` на Linux/macOS, `.venv\Scripts\activate` на Windows).
2. Инсталирайте зависимости за изграждане: Изпълнете `pip install --upgrade setuptools wheel`.
3. Изградете пакета: Изпълнете `python setup.py sdist bdist_wheel`. Тази команда създава два дистрибуционни файла в директорията `dist`: дистрибуция от изходен код (sdist) и wheel дистрибуция (bdist_wheel).

Файлът `sdist` съдържа вашия изходен код и файла `setup.py`. `bdist_wheel` е предварително изградена дистрибуция, която може да бъде инсталирана по-бързо.

Публикуване на вашия пакет в PyPI

Преди да можете да публикувате своя пакет, трябва да създадете акаунт в PyPI (https://pypi.org/) и да създадете API токен. Този токен ще се използва за удостоверяване на вашите качвания.

1. Регистрирайте се в PyPI: Отидете на https://pypi.org/account/register/ и създайте акаунт.
2. Създайте API токен: Отидете на https://pypi.org/manage/account/, превъртете надолу до секцията „API tokens“ и създайте нов токен. Съхранявайте този токен на сигурно място, тъй като ще ви е необходим за качване на вашия пакет.
3. Инсталирайте Twine: Изпълнете `pip install twine`.
4. Качете вашия пакет: Изпълнете `twine upload dist/*`. Ще бъдете подканени за вашето потребителско име (__token__) и парола (API токенът, който сте създали).

Важна забележка за сигурност: Никога не добавяйте (commit) вашия API токен във вашето хранилище. Съхранявайте го на сигурно място и използвайте променливи на средата или други сигурни методи за достъп до него по време на процеса на качване.

Тестване на инсталацията на вашия пакет

След публикуването на вашия пакет е от съществено значение да тествате дали може да бъде инсталиран правилно.

1. Създайте нова виртуална среда: Това гарантира, че тествате инсталацията в чиста среда.
2. Инсталирайте вашия пакет: Изпълнете `pip install име-на-вашия-пакет`.
3. Импортирайте и използвайте вашия пакет: В Python интерпретатор импортирайте вашия пакет и проверете дали работи както се очаква.

Непрекъсната интеграция и непрекъснато внедряване (CI/CD)

За да автоматизирате процеса на изграждане, тестване и публикуване на вашия пакет, можете да използвате CI/CD инструменти като GitHub Actions, GitLab CI или Travis CI.

Ето пример за работен процес на GitHub Actions, който изгражда и публикува вашия пакет в PyPI:

name: Publish to PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Set up Python 3.x
      uses: actions/setup-python@v2
      with:
        python-version: 3.x
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install setuptools wheel twine
    - name: Build package
      run: python setup.py sdist bdist_wheel
    - name: Publish package to PyPI
      run: |
        twine upload dist/* \
          -u __token__ \
          -p ${{ secrets.PYPI_API_TOKEN }}

Обяснение:

• Този работен процес се задейства, когато се публикува ново издание в GitHub.
• Той изтегля кода, настройва Python, инсталира зависимости, изгражда пакета и го качва в PyPI.
• secrets.PYPI_API_TOKEN е GitHub secret, който съхранява вашия PyPI API токен. Трябва да конфигурирате този secret в настройките на вашето GitHub хранилище.

Добри практики за разпространение на Python пакети

• Пишете изчерпателна документация: Включете подробен `README.md` файл, както и API документация, използвайки инструменти като Sphinx. Ясната и пълна документация е от решаващо значение, за да направите вашия пакет лесен за използване.
• Пишете unit тестове: Тествайте щателно вашия код, за да гарантирате неговото качество и надеждност. Използвайте рамка за тестване като pytest или unittest.
• Следвайте указанията за стил на PEP 8: Придържайте се към ръководството за стил на Python Enhancement Proposal 8 (PEP 8), за да осигурите последователен и четим код.
• Използвайте лиценз: Изберете подходящ лиценз с отворен код, за да посочите как другите могат да използват вашия код.
• Поддържайте зависимостите си актуални: Редовно актуализирайте зависимостите на вашия пакет, за да се възползвате от поправки на грешки, пачове за сигурност и нови функции.
• Използвайте виртуална среда: Винаги разработвайте и тествайте вашия пакет в рамките на виртуална среда, за да изолирате зависимостите.
• Обмислете интернационализация (i18n) и локализация (l10n): Ако вашият пакет обработва текст или данни, предназначени за потребители, обмислете възможността да го направите приспособим към различни езици и региони. Това разширява потенциалната ви потребителска база в световен мащаб. Инструменти като Babel могат да помогнат с това.
• Работете с различни часови зони и валути: Ако вашият пакет се занимава с дати, часове или финансови трансакции, имайте предвид различните часови зони и валути по света. Използвайте подходящи библиотеки и API, за да се справите правилно с тези сложности.
• Предоставяйте ясни съобщения за грешки: Пишете информативни съобщения за грешки, които помагат на потребителите да разберат какво се е объркало и как да го поправят. Преведете тези съобщения за грешки на различни езици, ако е възможно.
• Мислете за достъпността: Вземете предвид потребителите с увреждания, когато проектирате интерфейса и документацията на вашия пакет. Следвайте указанията за достъпност, за да гарантирате, че вашият пакет е използваем от всички.

Теми за напреднали

• Namespace пакети: Позволяват ви да разделите един Python пакет в няколко директории или дори в няколко дистрибуции.
• Входни точки (Entry points): Позволяват ви да дефинирате функции или класове, които могат да бъдат извиквани от други пакети или от командния ред.
• Файлове с данни: Позволяват ви да включите файлове, които не са на Python (напр. файлове с данни, конфигурационни файлове) във вашата дистрибуция.
• Условни зависимости: Позволяват ви да посочите зависимости, които са необходими само при определени условия (напр. на конкретна операционна система).

Заключение

Разпространението на вашия Python пакет в PyPI е чудесен начин да споделите работата си със света и да допринесете за екосистемата на Python. Като следвате стъпките и най-добрите практики, описани в това ръководство, можете да създавате и публикувате висококачествени Python пакети, които са лесни за инсталиране, използване и поддръжка. Не забравяйте да дадете приоритет на ясната документация, щателното тестване и последователното управление на версиите, за да гарантирате успеха на вашия пакет.