Конфигурация Python приложения: инструменты и файлы настройки

Раздел: Разработка на Python -> IDE и редакторы

Настройка Python-проекта: выбор конфигурации

Основное эффективное решение: использование pyproject.toml с Poetry

Современный стандарт конфигурации Python-проекта - файл pyproject.toml в сочетании с инструментом Poetry. Poetry автоматически создаёт виртуальное окружение, управляет зависимостями, сборкой и публикацией пакета. Файл pyproject.toml заменяет setup.py, setup.cfg и requirements.txt.

Как создать проект с помощью Poetry и настроить зависимости?

poetry new my_project
cd my_project
poetry add requests numpy

Python packaging tools (python packaging tools (инструменты сборки))

После выполнения команды poetry new создаётся структура каталогов, а в корне - pyproject.toml с начальной конфигурацией. Команда poetry add добавляет пакеты и обновляет файл.

Типичные ошибки и их решение:

Ошибка установки Poetry - если Python версии ниже 3.7. Решение: обновить Python или установить Poetry через pip: pip install poetry.
Конфликт версий зависимостей - Poetry использует строгое разрешение зависимостей. Если возникает неразрешимый конфликт, следует ослабить ограничения в разделе [tool.poetry.dependencies], например указав ^1.0 вместо ^1.2.
Отсутствие виртуального окружения - Poetry создаёт его автоматически. Если окружение не активируется, проверить настройки в poetry config virtualenvs.in-project true (создаёт .venv внутри проекта).

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

Как управлять зависимостями с помощью requirements.txt и virtualenv?

Классический подход - ручное создание виртуального окружения и файла requirements.txt. Этот метод остаётся актуальным для простых проектов или при необходимости точного контроля.

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate.bat # Windows
pip install flask==2.3.0
pip freeze > requirements.txt

Python online код (онлайн редактор python)

Команда pip freeze записывает все установленные пакеты с версиями в файл. При развёртывании достаточно выполнить pip install -r requirements.txt.

Частые проблемы:

Забытое окружение - если окружение не активировано, пакеты устанавливаются глобально. Решение: всегда проверять наличие (.venv) в приглашении терминала.
Различия между платформами - в requirements.txt могут быть пакеты, специфичные для ОС (например, pywin32). Лучше указывать без привязки к платформе или использовать несколько файлов: requirements-linux.txt.
Отсутствие requirements.txt в репозитории - рекомендуется добавлять его в Git для воспроизводимости.

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

Как создать распространяемый пакет с помощью setup.py?

Традиционный способ упаковки Python-проекта - файл setup.py. Он определяет метаданные и зависимости, позволяя установить пакет через pip install ..

from setuptools import setup, find_packages

setup(
    name='example-pkg',
    version='0.1.0',
    packages=find_packages(),
    install_requires=[
        'requests>=2.20',
        'numpy',
    ],
    entry_points={
        'console_scripts': [
            'example-cli=example.main:cli',
        ],
    },
)

Find python script (поиск python скрипта)

После создания файла setup.py выполнить pip install -e . для разработки (редактируемая установка) или python setup.py sdist bdist_wheel для сборки дистрибутива.

Возможные ошибки:

Импорт setuptools не найден - пакет setuptools не установлен. Решение: pip install setuptools.
Конфликты с pyproject.toml - если в проекте присутствуют оба файла, приоритет имеет pyproject.toml. Рекомендуется использовать что-то одно.
Ошибки в кодировке paths - недопустимые символы в названиях пакетов. Имена должны соответствовать PEP 8.

Используется для публикации библиотек на PyPI или для внутреннего распространения пакетов.

Как автоматизировать управление окружением и зависимостями с Pipenv?

Pipenv сочетает виртуальное окружение и управление зависимостями в одном инструменте. Создаёт файлы Pipfile и Pipfile.lock.

pip install pipenv
pipenv install requests
pipenv shell

Compiled python file (скомпилированные файлы python (.pyc))

Команда pipenv install добавляет пакет в Pipfile и устанавливает его в новое виртуальное окружение. pipenv shell активирует окружение.

Проблемы и их решение:

Медленная работа - Pipenv может долго разрешать зависимости. Решение: обновить Pipenv до последней версии или использовать --skip-lock при разработке.
Конфликты с системными пакетами - изолировать окружение через pipenv --python 3.10.
Отсутствие Pipenv в CI - можно сгенерировать requirements.txt из Pipfile: pipenv requirements > requirements.txt.

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

