В этой статье я кратко рассмотрю несколько практик, которые помогут поддерживать порядок в проекте, упростить поддержку базы данных и избежать распространённых ошибок при работе с Alembic и SQLAlchemy. Эти приёмы не раз спасали меня от проблем. Вот темы, которые мы затронем:

1. Соглашение об именовании (Naming Convention)
2. Сортировка миграций по дате
3. Комментарии таблиц, колонок и миграций
4. Работа с данными в миграциях без моделей
5. Тестирование миграций (Stairway Test)
6. Отдельный сервис для проведения миграций
7. Использование миксинов для моделей

1. Соглашение об именовании (Naming Convention)

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

У меня нет рецепта как добавить конвенцию в существующий проект, кроме как перегенерировать миграции. Для нового проекта достаточно добавить соглашение у базового класса, чтобы Alembic автоматически прописывал имена в нужном формате. Пример такого формата ниже, который хорошо подходит большинству случаев:

from sqlalchemy import MetaData
from sqlalchemy.orm import DeclarativeBase

convention = {
    'all_column_names': lambda constraint, table: '_'.join(
        [column.name for column in constraint.columns.values()]
    ),
    'ix': 'ix__%(table_name)s__%(all_column_names)s',
    'uq': 'uq__%(table_name)s__%(all_column_names)s',
    'ck': 'ck__%(table_name)s__%(constraint_name)s',
    'fk': 'fk__%(table_name)s__%(all_column_names)s__%(referred_table_name)s',
    'pk': 'pk__%(table_name)s',
}

class BaseModel(DeclarativeBase):
    metadata = MetaData(naming_convention=convention)

2. Сортировка миграций по дате

По умолчанию название файла миграции в alembic начинается с тега миграции. При таком именовании, миграции в директории располагаются в случайном порядке. В некоторых случаях такой порядок неудобен. Удобнее хранить их отсортированными в хронологическом порядке.

Alembic позволяет изменять шаблон названия файла миграции. Настройка располагается в alembic.ini поле file_template. Для сортировки миграций в директории можно воспользоваться двумя удобными вариантами именования миграций.

1. На основе даты: file_template = %%(year)d-%%(month).2d-%%(day).2d_%%(rev)s_%%(slug)s
2. На основе времени (эпоха Unix): file_template = %%(epoch)d_%%(rev)s_%%(slug)s

Использование дат или Unix времени в именах файлов помогает держать миграции в упорядоченном виде и легко ориентироваться в них. Я предпочитаю использовать эпохи, далее в пункте 3 будет пример имен файлов.

3. Комментарии для таблиц и миграций

Следующий совет для тех, кто работает в команде. В целом хорошая практика комментировать атрибуты классов. Когда работаем с моделями SQLAlchemy, вместо комментариев в docstring, лучше воспользоваться комментариями колонок и таблиц. В этом случае комментарии будут в коде и в СУБД. Комментарии в СУБД могут помочь другим пользователям БД (ДБА или аналитикам) понимать назначение полей и таблиц.

class Event(BaseModel):
    __table_args__ = ({'comment': 'System (service) event'},)

    id: Mapped[uuid.UUID] = mapped_column(
        UUID(as_uuid=True),
        primary_key=True,
        comment='Event ID - PK',
    )
    service_id: Mapped[int] = mapped_column(
        sa.Integer,
        sa.ForeignKey(
            f'{IntegrationServiceModel.__tablename__}.id',
            ondelete='CASCADE',
        ),
        nullable=False,
        comment='FK to integration service that owns the event',
    )
    name: Mapped[str] = mapped_column(
        sa.String(256), nullable=False, comment='Event name'
    )

Также полезно комментировать миграции, чтобы легче было их находить в файловой системе. Комментарий добавляется при помощи -m <comment> при генерации миграции. Комментарий будет в докстринге и в названии файла. Согласитесь, при таком именовании найти нужную миграцию намного легче.

1728372261_c0a05e0cd317_add_integration_service.py 
1728372272_a1b4c9df789d_add_user.py
1728372283_f32d57aa1234_update_order_status.py  
1728372294_9c8e7ab45e11_create_payment.py
1728372305_bef657cd9342_remove_old_column_from_users.py

4. Не используйте модели в миграциях

Модели часто используют для манипуляций с данными, таких как перенос данных из одной таблицы в другую или изменение значений в колонках. Однако использование ORM-моделей в миграциях может привести к проблемам, если модель изменится после создания миграции. В таких случаях миграция, основанная на старой модели, сломается при её выполнении, так как схема БД может больше не соответствовать актуальной модели.

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

Используйте сырой SQL для манипуляций с данными:

def upgrade():
    op.execute(
        "UPDATE user_account SET email = CONCAT(username, '@example.com') WHERE email IS NULL;"
    )

def downgrade():
    op.execute(
        "UPDATE user_account SET email = NULL WHERE email LIKE '%@example.com';"
    )

Определяйте таблицы непосредственно в миграции: Если вы хотите использовать SQLAlchemy для манипуляций с данными, можно определить таблицы вручную прямо в миграции. Это обеспечит статичность схемы на момент выполнения миграции и не будет зависеть от изменений в моделях.

from sqlalchemy import table, column, String

def upgrade():
    # Определяем таблицу user_account для работы с данными
    user_account = table(
        'user_account',
        column('id'),
        column('username', String),
        column('email', String)
    )

    # Получаем соединение с базой данных
    conn = op.get_bind()

    # Выбираем всех пользователей без email
    users = conn.execute(
        user_account.select().where(user_account.c.email == None)
    )

    # Обновляем email для каждого пользователя
    for user in users:
        conn.execute(
            user_account.update().where(user_account.c.id == user.id).values(email=f"{user.username}@example.com")
        )

def downgrade():
    user_account = table(
        'user_account',
        column('id'),
        column('email', String)
    )

    conn = op.get_bind()
    # Удаляем email для пользователей, добавленных в upgrade
    conn.execute(
        user_account.update().where(user_account.c.email.like('%@example.com')).values(email=None)
    )

5. Тестирование миграций лесенкой (Stairway Test)

Stairway test — это методика, при которой проверяются постепенное применение миграций лесенкой upgrade/downgrade. Это проверит миграции на то, что миграции могут создать новую БД с нуля и то, что любую миграцию можно откатить без проблем, т.е. проверяется работоспособность downgrade. Если работаете в команде, добавьте этот тест в CI, спасёт нервы и время.

Тест внедряется довольно легко и быстро. Оставляю ссылку на репозиторий, где можно найти пример кода. Также там есть другие полезные тесты миграций.

6. Сервис миграций

Отдельный сервис для совершения миграций. Это просто один из способов производить миграции. При разработке локально или в окружениях приближенных к разработке этот метод вписывается хорошо. Напоминаю про условный depends_on, который здесь к месту. Берём образ приложения с alembic и запускаем в отдельном контейнере. Добавляем зависимость от БД с условием, что миграции начинаются, только когда БД способен обрабатывать запросы (service_healthy). Также можно добавить условный depends_on (service_completed_successfully) на приложение, чтобы оно запускалось после успешного завершения миграций.

  db:
    image: postgres:15
    ...
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      start_period: 10s

  app_migrations:
    image: <app-image>
    command: [
      "python",
      "-m",
      "alembic",
      "-c",
      "<path>/alembic.ini",
      "upgrade",
      "head"
    ]
    depends_on:
      db:
        condition: service_healthy

  app:
    ...
    depends_on:
      app_migrations:
        condition: service_completed_successfully

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

