Python Academy · Урок

Версии и метаданные

Управляйте метаданными пакета

«Версии и метаданные» — бесплатный урок Python Academy на CoddyKit. Это урок 3 из 4. Ты можешь прочитать весь урок бесплатно ниже — а потом практиковать его прямо в браузере с встроенным редактором кода и ИИ-репетитором 24/7. Это часть пути обучения Python Academy, и твой прогресс синхронизируется между веб-версией и приложением CoddyKit. Курс Python Academy содержит 4 уроков всего.

Почему важны метаданные

Метаданные — это всё, что относится к вашему пакету, кроме кода: его версия, описание, лицензия, автор и ссылки. PyPI использует их для отображения проекта, а pip — для разрешения зависимостей.

Хорошие метаданные делают пакет надёжным и пригодным для установки.

Семантическое версионирование

Принято использовать схему MAJOR.MINOR.PATCH:

MAJOR — изменения, нарушающие обратную совместимость
MINOR — новые функции, совместимые с предыдущими версиями
PATCH — исправления ошибок, совместимые с предыдущими версиями

Пользователи полагаются на эту схему, чтобы понимать, безопасно ли обновление.

version = '2.4.1'
major, minor, patch = version.split('.')
print('Major', major, 'Minor', minor, 'Patch', patch)
print('Bug fix -> bump patch to', major + '.' + minor + '.' + str(int(patch) + 1))

Выбор следующей версии

Решение о bump определяется правилами: нарушили ли вы программный интерфейс, добавили функцию или просто исправили ошибку? Формализация этого правила делает выпуски единообразными.

def bump(version, kind):
    major, minor, patch = (int(x) for x in version.split('.'))
    if kind == 'major':
        return str(major + 1) + '.0.0'
    if kind == 'minor':
        return str(major) + '.' + str(minor + 1) + '.0'
    return str(major) + '.' + str(minor) + '.' + str(patch + 1)

print(bump('1.2.3', 'minor'))
print(bump('1.2.3', 'major'))

Предварительные и разрабатываемые версии

Python допускает суффиксы: 1.0.0a1 (альфа-версия), 1.0.0b2 (бета-версия), 1.0.0rc1 (кандидат на выпуск) и 1.0.0.dev3. pip считает такие версии более ранними, чем финальная 1.0.0, поэтому тестировщики могут выбрать их, не затрагивая обычных пользователей.

Единственный источник истины

Храните версию ровно в одном месте. Либо укажите её статически в pyproject.toml, либо пометьте как dynamic и считывайте из кода (или метки) с помощью таких инструментов, как setuptools-scm. Две копии неизбежно начинают расходиться.

Описание и README

Краткое description отображается в результатах поиска. Развёрнутое описание берётся из вашего readme (обычно README.md) и отображается на странице проекта в PyPI. Укажите его с помощью readme = 'README.md'.

Понятный README — лучший способ продвижения вашего проекта.

Лицензия

Укажите лицензию, чтобы пользователи знали свои права. В современных проектах используется выражение SPDX, например license = 'MIT'. Отсутствие лицензии означает, что все права защищены, и препятствует распространению пакета.

popular = ['MIT', 'Apache-2.0', 'BSD-3-Clause', 'GPL-3.0-only']
for lic in popular:
    print('SPDX:', lic)

Классификаторы

classifiers — это стандартизированные метки из списка PyPI, например 'Programming Language :: Python :: 3.11' или 'Development Status :: 4 - Beta'. Они обеспечивают работу фильтров PyPI и показывают степень готовности и поддерживаемые версии.

Ссылки проекта

В разделе [project.urls] добавьте такие ссылки, как «Главная страница», «Документация», «Исходный код» и «Журнал изменений». Они отображаются на боковой панели PyPI и помогают пользователям найти репозиторий и документацию.

urls = {
    'Homepage': 'https://example.com',
    'Source': 'https://github.com/me/mytool',
    'Issues': 'https://github.com/me/mytool/issues',
}
for label, link in urls.items():
    print(label.ljust(10), link)

Ключевые слова для поиска

Поле keywords содержит список коротких терминов, которые помогают пользователям найти ваш пакет в результатах поиска. Выбирайте слова, которые люди действительно стали бы вводить, например ['cli', 'automation', 'excel'], а не общие слова-заполнители.

Вместе с классификаторами ключевые слова повышают заметность вашего проекта.

CHANGELOG

Ведите CHANGELOG, где записывайте изменения в каждой версии. Пользователи читают его перед обновлением, чтобы узнать о новых функциях и изменениях, нарушающих обратную совместимость. Если добавить ссылку на него в разделе [project.urls], перейти к нему со страницы PyPI можно будет одним щелчком.

Хороший журнал изменений превращает номер версии в историю, за которой пользователи могут следить.

Быстрая проверка

Проверьте свои знания о версиях.

Итоги

Вы научились управлять метаданными пакета:

Семантическое версионирование MAJOR.MINOR.PATCH, а также суффиксы предварительных выпусков
Хранить версию в едином источнике истины
Указывать description, расширенное описание в README и license
Добавлять classifiers и [project.urls], чтобы PyPI хорошо отображал сведения о проекте

Часто задаваемые вопросы

Урок «Версии и метаданные» бесплатный?

Да — полный текст урока «Версии и метаданные» бесплатно доступен здесь в веб-версии. Чтобы практиковать его интерактивно (встроенный редактор кода и ИИ-репетитор 24/7) и разблокировать остальной курс Python Academy, подпишись на CoddyKit PRO. Курс Python Academy содержит 4 уроков всего.

Чему я научусь в уроке «Версии и метаданные»?

Управляйте метаданными пакета Ты практикуешь Python Academy с помощью реального кода, который запускаешь прямо в браузере, и ИИ-репетитор 24/7 отвечает на твои вопросы во время урока.

Нужен ли мне опыт, чтобы начать Python Academy?

Предыдущий опыт не требуется. Python Academy на CoddyKit структурирован для всех уровней — от новичков до продвинутых, поэтому ты можешь начать отсюда или с самого начала и учиться в своем темпе. Это урок 3 из 4.

Сколько времени занимает урок «Версии и метаданные»?

Большинство уроков CoddyKit занимают около 5–10 минут. Каждый из них компактный и интерактивный, поэтому ты постоянно делаешь прогресс и продолжаешь с того же места в веб-версии и приложении.

Можно ли писать и запускать код в этом уроке Python Academy?

Да. Каждый урок Python Academy включает встроенный редактор кода, поэтому ты пишешь и запускаешь реальный код прямо в браузере и получаешь моментальную обратную связь от AI — локальная установка не требуется.

Все уроки этого курса

← Назад к Python Academy