Краткая структура программы на Python

1. Простейшая структура (Скрипт)

Самый базовый вариант — линейное выполнение кода сверху вниз. Обычно используется для небольших задач, автоматизации или прототипов.

python

# 1. Импорт библиотек
import os
import sys
from datetime import datetime

# 2. Определение констант (обычно ЗАГЛАВНЫМИ буквами)
MAX_RETRIES = 3
CONFIG_PATH = "./config.json"

# 3. Определение функций
def calculate_sum(a, b):
"""Возвращает сумму двух чисел."""
return a + b

def main_logic():
"""Основная логика программы."""
print("Программа запущена")
result = calculate_sum(10, 20)
print(f"Результат: {result}")
return result

# 4. Точка входа (Guard)
if __name__ == "__main__":
# Код выполняется только если файл запущен напрямую (не импортирован как модуль)
main_logic()

2. Структура модуля (Библиотека)

Если вы пишете код, который будут импортировать другие, структура становится более строгой: публичное API отделяется от внутренней реализации.

python

# module_name.py

# 1. Приватные (внутренние) функции (с _)
def _validate_input(data):
"""Внутренняя функция. Не предназначена для импорта."""
if not data:
raise ValueError("Data is empty")
return True

# 2. Публичные функции (API)
def process_data(data):
"""Главная функция, которую будут использовать пользователи модуля."""
_validate_input(data)
return [x * 2 for x in data]

# 3. Переменные уровня модуля (если нужны)
__version__ = "1.0.0"

# 4. Определение того, что импортируется через "from module import *"
__all__ = ["process_data"] # Безопасно, скрывает _validate_input

3. Структура с классами (ООП)

Для более сложных программ, где нужно состояние и поведение.

python

# app/models/user.py

class User:
"""Класс, описывающий пользователя."""

# 1. Конструктор (инициализация)
def __init__(self, username, email):
self.username = username
self.email = email
self._is_active = True # защищенный атрибут

# 2. Методы (поведение)
def get_profile(self):
return f"{self.username} <{self.email}>"

def deactivate(self):
self._is_active = False

# 3. Свойства (property) для контролируемого доступа
@property
def is_active(self):
return self._is_active

# 4. Магические методы
def __str__(self):
return self.username

# Использование
if __name__ == "__main__":
user = User("alice", "alice@example.com")
print(user.get_profile())

4. Структура проекта (Несколько файлов)

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

text

my_project/ # Корень проекта
│
├── pyproject.toml # Современный файл конфигурации (зависимости, инструменты)
├── requirements.txt # Список зависимостей (pip install -r requirements.txt)
├── README.md # Документация
├── .env # Переменные окружения (не в git!)
├── .gitignore # Игнорируемые файлы
│
├── src/ # Исходный код (или my_project/)
│ ├── __init__.py # Делает папку пакетом Python
│ ├── main.py # Точка входа в приложение
│ │
│ ├── models/ # Модуль для моделей данных
│ │ ├── __init__.py
│ │ ├── user.py
│ │ └── product.py
│ │
│ ├── services/ # Бизнес-логика
│ │ ├── __init__.py
│ │ └── payment.py
│ │
│ └── utils/ # Вспомогательные функции
│ ├── __init__.py
│ ├── logger.py
│ └── validators.py
│
├── tests/ # Тесты (зеркалируют структуру src)
│ ├── test_main.py
│ ├── models/
│ │ └── test_user.py
│ └── conftest.py # Фикстуры pytest
│
└── scripts/ # Скрипты для развертывания/утилиты
└── setup_db.py

5. Основные принципы для хорошей структуры

1. if __name__ == "__main__" — обязателен в исполняемых файлах. Позволяет импортировать функции из файла без запуска всей программы.
2. Разделение ответственности — не пишите всё в одном файле (main.py). Выносите модели, логику и утилиты в разные модули.
3. Именование:
   snake_case — для функций, переменных, модулей.
   PascalCase — для классов.
   UPPER_CASE — для констант.
4. Документирование — используйте docstrings (тройные кавычки) для описания того, что делает функция/класс.
5. Виртуальное окружение (venv) — всегда используйте изолированное окружение, чтобы не засорять глобальный Python и управлять зависимостями.

Эта структура масштабируется: от одного файла до крупного фреймворка (Django, FastAPI), который использует ту же философию, но с добавлением своих соглашений.