7. Миксины для моделей

Да, это очевидный пункт, но всё же напомню, чтобы никто не забыл. Использование миксинов — удобный способ избежать дублирования кода. Миксины — это классы с часто используемыми полями и методами, которые можно подключить к любым моделям, где они нужны. Например, часто нам нужны поля created_at и updated_at для отслеживания времени создания и обновления записей. Также бывает полезно использовать id на основе UUID, чтобы унифицировать первичные ключи. Всё это можно вынести в миксины.

import uuid
from sqlalchemy import Column, DateTime, func
from sqlalchemy.dialects.postgresql import UUID

class TimestampMixin:
    created_at = Column(
        DateTime,
        server_default=func.now(),
        nullable=False,
        comment="Время создания записи"
    )
    updated_at = Column(
        DateTime,
        onupdate=func.now(),
        nullable=True,
        comment="Время последнего обновления записи"
    )

class UUIDPrimaryKeyMixin:
    id = Column(
        UUID(as_uuid=True),
        primary_key=True,
        default=uuid.uuid4,
        comment="Уникальный идентификатор записи"
    )

Теперь, когда у нас есть миксины, можем подключить их к любой модели, где требуется и UUID id, и метки времени:

class User(UUIDPrimaryKeyMixin, TimestampMixin, BaseModel):
    __tablename__ = 'user'
    # Другие столбцы...

Заключение

Работа с миграциями может стать настоящей головной болью, но, если соблюдать несколько простых правил, поддерживать порядок в проекте гораздо легче. Соглашения об именовании, сортировка по дате, комментарии и тестирование миграций не раз спасали нас от хаоса и помогали не совершать ошибки. Надеюсь, эта статья оказалась полезной — поделитесь своими практиками работы с миграциями в комментариях!

При разработке приложений с помощью Docker Compose часто возникает ситуация, когда один сервис должен дождаться готовности другого перед началом своей работы. Например, веб-приложению может понадобиться дождаться запуска базы данных или другого зависимого сервиса. В этой статье мы рассмотрим два популярных способа решения этой задачи:

1. Скрипт wait-for-it.sh
2. Использование depends_on и healthchecks в Docker Compose

Для демонстрации мы создадим простое приложение на Python, но для понимания статьи знание Python не требуется — вы сможете просто скопировать код.

Настройка рабочего окружения

Для начала создадим рабочую директорию:

mkdir waitforit
cd waitforit

Теперь создадим тестовое веб-приложение на базе aiohttp, которое будет включать эндпоинт /healthz для проверки состояния. Также добавим возможность задержки перед запуском через переменную окружения SLEEP_BEFORE_START. Эта переменная позволит имитировать задержку старта сервиса. Чтобы сымитировать задержку старта сервиса, будем передавать в эту переменную количество секунд на которое надо задержаться перед запуском приложения.

Файл: app.py

import os
import time
from aiohttp import web

async def healthz(request):
    return web.Response(text="OK")

if __name__ == "__main__":
    sleep_time = int(os.getenv("SLEEP_BEFORE_START", 0))
    print(f"Sleep {sleep_time} sec before start...")
    time.sleep(sleep_time)

    app = web.Application()
    app.add_routes([web.get("/healthz", healthz)])
    print("Starting...")
    web.run_app(app, host="0.0.0.0", port=8080)

Теперь создадим Dockerfile для нашего приложения.

Файл: Dockerfile

FROM python:3.9-slim

WORKDIR /app
RUN pip install aiohttp \
    && apt-get update \
    && apt-get install -y curl
COPY app.py .
CMD ["python", "-u", "app.py"]

Теперь создадим docker-compose.yml, который будет запускать два сервиса:

1. web — наше веб-приложение с задержкой старта.
2. dependent — сервис, который должен ждать, пока web станет доступным.

Файл: docker-compose.yml

version: "3.8"

services:
  web:
    image: sleep-web-app
    build: .
    environment:
      SLEEP_BEFORE_START: 10

  dependent:
    image: sleep-web-app
    depends_on:
      - web

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

docker compose up --build

Результат покажет, что сервис dependent начнёт запуск до того, как сервис web будет готов:

web-1        | Sleep 10 sec before start...
dependent-1  | Sleep 0 sec before start...
dependent-1  | Starting...
web-1        | Starting...

Наша задача — настроить Docker Compose так, чтобы сервис dependent начинал работу только после того, как сервис web будет полностью готов. В результате хотим получить такой лог:

web-1        | Sleep 10 sec before start...
web-1        | Starting...
dependent-1  | Sleep 0 sec before start...
dependent-1  | Starting...

Использование wait-for-it.sh

wait-for-it.sh — это простой Bash-скрипт, который блокирует выполнение сервиса до тех пор, пока другой сервис не станет доступен, проверяя доступность конкретного порта. Это удобно для проверки готовности баз данных, веб-сервисов или других TCP-сервисов.

Скрипт надо запустить до основной команды запуска приложения. Это можно сделать в entrypoint или непосредственно подставить перед командой запуска. В нашем примере воспользуемся вторым способом для простоты.

В качестве аргументов достаточно передать host:port, доступность которого ожидаем. Тогда скрипт подождёт 15 секунд (значение по умолчанию). Чтобы задать своё время ожидания, можно добавить аргумент --timeout <sec>. Если за это время порт станет доступным, то скрипт остановится и сервис продолжит запуск, но если host:port окажется недоступным по истечении таймаута сервис всё равно начнёт запуск. Чтобы этого избежать и остановить запуск с ошибочным статусом, необходимо передать флаг --strict.

Давайте скачаем скрипт с GitHub и попробуем им воспользоваться:

curl -o wait-for-it.sh https://raw.githubusercontent.com/vishnubob/wait-for-it/master/wait-for-it.sh
chmod +x wait-for-it.sh

Добавим к сервису dependent волюм, через который прокинем скрипт. И добавим команду запуска приложения с использованием wait-for-it.sh. Скрипт будет ожидать готовность web сервиса на порту 8080. Основная команда запуска сервиса выполняется после --. Вы можете поиграть с параметрами и различными сценариями запуска. Мы рассмотрим пример, когда мы примерно понимаем сколько надо ждать web сервис (10 секунд) и оставим таймаут по умолчанию (15 секунд).

  dependent:
    image: sleep-web-app
    command:
      - ./wait-for-it.sh
      - web:8080
      - --
      - python
      - -u
      - app.py
    volumes:
      - ./wait-for-it.sh:/app/wait-for-it.sh

Теперь запустим наши сервисы:

docker-compose up

Из лога видно, что сервис dependent начинает работу с запуска wait-for-it.sh и ожидания web:8080. После того как web сервис запускается, dependent останавливает wait-for-it.sh, пишет сколько он прождал и выполняет команду, указанную после -- слешей. Мы добились необходимого поведения: зависимый сервис запускается после того, как другой сервис готов принимает соединения на своём порту.