Как настроить проект в IDE (VS Code, PyCharm) для работы с выбранной конфигурацией?

Независимо от выбранного инструмента, важно правильно указать интерпретатор и виртуальное окружение в среде разработки.

# В VS Code: Ctrl+Shift+P -> Python: Select Interpreter -> Выбрать путь к .venv или poetry env
# В PyCharm: File -> Settings -> Project -> Python Interpreter -> Add -> Existing environment

Частая ошибка:

Интерпретатор не видит установленные пакеты - окружение не активировано в IDE. В VS Code файл .vscode/settings.json должен содержать "python.terminal.activateEnvironment": true.

Настройка IDE позволяет пользоваться автодополнением, проверкой типов и отладкой.

- Microsoft vs python (python в visual studio)

- Microsoft code python (настройка python в visual studio code)

- Format python code (форматирование кода python)

Расширенные примеры конфигурации Python-проекта

1. Пример pyproject.toml для проекта с тестированием и линтингом

Пример

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

[tool.poetry]
name = "advanced-app"
version = "0.2.0"
description = "Пример продвинутой конфигурации"
authors = ["Разработчик "]
license = "MIT"
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.9"
fastapi = "^0.100.0"
uvicorn = {version = "^0.22.0", extras = ["standard"]}

[tool.poetry.group.dev.dependencies]
pytest = "^7.4"
black = "^23.7"
ruff = "^0.0.290"

[tool.poetry.scripts]
start = "app.main:run"

[tool.black]
line-length = 88

[tool.ruff]
select = ["E", "F", "W"]
ignore = ["E501"]

После создания файла выполнить:

Пример

poetry install  # установка основных и dev-зависимостей
poetry run pytest  # запуск тестов в окружении Poetry
poetry run black .  # форматирование кода
poetry run ruff check .  # линтинг

# Результат выполнения `poetry run pytest`
============================= test session starts ==============================
collected 10 items

tests/test_app.py ..........                                          [100%]

============================== 10 passed in 0.35s ===============================

2. Пример requirements.txt с указанием опциональных зависимостей

Пример

# requirements.txt
flask==2.3.3
flask-sqlalchemy==3.1.0
psycopg2-binary==2.9.9

# Для разработки (устанавливается отдельно)
# requirements-dev.txt
pytest==7.4.0
pytest-cov==4.1.0
black==23.7.0

Пример

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt  # если нужно
pip freeze | grep -E "^(pytest|black)"

pytest==7.4.0
black==23.7.0

Для воспроизводимости можно использовать pip freeze > full-requirements.txt.

3. Пример setup.py с точкой входа и тестовыми зависимостями

Пример

from setuptools import setup, find_packages

setup(
    name='cli-tool',
    version='1.0.0',
    packages=find_packages(include=['cli_tool', 'cli_tool.*']),
    install_requires=[
        'click>=8.0',
        'requests',
    ],
    extras_require={
        'dev': ['pytest', 'flake8'],
        'test': ['pytest'],
    },
    entry_points={
        'console_scripts': [
            'cli-tool=cli_tool.main:cli',
        ],
    },
    python_requires='>=3.8',
)

Установка в режиме разработки и запуск тестов:

Пример

pip install -e .[dev]
pytest --cov=cli_tool

collected 5 items

tests/test_main.py .....                                          [100%]

---------- coverage: platform linux, python 3.10.6 -----------
Name                 Stmts   Miss  Cover
----------------------------------------
cli_tool/main.py       20      0   100%
----------------------------------------
TOTAL                  20      0   100%

4. Пример Pipfile для проекта с несколькими источниками

Пример

[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[[source]]
url = "https://private-repo.example.com/simple"
verify_ssl = false
name = "private"

[packages]
requests = "*"
my-private-pkg = {version = "*", source = "private"}

[dev-packages]
pytest = "*"

[requires]
python_version = "3.10"

Установка:

Пример

pipenv install --dev
pipenv graph

requests==2.31.0
  - certifi [required: >=2017.4.17, installed: 2023.7.22]
  - chardet [required: >=3.0.2,<5,>=3.0.2,<6, installed: 5.1.0]
  ...
my-private-pkg==1.0.0
pytest==7.4.0 [dev]

Настройка Python-проекта - comments

Python configure py (python)