Python Academy · Урок

Структура проекта и pyproject.toml

Q: Урок «Структура проекта и pyproject.toml» бесплатный?

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

Q: Чему я научусь в уроке «Структура проекта и pyproject.toml»?

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

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

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

Q: Сколько времени занимает урок «Структура проекта и pyproject.toml»?

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

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

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

Размещайте содержимое пакета

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

Зачем упаковывать код

Скрипт существует на вашем компьютере, а пакет может установить любой пользователь с помощью pip install. Упаковка превращает папку с кодом в распространяемый, версионируемый и пригодный для повторного использования компонент.

Первый шаг — аккуратная структура проекта и конфигурационный файл.

Структура src

Рекомендуемая структура помещает импортируемый код в каталог src/:

src/mypackage/__init__.py
src/mypackage/core.py
pyproject.toml
README.md и tests/

Структура src не позволяет случайно импортировать код из корня проекта вместо установленной копии.

Файл init.py

__init__.py помечает каталог как импортируемый пакет и выполняется при первом импорте пакета. Здесь также можно открыть общедоступный программный интерфейс, импортировав его основные имена.

Даже пустого файла __init__.py достаточно, чтобы создать пакет.

package_dir = 'src/mypackage'
files = ['__init__.py', 'core.py', 'utils.py']
for f in files:
    print(package_dir + '/' + f)
print('Importable as:', 'mypackage')

Что такое pyproject.toml

pyproject.toml — это единый стандартизированный конфигурационный файл (PEP 518/621) для современной упаковки Python-проектов. В большинстве проектов он заменяет старый setup.py, и его читают инструменты сборки.

В нём используется формат TOML: разделы заключаются в квадратные скобки, а строки имеют вид «ключ = значение».

Таблица системы сборки

Таблица [build-system] сообщает инструментам, как собрать ваш пакет. Распространённый вариант:

requires = ['setuptools', 'wheel']
build-backend = 'setuptools.build_meta'

Существуют и другие серверы сборки, например Hatchling и Flit; принцип тот же.

Таблица проекта

Таблица [project] содержит метаданные: name, version, description, authors, readme, requires-python и dependencies. Именно это видят пользователи на PyPI.

Считайте её удостоверением личности вашего пакета.

project = {
    'name': 'mytool',
    'version': '0.1.0',
    'requires-python': '>=3.9',
    'dependencies': ['requests>=2.0'],
}
for k, v in project.items():
    print(k, '=', v)

Правила именования

Имя пакета должно быть уникальным на PyPI и подчиняется правилам нормализации: регистр не учитывается, а дефисы и символы подчёркивания считаются одинаковыми. Проверьте доступность имени до окончательного выбора, чтобы избежать конфликта при загрузке.

name = 'My_Cool.Tool'
normalized = name.lower().replace('_', '-').replace('.', '-')
print('PyPI normalized name:', normalized)

Объявление зависимостей

Перечисляйте зависимости времени выполнения в разделе dependencies, указывая ограничения версий, например 'requests>=2.28,<3'. Необязательные дополнительные зависимости указываются в разделе [project.optional-dependencies] и устанавливаются с помощью pip install mytool[dev].

Делайте ограничения настолько свободными, насколько это безопасно, чтобы ваш пакет мог сосуществовать с другими.

Точки входа

Чтобы поставлять инструмент командной строки, добавьте в раздел [project.scripts] запись вроде mytool = 'mypackage.cli:main'. После установки ввод команды mytool запускает эту функцию. Так интерфейсы командной строки, например black или pytest, предоставляют свои команды.

Включение файлов, не содержащих кода

Файлы данных (шаблоны, JSON) не включаются автоматически. Настройте включение данных пакета в сервере сборки, чтобы файлы попали внутрь готового архива. Если забыть об этом, часто возникают ошибки, когда всё работает локально, но ломается после установки.

Установка в режиме редактирования для разработки

Во время разработки установите пакет в режиме редактирования с помощью pip install -e .. Изменения в исходном коде вступают в силу сразу, без повторной установки. Для этого нужен корректный pyproject.toml, что служит ещё одной причиной настроить его заранее.

Установка в режиме редактирования обеспечивает самый быстрый цикл обратной связи при работе над пакетом.

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

Проверьте свои знания о структуре проекта.

Итоги

Вы создали структуру пакета:

Используйте структуру src, где __init__.py помечает пакеты
pyproject.toml — стандартный конфигурационный файл: [build-system] и [project]
Объявите name, version, requires-python и dependencies
Добавьте точки входа [project.scripts] для интерфейсов командной строки и настройте данные пакета

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

Урок «Структура проекта и pyproject.toml» бесплатный?