dependent-1  | wait-for-it.sh: waiting 15 seconds for web:8080
web-1        | Sleep 10 sec before start...
web-1        | Starting...
dependent-1  | wait-for-it.sh: web:8080 is available after 11 seconds
dependent-1  | Sleep 0 sec before start...
dependent-1  | Starting...

Преимущества wait-for-it.sh:

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

Недостатки:

• wait-for-it.sh проверяет только доступность порта, но не проверяет полную готовность сервиса (например, не проверяет завершение инициализации схемы базы данных). Часто бывает, что порт уже открыт, а сервис не готов обрабатывать входящие запросы. Эту проблему поможет решить следующий способ.

Использование depends_on и healthcheck

Еще один способ заставить один сервис ожидать готовности другого — это использование условной опции depends_on и механизма healthcheck в Docker Compose.

В этом подходе сервис должен иметь healthcheck, который проверяет готовность сервиса обрабатывать запросы, а зависимый сервис иметь depends_on с условием на healthcheck первого. Простыми словами, зависимый сервис запускается, когда первый сервис здоров (готов обрабатывать запросы).

Добавим healthcheck для сервиса web, чтобы проверять его готовность через эндпоинт /healthz. Тем самым, мы будем знать, что у сервиса не просто открыт порт, но и то, что сервис готов обрабатывать запросы. Подробнее про healthcheck можно прочитать здесь. В test задаётся команда, которая проверяет здоровье сервиса. Команда могла бы проверять просто открытость порта, тогда это был бы эквивалент wait-for-it.sh. Но суть healthcheck не просто проверить порт, а готовность сервиса обработать запросы.

  web:
    image: sleep-web-app
    build: .
    environment:
      SLEEP_BEFORE_START: 10
    healthcheck:
      test: ["CMD", "curl", "http://web:8080/healthz"]
      interval: 10s # Как часто будет проверяться статус
      retries: 5 # Сколько раз проверить, прежде чем считать недоступным
      start_period: 10s # Через сколько после запуска начинать проверки
      timeout: 10s # Таймаут на каждый запуск test

К зависимому сервису добавим depends_on с условием. Сервис dependent зависит от web, но будет запускаться только после того, как сервис web успешно пройдет проверку состояния. Больше про условный depends_on можно прочитать здесь. Надо упомянуть, что не все версии композа поддерживают условный depends_on.

Финальный композ:

version: "3.8"

services:
  web:
    image: sleep-web-app
    build: .
    environment:
      SLEEP_BEFORE_START: 10
    healthcheck:
      test: ["CMD", "curl", "http://web:8080/healthz"]
      interval: 10s
      retries: 5
      start_period: 10s
      timeout: 10s

  dependent:
    image: sleep-web-app
    depends_on:
      web:
        condition: service_healthy

Теперь снова запускаем наши сервисы:

docker-compose up

На этот раз сервис dependent начнет выполнение только после того, как проверка состояния сервиса web через /healthz пройдет успешно.

web-1        | Sleep 10 sec before start...
web-1        | Starting...
dependent-1  | Sleep 0 sec before start...
dependent-1  | Starting...

Популярные сервисы имеют готовые решения для healthcheck:

postgresql: ["CMD", "pg_isready", "-U", "postgres"]
kafka: ["CMD-SHELL", "kafka-broker-api-versions.sh --bootstrap-server localhost:9092"]
redis: ["CMD", "redis-cli", "ping"]
mysql: ["CMD", "mysqladmin", "ping", "-h", "localhost"]
mongodb: ["CMD", "mongo", "--eval", "db.adminCommand('ping')"]
elasticsearch: ["CMD-SHELL", "curl -f http://localhost:9200/_cluster/health || exit 1"]

Преимущества depends_on + healthcheck:

• Проверки состояния дают более полное представление о готовности сервиса по сравнению с простой проверкой порта.
• Это встроенное решение Docker Compose, что упрощает его использование без дополнительных скриптов.
• Легче настраивать цепочки зависимостей.

Недостатки:

• Более объемная конфигурация, которая может быть менее гибкой для сервисов, не основанных на TCP.
• Не все образы поддерживают проверки состояния по умолчанию, возможно, потребуется писать свои скрипты.
• Сложность с проверкой готовности внешних сервисов, вне композа.

Какой метод выбрать?

Выбор между wait-for-it.sh и depends_on с healthcheck зависит от вашего конкретного случая:

• Используйте wait-for-it.sh, если вам нужно быстрое и простое решение для ожидания доступности порта, особенно в тех средах, где вы имеете больший контроль над зависимостями.
• Используйте depends_on + healthcheck, если вам нужно более надежное, встроенное решение Docker Compose, которое гарантирует полную готовность сервиса, а не только его доступность.

Заключение

Управление готовностью сервисов в Docker Compose — важный аспект создания надежных многосервисных приложений. Независимо от того, выберете ли вы простоту wait-for-it.sh или встроенные возможности depends_on с проверками состояния, оба метода помогают обеспечить, что ваши сервисы ожидают полной готовности зависимостей перед запуском. Правильный выбор стратегии позволит избежать потенциальных проблем и сделать запуск сервисов более плавным в ваших Docker-приложениях.

Рассмотрим один из удачных примеров постраничной пагинации в Django, используя класс Paginator. Такая пагинация удобна для пользователя и обычно подходит для большинства случаев.

Этот вид пагинации позволяет:

• перемещаться на следующую и предыдущую страницы с помощью кнопок Prev и Next;
• перемещаться на первую и последнюю страницы с любой страницы;
• перемещаться через одну страницу.

Пагинация в Django

Вы можете ознакомиться с подробной информацией о пагинации в Django по следующим ссылкам:

• Documentation: Pagination
• Pagination for a User-Friendly Django App

Кратко напомню, что пагинация в Django осуществляется с помощью классов Paginator и Page. Paginator разбивает большой набор данных на страницы и принимает в качестве параметров набор объектов (list, tuple или QuerySet) и размер страницы. Page представляет текущую страницу в пагинации и содержит объекты страницы и информацию о соседних страницах.

Пагинатор можно создавать вручную или автоматически с использованием Class-Based Views. В шаблон передается объект страницы (page_obj), который содержит объекты, информацию о страницах и сам пагинатор.

Используемые атрибуты страницы в рассматриваемой пагинации:

• page_obj.has_previous: проверяет, есть ли предыдущая страница.
• page_obj.has_next: проверяет, есть ли следующая страница.
• page_obj.previous_page_number: возвращает номер предыдущей страницы.
• page_obj.next_page_number: возвращает номер следующей страницы.
• page_obj.number: возвращает номер текущей страницы.
• page_obj.paginator: возвращает экземпляр класса Paginator.
• page_obj.paginator.num_pages: возвращает общее количество страниц.
• page_obj.paginator.page_range: возвращает диапазон страниц.

Также в рассматриваемой пагинации используется фильтр шаблонов add, который позволяет прибавлять значения к переменным прямо в шаблоне.

User-Fiendly пагианция

