Организация структуры проекта на Python

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

В этом руководстве мы пошагово рассмотрим процесс структурирования проекта на Python, с объяснениями лучших практик и примерами, иллюстрирующими каждый шаг.

Шаг 1: Создайте корневой каталог проекта

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

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

Пример

my_project/

Шаг 2: Создайте виртуальную среду

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

Создание среды под Linux/macOS

cd my_project
python3 -m venv venv

Для Windows

python -m venv venv

После создания активируйте его:

• Linux/macOS: source venv/bin/activate
• Windows: venv\Scripts\activate

Теперь ваши зависимости будут установлены в этой среде.

Шаг 3: Определите основную структуру каталогов

Структура вашего ядра проекта должна включать каталог для вашего пакета или модуля, каталог tests/ и файлы установки, конфигурации в корне.

Пример

my_project/
│
├── my_package/           # Основной каталог пакетов
│   ├── __init__.py       # Превращает каталог в пакет
│   ├── module1.py
│   ├── module2.py
│   └── utils.py
│
├── tests/                # Тесты для каждого модуля или функциональности
│   ├── __init__.py
│   ├── test_module1.py
│   ├── test_module2.py
│   └── test_utils.py
│
├── venv/                 # Каталог виртуальной среды (игнорируется в .gitignore)
│
├── requirements.txt      # Список зависимостей проекта
│
└── README.md             # Описание проекта и его использование

Описание каждого компонента

• my_package/: Содержит основной код вашего проекта.
• tests/: Содержит модульные тесты для каждого модуля, которые помогут с проверкой кода.
• requirements.txt: Выводит список зависимостей. Сгенерируйте его с помощью pip freeze > requirements.txt.
• README.md: Описывает проект и инструкции по использованию, которые помогают другим понять, как им пользоваться.

Шаг 4. Написание файла __init__.py

Файл __init__.py используется для инициализации пакета Python. Поместите его в каждый каталог, который вы хотите рассматривать как пакет.

Этот файл также может определять, что импортируется при импорте пакета.

Пример __init__.py для my_package/

# my_package/__init__.py
from .module1 import function1
from .module2 import function2

Теперь вы можете напрямую использовать from my_package import function1

Шаг 5: Добавьте конфигурационные файлы

Некоторые конфигурационные файлы помогают автоматизировать тестирование, компоновку и развертывание.

1. .gitignore

Добавьте файл .gitignore, чтобы указать файлы и каталоги, которые Git должен игнорировать.

Пример .gitignore:

venv/
__pycache__/
*.pyc

2. requirements.txt

Для управления зависимостями необходим список пакетов в requirements.txt:

pip install some_package
pip freeze > requirements.txt

Шаг 6: Подготовка тестов

Для тестирования используйте pytest или unittest. Для начала создайте файлы тестов в каталоге tests/.

Пример файла теста tests/test_module1.py

# tests/test_module1.py

import pytest
from my_package.module1 import function1

def test_function1():
    result = function1()
    assert result == expected_output  # заменить на фактический ожидаемый результат

Запуск тестов из терминала:

pytest tests/

Шаг 7: Создайте setup.py для упаковки (необязательно)

Если вы хотите распространять свой пакет, добавьте файл setup.py, который сообщает Python, как собрать и установить пакет.

Пример setup.py

from setuptools import setup, find_packages

setup(
    name="my_project",
    version="0.1",
    packages=find_packages(),
    install_requires=[
        "some_package>=1.0.0",
    ],
)

Чтобы установить пакет локально:

pip install -e .

Это позволяет импортировать my_package без указания полного пути.

Шаг 8: Документируйте проект

Документация облегчает другим (и вам самим) понимание и использование проекта.

Обновите README.md, чтобы предоставить обзор, инструкции по установке и примеры использования.

Пример README.md

# Мой проект

## Описание
Этот проект делает определенные действия.

## Установка
1. Склонируйте репозиторий.
2. Установите зависимости: `pip install -r requirements.txt`.

## Использование
```python
from my_package import function1
function1()

Такая структура упорядочивает вашу кодовую базу, упрощая ее разработку, тестирование и сопровождение.