На скриншоте показано как будет выглядеть пагинатор на различных страницах. Пагинатор всегда отображает крайние страницы и две соседние страницы, если они существуют. Также отображаются кнопки Prev и Next, если текущая страница не является крайней.

В следующем листинге представлена реализация этой пагинации. Просто вставьте этот код в свой проект, и скорее всего, все должно работать. Далее мы рассмотрим этот листинг подробнее.

{% if page_obj.has_previous %}
  <li><a href="?page={{ page_obj.previous_page_number }}">(Prev)</a></li>

  {% if page_obj.number > 3 %}
      <li><a href="?page=1">(1)</a></li>
    {% if page_obj.number > 4 %}
      <li><a >...</a></li>
    {% endif %}
  {% endif %}
{% endif %}

{% for num in page_obj.paginator.page_range %}
  {% if page_obj.number == num %}
      <li><a href="?page={{ num }}">({{ num }})</a></li>
  {% elif num > page_obj.number|add:'-3' and num < page_obj.number|add:'3' %}
      <li><a href="?page={{ num }}">({{ num }})</a></li>
  {% endif %}
{% endfor %}

{% if page_obj.has_next %}
  {% if page_obj.number < page_obj.paginator.num_pages|add:'-3' %}
    <li><a >...</a></li>
    <li><a href="?page={{ page_obj.paginator.num_pages }}">
      ({{ page_obj.paginator.num_pages }})
    </a></li>
  {% elif page_obj.number < page_obj.paginator.num_pages|add:'-2' %}
    <li><a href="?page={{ page_obj.paginator.num_pages }}">
      ({{ page_obj.paginator.num_pages }})
    </a></li>
  {% endif %}

  <li><a href="?page={{ page_obj.next_page_number }}">(Next)</a></li>
{% endif %}

Этот фрагмент кода является шаблоном Django для создания элемента управления пагинацией. Давайте разберем, что делает каждая часть этого кода:

1. Ссылка на Предыдущую Страницу:

{% if page_obj.has_previous %}
  <li><a href="?page={{ page_obj.previous_page_number }}">(Prev)</a></li>

Если page_obj.has_previous равно True, он показывает кнопку Prev на предыдущую страницу. Переменная page_obj.previous_page_number содержит номер предыдущей страницы.

2. Ссылки на Первые Страницы и Многоточие:

{% if page_obj.number > 3 %}
    <li><a href="?page=1">(1)</a></li>
  {% if page_obj.number > 4 %}
    <li><a >...</a></li>
  {% endif %}
{% endif %}

Эти строки кода обрабатывают отображение ссылки на первую страницу и многоточие (...), если текущий номер страницы больше 3 (или 4 для многоточия).

3. Текущая Страница и Ссылки на Соседние Страницы:

{% for num in page_obj.paginator.page_range %}
  {% if page_obj.number == num %}
      <li><a href="?page={{ num }}">({{ num }})</a></li>
  {% elif num > page_obj.number|add:'-3' and num < page_obj.number|add:'3' %}
      <li><a href="?page={{ num }}">({{ num }})</a></li>
  {% endif %}
{% endfor %}

Этот цикл проходит через диапазон страниц в пагинаторе. Он проверяет два условия:

• Если номер страницы (num) является текущей страницей (page_obj.number), он создает для нее ссылку. Обычно это оформляется по-разному, чтобы указать на текущую страницу.
• Если номер страницы находится в пределах трех страниц до или после текущей страницы, он также создает ссылки на эти страницы. Таким образом, пользователь может переходить к ближайшим двум страницам, не просматривая весь диапазон.

4. Многоточие и Ссылка на Последнюю Страницу:

{% if page_obj.has_next %}
{% if page_obj.number < page_obj.paginator.num_pages|add:'-3' %}
<li><a >...</a></li>
<li><a href="?page={{ page_obj.paginator.num_pages }}">
  ({{ page_obj.paginator.num_pages }})
</a></li>
{% elif page_obj.number < page_obj.paginator.num_pages|add:'-2' %}
<li><a href="?page={{ page_obj.paginator.num_pages }}">
  ({{ page_obj.paginator.num_pages }})
</a></li>
{% endif %}

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

5. Ссылка на Следующую Страницу:

{% if page_obj.has_next %}
...  
<li><a href="?page={{ page_obj.next_page_number }}">(Next)</a></li>
{% endif %}

Аналогично первой части, только кнопка для перехода на следующую страницу.

Заключение

Мы рассмотрели пример простой и интуитивно понятной постраничной пагинации в Django, которая позволяет пользователям легко перемещаться по страницам и получать нужную информацию.

Реализация пагинации может быть адаптирована под ваши потребности, и вы можете внести изменения в код, чтобы соответствовать требованиям вашего проекта. Удачи в использовании пагинации в ваших Django приложениях!

Все знают, что в Python типы данных делятся на изменяемые и неизменяемые, а как устроена сама типизация в Python? Чтобы ответить на этот вопрос, надо рассмотреть какими характеристиками обладает система типов Python.

Обычно, когда описывают систему типов языка программирования, отвечают на 3 вопроса:

1. Выполняет ли язык неявные автоматические преобразования типов?
2. На каком этапе выясняется тип переменной?
3. Надо ли явно указывать тип переменных?

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

Python имеет сильную динамическую неявную типизацию и давайте подробнее рассмотрим почему.

1. Сильная типизация

Когда мы говорим о "сильной типизации" в контексте программирования, мы имеем в виду строгий подход языка к обработке переменных разных типов. В языке программирования Python, который отличается сильной типизацией, разные типы данных не смешиваются автоматически. Так, выражение "some string" - 3 вызовет ошибку, потому что язык не позволяет неявно преобразовывать строку в число для выполнения математической операции. При ошибках связанных с типами Python генерирует исключение TypeError.

Аналогично, попытка сложить список [2, 1, 0] и множество set([2, 23, 2]) также приведет к ошибке, поскольку Python не будет искать способы автоматически преобразовать одну структуру данных в другую для выполнения операции. В противопоставление можно привести в пример язык JavaScript, который позволяет без проблем складывать строки с числами: 3 + '1' // Получится строка: '31'.

Несмотря на сильную типизацию, Python допускает некоторые операции между различными типами данных, но это объясняется явной реализацией, а не автоматическим преобразованием:

# Повторение последовательностей:
# вы можете "умножить" строку или список на число,
# и это даст повторяющуюся последовательность.

print("word" * 3)  # wordwordword
print([1, 2] * 3)  # [1, 2, 1, 2, 1, 2]

# float и int
print(5 + 0.1)  # 5.1

# bool и число
print(2.2 + True)  # 3.2

# Замечание: тип bool наследуется от int,
# и здесь операция сложения не вызывает сомнений.

# и другие...

Эти операции возможны благодаря внутренним механизмам языка, предоставляющим четкую реализацию для таких случаев. Например, вы в своей программе можете явно задать поведение вашего типа (класса) при сложении с другим объектом, используя магические методы. Но если вы этого не сделаете, то получите ошибку при попытке сложить с чем-то.

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

class JavaScriptStr(str):
    def __add__(self, value):  # Явная реализация сложения
        return super().__add__(str(value))


number = JavaScriptStr("3")
print(number + 1)  # "31"

2. Динамическая типизация

Динамическая типизация Python означает, что типы данных переменных определяются во время выполнения программы, а не на этапе компиляции, как в языках со статической типизацией. Это облегчает написание гибкого кода и позволяет, например, создавать функции, которые работают с различными типами данных.

Рассмотрим функцию find, которая ищет элемент required_element в последовательности sequence. В языке C для реализации этой же логики пришлось бы написать несколько версий функции для разных типов данных, тогда как в Python достаточно одной:

def find(required_element, sequence):
    """Осуществляет поиск элемента в последовательности."""
    for index, element in enumerate(sequence):
        if element == required_element:
            return index
    return -1

    
print(find(2, [1, 2, 3]))  # Выведет: 1
print(find("c", ("a", "b", "c", "d")))  # Выведет: 2

print(find(1, 1))  # Возникнет исключение TypeError

Негативная сторона динамической типизации в том, что она может порождать неожиданные ошибки во время выполнения программы. Например, если мы в sequence передадим не итерируемый объект (по которому нельзя пройтись с помощью for), то получим ошибку. Но узнаем о ней, только когда выполнение программы дойдёт до конкретной строчки с for обходом по этому объекту.

Также динамическая типизация позволяет перезаписывать в одну переменную данные разных типов.

number = 1  # int
number = "One"  # str

3. Неявная типизация

В языках с неявной типизацией не требуется явно указывать тип переменной — интерпретатор сам определяет тип на основе присвоенного значения. Это упрощает код и делает его более читаемым:

var = 5  # int
var = "some string"  # теперь var - это str

Аннотация Типов в Python

Начиная с версии 3.5, в Python появилась поддержка аннотации типов, что позволяет программистам явно указывать типы переменных и возвращаемых функцией значений. Это не влияет на работу интерпретатора, но помогает в программировании и поддержке кода:

def plus(x: int, y: int) -> int:
    return x + y


print(plus(5, 10))  # Выведет: 15

# Функция выполнит конкатенацию строк.
# Это показывает, что аннотация не равно явная типизация.
print(plus("Hello ", "world!"))  # Выведет: Hello world!

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

Заключение

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

Docker — это невероятно мощный инструмент, но иногда его настройка на Ubuntu иногда может быть сложной задачей. В этом посте мы рассмотрим шаги установки Docker (и Docker Compose) на Ubuntu с использованием одного скрипта.

Прежде чем мы начнем процесс установки, убедитесь, что вы используете Ubuntu. Шаги, предоставленные в этом руководстве, написаны для Ubuntu, но могут быть применимы к другим дистрибутивам с некоторыми изменениями.

TL;DR:

wget https://gist.githubusercontent.com/welel/f80c96482e3b539487b9fa08bfcab86d/raw/90bc2330924d225aef7dc3178f5926bda7daff04/install_docker.sh

sudo chmod +x install_docker.sh

sudo ./install_docker.sh

Вот как установить Docker с помощью скрипта в Ubuntu:

Шаг 1: Загрузите установочный скрипт

Сначала вам нужно загрузить скрипт, который автоматизирует процесс установки. Откройте терминал и введите следующую команду:

wget https://gist.githubusercontent.com/welel/f80c96482e3b539487b9fa08bfcab86d/raw/90bc2330924d225aef7dc3178f5926bda7daff04/install_docker.sh

Эта команда загружает необходимый скрипт из Gist и сохраняет его в текущей директории.

Скрипт доступен на Gist. Gist включает в себя сам скрипт и подробное объяснение его использования. Вы можете просмотреть и скачать скрипт, а также найти инструкции о том, как им пользоваться, по следующей ссылке:

Установить Docker на Ubuntu - Скрипт установки и руководство

Этот скрипт делает процесс установки понятным и простым, позволяя вам быстро запустить Docker на вашей системе Ubuntu с минимальными усилиями.

Шаг 2: Предоставьте скрипту разрешения на выполнение

Прежде чем запустить скрипт, вам нужно дать ему разрешение на выполнение. Измените разрешения с помощью команды chmod:

sudo chmod +x install_docker.sh

Шаг 3: Выполните скрипт

Теперь пришло время запустить скрипт. Вы сделаете это с повышенными привилегиями, используя sudo:

sudo ./install_docker.sh

После выполнения скрипта следите за выводом в терминале. Если все пройдет как запланировано, вы должны увидеть сообщение Docker successfully installed. Это подтверждение означает, что Docker был успешно установлен на вашей системе, и вы готовы использовать его для ваших нужд в контейнеризации.

После установки

Чтобы убедиться, что все работает корректно, вы можете выполнить:

docker --version

docker compose version

Эта команда должна вывести версию Docker, которую вы только что установили, и версию Docker Compose.

Кроме того, хорошей практикой будет добавить вашего пользователя в группу docker, чтобы вы могли выполнять команды Docker без использования sudo:

sudo usermod -aG docker ${USER}

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

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

Дешевый виртуальный сервер с небольшими ресурсами хорошо подходит для ряда целей, особенно если вы не ожидаете большой нагрузки или если требования к вычислительным мощностям и хранению данных невелики. Вот несколько примеров задач, для которых может подойти такой сервер: хостинг веб-сайтов, легкие веб-приложения, размещение ботов и так далее.

За 130 рублей получится арендовать машину со следующей конфигурацией: 1 ядро x 2.2 ГГц, 500 Мб RAM, 10 Гб HDD, операционная система на выбор. Такой конфигурации вполне хватит для поднятия учебных веб-приложений, ботов и даже реальных проектов с небольшим количеством пользователей.

1. Регистрация

Перейдите на сайт RU VDS и выполните регистрацию.

2. Переход на форму создания сервера

Нажмите на выпадающее меню Выбрать VPS, затем на VPS Старт. Выберите желаемую конфигурацию. Я выберу самую дешевую за 130 рублей. Нажмите Заказать.

3. Конфигурация ресурсов сервера

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

Далее есть возможность поменять ресурсы сервера, при этом изменится цена.

Данный пункт позволяет выбрать шаблон для сервера. Шаблон — сервер с предустановленным софтом (например, можно выбрать шаблон для Django проекта). Я предпочитаю работать с контейнеризацией при разворачивании проектов, потому выбираю чистую ОС. Также можно выбрать желаемую операционную систему (можно потом поменять) и срок аренды.

4. Оплата

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

5. Вход на сервер

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

Теперь использую любой SSH клиент можно войти на сервер, используя данные для входа: IP, имя пользователя, пароль. Воспользуемся ssh клиентом системы Ubuntu.

# ssh <user>@<IP>

$ ssh root@62.76.228.108

# Вводим пароль

# Соглашаемся с предупреждением

# Выводим информацию о сервере

$ lsb_release -a

Поздравляю, вы успешно арендовали сервер, на котором теперь можно запустить целый ряд интересных и полезных проектов! Неважно, начинаете ли вы свой путь в мире веб-разработки или уже имеете опыт и просто ищете подходящее место для экспериментов — этот сервер открывает перед вами множество возможностей.

Далее логичным шагом будет установить Docker и Docker Compose, инструкция: Быстрая Установка Docker и Compose на Ubuntu

Покупка компьютера без операционной системы обходится дешевле. При заказе своего ноутбука, мне предложили купить Windows 11 за 15.000 рублей, что мне показалось забавным. Когда я пришёл забирать ноутбук в магазин, краем уха я услышал, как покупателю предлагают дополнительно к компьютеру купить Windows за похожую цену, и поколебавшись, он согласился. Наверное, это и подвигло меня написать немного об этом. В этом посте мы рассмотрим, как можно приобрести Windows 11 всего за 500/1000 рублей.

Несколько слов “почему Windows” (можете пропустить это). Мне, как и многим разработчикам, удобнее работать непосредственно в Linux. Но не все ноутбуки подходят для работы с этой операционной системой. Иногда при установке Linux у ноутбука могут перестать работать некоторые функции или могут появиться проблемы с драйверами. Есть список сертифицированных ноутбуков под Ubuntu, у которых при работе с Linux должно быть минимум проблем. Мой ноутбук не из этой серии, а производитель заявляет, что лучшая ОС для моего девайса — Windows 10/11. Ради хорошего ноутбука пришлось пойти на компромисс и установить Windows. Благо помимо виртуальной машины существуют такие инструменты как WSL (позволяет запускать Linux-приложения и среду на вашем компьютере под управлением Windows). Для разработчиков и тех, кто предпочитает Linux, WSL открывает новые возможности, делая работу с обеими операционными системами более гармоничной.

Шаг 1: Установка Windows 11

Первым шагом необходимо получить установочный образ Windows 11, создать загрузочную флешку и установить Windows на компьютер. Официальный сайт Microsoft предлагает скачать образ, однако не всегда это бывает доступно. При возникновении ошибки, такой как “We are unable to complete your request at this time. Some users, entities and locations are banned from using this service.”, VPN может помочь обойти ограничения. Если VPN не помогает, то скачайте образ с другого источника. Важно выбирать проверенный источник для загрузки образа, который позволяет скачать официальную версию образа, а не переделанные сборки.

Я скачивал образ Windows 11 Pro с этого сайта: https://softcomputers.org/download/download-windows-11/download-windows-11/. Есть английская и русская версии и чек-сумма для проверки. Вы можете поискать источники заслуживающие ваше доверие.

Шаг 2: Покупка ключа

Чтобы сэкономить значительную сумму, я обратился к ресурсам вроде Ozon, Авито, сайты в интернете, где можно найти лицензионные ключи Windows 11 по намного более доступным ценам, чем в официальных магазинах. Однако при таком выборе, всегда необходимо быть осторожным и проверять рейтинг продавца и отзывы покупателей, чтобы избежать мошенничества. Также, даже успешно активированный ключ не признак гарантии того, что в будущем с ним не возникнет проблем. В любом случае это будет дешевле, даже если придётся купить пару ключей.

Многие отзываются о данном сайте, как о надежном продавце: https://softmonstr.ru/product/windows-11-pro-%D0%BE%D0%B5%D0%BC/, но я нашёл хороший и дешевый вариант на Авито. Продавец имеет положительные отзывы, и очень оперативно проводит сделки. Ключ можно приобрести за 500 рублей — одноразовый (до переустановки ОС) и за 1000 — с привязкой к аккаунту Microsoft. Через 2 минуты после первого сообщения, я уже вводил свой электронный ключ, который подошёл и активировал Windows с привязкой.

Заключение:

Как видите, приобретение Windows 11 за более доступную цену возможно, но требует осторожности. Проверьте рейтинг продавца и используйте проверенные источники для загрузки операционной системы. Ключ, связанный с учетной записью Microsoft, обычно более гибкий и позволяет переустанавливать Windows при необходимости. Не забывайте о преимуществах Windows Subsystem for Linux (WSL), который делает Windows привлекательным выбором для разработчиков.

Наглядное видео как установить Windows: https://www.youtube.com/watch?v=oeMhkn6WAgQ&t=143s

В таких случаях может быть удобно иметь специально подготовленное виртуальное устройство Android (AVD), готовое посмотреть, какими HTTP(S) запросами обменивается устройство и сервер.

В этом руководстве объясняется, как настроить специально подготовленный AVD, который можно использовать для мониторинга сетевого трафика Android приложения, установленного в эмуляторе, даже если оно обменивается данными через защищенное соединение (HTTPS).

Установка mitmproxy

Для просмотра сетевого трафика мы будем использовать mitmproxy (в этом руководстве будет использоваться веб-интерфейс mitmweb, который позволяет просматривать трафик в интерфейсе браузера). MITMproxy позволяет просматривать сетевой трафик, добавляя себя в качестве прокси-сервера между приложением и сервером (API).

В зависимости от вашей ОС вы должны следовать этому руководству по установке: https://docs.mitmproxy.org/stable/overview-installation/

Для установки на Linux, необходимо скачать архив, затем распаковать его в удобную папку.

Установка Android Studio

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

В зависимости от вашей ОС вы должны следовать этому руководству по установке: https://developer.android.com/studio/install

После установки, необходимо добавить в переменную окружения PATH пути к эмулятору и используемым далее инструментам. На Linux можно в конец файла ~/.bashrc добавить строчки:

export PATH=$PATH:$HOME/Android/Sdk/platform-tools
export PATH=$PATH:$HOME/Android/Sdk/emulator

После установки и настройки, запускайте Android Studio, выполнив скрипт studio.sh в android-studio/bin/ директории.

Создание AVD

1. В окне Android Studio нажмите More Actions -> Virtual Device Manager.

2. В окне менеджера устройств нажмите Create Device.

3. Я выберу Pixel 3.

4. Выберите образ системы. По опыту, API уровня 28 и ABI x86 (Android 9.0) работают лучше всего. Более новые уровни API могут помешать вам загрузить пользовательские (CA) сертификаты.

5. После выбора образа жмите Finish.

У вас появилось новое устройство, но пока не запускайте его. Закройте Android Studio.

Подготовка AVD

1. Откройте свой терминал.

2. Предполагая, что вы добавили пути Android Studio инструментов в $PATH, если нет, вернитесь на шаг установки Android Studio.

3. Выведите список доступных виртуальных устройств командой и скопируйте название созданного нами устройства:

emulator -list-avds

4. По умолчанию (при запуске из AVD Manager) мы не сможем записывать никакие файлы в системные папки. Чтобы запустить эмулятор с доступными для записи системными папками, используйте эту команду:

emulator -avd Pixel_3_API_28 -writable-system

5. Подождите, когда загрузится устройство.

Настройка mitmproxy

1. Перейдите в папку с mitmproxy и запустите mitmweb. В домашней директории у вас появится папка .mitmproxy. Переходите в неё.

cd ~/.mitmproxy/

2. Сгенерируйте сертификат:

hashed_name=`openssl x509 -inform PEM -subject_hash_old -in mitmproxy-ca-cert.cer | head -1` && cp mitmproxy-ca-cert.cer $hashed_name.0

У вас в папке должен появиться файл с расширением .0, например такой c8750f0d.0. В дальнейших шагах подставляйте своё название файла из папки. Дополнительную информацию можно найти здесь: https://docs.mitmproxy.org/stable/howto-install-system-trusted-ca-android/

3. Выполните последовательность команд в терминале и подождите перезагрузку AVD:

adb root
adb remount
adb shell 'mount -o rw,remount /'
adb push c8750f0d.0 /system/etc/security/cacerts
adb shell 'chmod 664 /system/etc/security/cacerts/c8750f0d.0'
adb reboot

Настройка прокси на AVD

1. Нажмите на дополнительные настройки:

2. В открывшемся окне выберите Settings → Proxy → Manual proxy configuration. В Host name впишите 0.0.0.0, в Port number 8080. Нажмите Apply.

Перехват трафика браузера

1. Запустите mitmweb и перейдите в браузере по адресу http://localhost:8081/

2. Откройте на AVD браузер и перейдите по адресу mitm.it, в mitmweb у вас должна открыться вкладка Flow, в которой отображается информация о выполненных запросах AVD.

Установка Android приложения

Для примера перехватим трафик приложения Ozon, вы можете попробовать необходимое вам приложение.

1. Скачайте apk файл. Apk файл Ozon. И откройте терминал в директории с файлом.
2. Выполните команду установки:

adb install <название apk файла>

Перехват трафика приложения

1. Запустите mitmweb и перейдите в браузере по адресу http://localhost:8081/
2. Запустите приложение, которое хотите проинспектировать.

Как видим, mitmproxy перехватывает все API вызовы. За счёт CA сертификатов, мы можем наблюдать HTTPS трафик.

Источники

1. Inspecting (HTTPS) Network Traffic of any Android App
2. Install System CA Certificate on Android Emulator
3. How to Install Android Apps via ADB

Подробнее о том как работает mimtproxy:

Selectel: Анализ HTTP-трафика с mitmproxy

Требования. У вас должна быть Linux система с установленным Python 3.10+. Если вы в России, потребуется VPN. В качестве Telegram фреймворка используется aiogram 3. Для успешного прохождения туториала необходимы некоторые знания aiogram 3.

Транскрибация — это перевод аудио в текст. В нашем случае: перевод голосового сообщения (voice) в текст.

OpenAI API

OpenAI API — это программный интерфейс приложения, который предоставляет доступ к технологиям искусственного интеллекта, разработанным и поддерживаемым OpenAI. Для решения нашей задачи нам понадобится модель Whisper от OpenAI.

Прежде чем продолжать, вам следует убедиться, что у вас есть доступ к OpenAI API. В данной статье описан подробный алгоритм регистрации и получения токена для использования OpenAI API: https://teletype.in/@loginovpavel/get-openai-token. Как только у вас удастся получить доступ, продолжайте.

Whisper Model — модель, способная транскрибировать аудио файлы в текст.

Возможности модели:

• Транскрибирование аудио файла на любом языке.
• Транскрибирование аудио файла и перевод текста на английский.

Для использования модели необходимо отправить байтовое представление аудио файла размером не более 25 мегабайтов в одном из доступных форматов на endpoint API. Мы будем использовать Python библиотеку openai для выполнения запросов к API в программе.

Пример из документации траскрибирующий аудио файл в текст:

# Листинг [1]
# Транскрибация аудио файла в текст

# Примечание: вам необходимо использовать
# OpenAI Python v0.27.0 для работы с этим кодом

import openai

audio_file = open("/path/to/file/german.mp3", "rb")
transcript = openai.Audio.translate("whisper-1", audio_file)

Сперва открывается файл по пути "/path/to/file/german.mp3" в binary моде. Далее выполняется метод translate, который принимает название модели "whisper-1" и файл audio_file.

Формат ответа transcript:

# Листинг [2]
# Ответ от модели, содержимое transcript

{
  "text": "Текст аудио файла."
}

Создание проекта и установка зависимостей

Для начала необходимо установить программу ffmpeg для работы с медиа файлами в ОС Linux. Это программа необходима для работоспособности одной из зависимостей проекта, подробнее о ней далее.

$ sudo apt install ffmpeg

Создайте папку с проектом и настройте виртуальное окружение. В окружение установите фреймворк aiogram 3 (для работы с Telegram API), библиотеку openai (для работы с OpenAI API) не ниже 0.27 версии и библиотеку pydub (для работы с аудио файлами).

$ pip install --pre aiogram
$ pip install openai==0.27.0
$ pip install pydub

Для удобства будем работать в одном файле. Создайте новый файл bot.py и поместите туда следующий код. Поменяйте токен бота на свой.

# Листинг [3]
# Эхо бот на aiogram 3

import asyncio

from aiogram import Bot, Dispatcher, F, Router
from aiogram.types import Message

# Токен вашего телеграм бота
BOT_TOKEN = "5842123168:AAHyhAIFWeh4-8jYvo72eZeq18-9P2wQmaY"


router: Router = Router()

# Хендлер сообщений с которым будем работать
@router.message(F.content_type == "voice")
async def process_message(message: Message):
    """Принимает все голосовые сообщения и отвечает эхо."""
    await message.answer(text="echo")


async def main():
    bot: Bot = Bot(token=BOT_TOKEN)
    dp: Dispatcher = Dispatcher()
    dp.include_router(router)
    await dp.start_polling(bot)


if __name__ == "__main__":
    asyncio.run(main())

У вас должна была получиться примерно следующая структура проекта:

project/
├── env/ 	# Виртуальное окружение
└── bot.py  # Код с ботом

Запустите бота и проверьте работоспособность. На любое сообщение бот должен возвращать echo.

$ python bot.py

Если всё работает, двигаемся дальше.

Транскрибация аудио в текст

Продолжаем работать в файле bot.py, добавляя последующий код в него. Перед тем как начать работать с библиотекой openai, необходимо проинициализировать API токен. Импортируем библиотеку и инициализируем токен, который вы сгенерировали ранее.

# Листинг [4]
# Инициализация openai ключа

import openai

openai.api_key = "sk-BhC44H9LVVtSE74BlbkGGtPs0OTGDx21tjPVu7bzl"

Выше был пример из документации OpenAI с транскрибацией (листинг №1). В нём использовался метод transcribe, класса Audio из модуля openai для создания запроса к OpenAI API. Также в классе Audio имеется метод atranscribe для выполнения этого же запроса, но в асинхронном режиме. Метод принимает два аргумента - название модели ("whisper-1") и файл для транскрибации.

Создадим следующую функцию:

# Листинг [5]
# Функция для транскрибации аудио файла

async def audio_to_text(file_path: str) -> str:
    """Принимает путь к аудио файлу, возвращает текст файла."""
    with open(file_path, "rb") as audio_file:
        transcript = await openai.Audio.atranscribe(
            "whisper-1", audio_file
        )
    return transcript["text"]

Функция принимает путь к аудио файлу file_path. Открывает файл на чтение в binary моде audio_file. Выполняет запрос методом atranscribe класса Audio, передавая название модели и сам файл. В листинге №2 указан формат ответа от модели, поэтому для возвращения результирующего текста обращаемся к ключу "text" ответа transcript.

Далее напишем функцию для сохранения голосового сообщения с сервера Telegram. Для этого подготовим директорию voice_files.

У вас должна была получиться следующая структура проекта:

project/
├── env/ 	        # Виртуальное окружение
├── voice_files/    # Хранилище войсов в .mp3 формате
└── bot.py          # Код с ботом

Импортируем io, Voice, AudioSegment.

# Листинг [6]
# Необходимые импорты

import asyncio
import io

from aiogram import Bot, Dispatcher, F, Router
from aiogram.types import Message, Voice

import openai
from pydub import AudioSegment

Разберём функцию по шагам:

# Листинг [7]
# Функция сохраняющая голосовое сообщение в mp3

async def save_voice_as_mp3(bot: Bot, voice: Voice) -> str:
    """Скачивает голосовое сообщение и сохраняет в формате mp3."""
    voice_file_info = await bot.get_file(voice.file_id)
    voice_ogg = io.BytesIO()
    await bot.download_file(voice_file_info.file_path, voice_ogg)
    
    voice_mp3_path = f"voice_files/voice-{voice.file_unique_id}.mp3"
    AudioSegment.from_file(voice_ogg, format="ogg").export(
	    voice_mp3_path, format="mp3"
	)
    return voice_mp3_path

Функция принимает экземпляр бота bot для скачивания файлов и экземпляр голосового сообщения voice с необходимой информацией.

Голосовые сообщения скачиваются в формате .ogg, а модель Whisper с этим форматом не работает. Поэтому мы будем скачивать файл с сервера в переменную voice_ogg, затем конвертировать его в формат .mp3 в папку voice_files.

Метод bot.get_file принимает идентификатор файла голосового сообщения voice и возвращает информацию о файле. Нам нужен путь к файлу.

Создаем байтовую переменную voice_ogg в которую будет скачиваться голосовое сообщение с сервера в формате .ogg. Затем методом bot.download_file, который принимает путь к файлу на сервере и место назначения для сохранения, скачиваем файл. Передаем путь к файлу voice_file_info.file_path и место для сохранения voice_ogg.

Далее используем класс AudioSegment из библиотеки pydub для преобразования формата файла из .ogg в .mp3. Задаем путь для сохранения файла в переменную voice_mp3_path. Используем метод from_file для открытия файла и сразу же метод export для сохранения конвертированного файла по месту назначения, указывая форматы данных.

Функция возвращает путь к скаченному файлу.

Осталось за малым — соединить всё воедино в нашем обработчике. Для этого отредактируем его следующим образом:

# Листинг [8]
# Обработчик транскрибирующий голосовые сообщения

@router.message(F.content_type == "voice")
async def process_voice_message(message: Message, bot: Bot):
    """Принимает голосовое сообщение, транскрибирует его в текст."""
    voice_path = await save_voice_as_mp3(bot, message.voice)
    transcripted_voice_text = await audio_to_text(voice_path)

    if transcripted_voice_text:
        await message.reply(text=transcripted_voice_text)

Наш обработчик process_voice_message принимает все голосовые сообщения пользователя, как указано в декораторе. Сперва идет вызов нашей функции save_voice_as_mp3 из листинга №7 для скачивания голосового сообщения в директорию voice_files в формате .mp3, она возвращает путь к скаченному файлу. Далее вызывается функция audio_to_text из листинга №5 для выполнения запроса к OpenAI API на транскрибацию. Функция возвращает текст аудио файла. Если модель разобрала речь, то возвращается не пустая строка, которую мы распечатываем в чат Telegram бота.

Полный код файла bot.py:

# Листинг [9]
# Телеграм бот транскрибирующий голосовые сообщения

import asyncio
import io

from aiogram import Bot, Dispatcher, F, Router
from aiogram.types import Message, Voice

import openai
from pydub import AudioSegment


openai.api_key = "sk-BhC44H9LVVtSE74BlbkGGtPs0OTGDx21tjPVu7bzl"
BOT_TOKEN = "5842123168:AAHyhAIFWeh4-8jYvo72eZeq18-9P2wQmaY"

router: Router = Router()


async def audio_to_text(file_path: str) -> str:
    """Принимает путь к аудио файлу, возвращает текст файла."""
    with open(file_path, "rb") as audio_file:
        transcript = await openai.Audio.atranscribe(
	        "whisper-1", audio_file
	    )
    return transcript["text"]


async def save_voice_as_mp3(bot: Bot, voice: Voice) -> str:
    """Скачивает голосовое сообщение и сохраняет в формате mp3."""
    voice_file_info = await bot.get_file(voice.file_id)
    voice_ogg = io.BytesIO()
    await bot.download_file(voice_file_info.file_path, voice_ogg)
    voice_mp3_path = f"voice_files/voice-{voice.file_unique_id}.mp3"
    AudioSegment.from_file(voice_ogg, format="ogg").export(
	    voice_mp3_path, format="mp3"
	)
    return voice_mp3_path


@router.message(F.content_type == "voice")
async def process_voice_message(message: Message, bot: Bot):
    """Принимает все голосовые сообщения и транскрибирует их в текст."""
    voice_path = await save_voice_as_mp3(bot, message.voice)
    transcripted_voice_text = await audio_to_text(voice_path)

    if transcripted_voice_text:
        await message.reply(text=transcripted_voice_text)


async def main():
    bot: Bot = Bot(token=BOT_TOKEN)
    dp: Dispatcher = Dispatcher()
    dp.include_router(router)
    await dp.start_polling(bot)


if __name__ == "__main__":
    asyncio.run(main())

Результат:

В статье мы рассмотрели эффективный способ получения текстовых версий голосовых сообщений в Telegram боте, используя API OpenAI. Использование OpenAI API значительно упрощает процесс транскрибации голосовых сообщений и делает его более точным и надежным. Всем удачи в изучении!

В статье изложена инструкция получения токена OpenAI API и обхода блокировки OpenAI сайта из России.

OpenAI API — это программный интерфейс приложения, который предоставляет доступ к технологиям искусственного интеллекта, разработанным и поддерживаемым исследовательской лабораторией OpenAI. API позволяет разработчикам интегрировать функциональность OpenAI в свои собственные приложения и использовать различные модели машинного обучения, такие как обработка естественного языка, генерация текста и т.д.

Чтобы использовать API, вам необходимо получить токен на сайте OpenAI. Для России сайт заблокирован. Для преодоления блокировки необходимо иметь VPN и заграничный телефонный номер, чтобы получить СМС для регистрации. В статье на Хабр подробно и точно описано как обойти блокировку при помощи “виртуального” номера телефона. У меня это заняло примерно 10 минут и 20 рублей. Ссылка на статью: Как получить доступ к chatGPT в России.

Если вы получили доступ к платформе OpenAI и смогли зайти на страницу ChatGPT, тогда мы можем продолжать.

Сперва перейдем на страницу входа в аккаунт OpenAI: https://platform.openai.com/signup

После входа вас должно направить на страницу: https://platform.openai.com/overview

В меню находим View API keys и переходим туда:

Тут у вас отображается список имеющихся токенов и есть кнопка создания нового Create new secret key, нажимаем на неё:

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

Поздравляю! Теперь у вас есть возможность использовать OpenAI API в своих приложениях. Исследуйте документацию и возможности этого инструмента, они обширны и интересны. Удачи в изучении!