Telegram 및 Max 봇을 위한 obabot

obabot: Telegram과 Max 봇을 위한 범용 라이브러리

obabot 라이브러리는 단일 비동기 Python 봇을 Telegram과 Max에서 동시에 배포할 수 있게 해줍니다. API는 aiogram 3.x와 완벽하게 호환되며, Telegram에는 네이티브 aiogram을 사용하고 Max에는 이벤트를 호환 객체로 변환하는 어댑터를 씁니다. 설치도 간단합니다: pip install obabot aiogram>=3.0.0 umaxbot>=0.1.7.

핵심 create_bot() 함수는 플랫폼 토큰을 받아 (bot, dispatcher, router) 튜플을 반환합니다. 메시지 핸들러는 플랫폼에 상관없이 동일하게 작성할 수 있습니다.

초기화 예제

Telegram용:

from obabot import create_bot
from obabot.filters import Command

bot, dp, router = create_bot(tg_token="YOUR_TG_TOKEN")

@router.message(Command("start"))
async def start(message):
    await message.answer(f"{message.platform}에서 안녕하세요!")

await dp.start_polling(bot)

Max용:

from obabot import create_bot
from obabot.filters import Command

bot, dp, router = create_bot(max_token="YOUR_MAX_TOKEN")

@router.message(Command("start"))
async def start(message):
    await message.answer(f"{message.platform}에서 안녕하세요!")

await dp.start_polling(bot)

두 플랫폼 동시 사용:

from obabot import create_bot
from obabot.filters import Command

bot, dp, router = create_bot(
    tg_token="YOUR_TG_TOKEN",
    max_token="YOUR_MAX_TOKEN"
)

@router.message(Command("start"))
async def start(message):
    await message.answer(f"{message.platform}에서 안녕하세요!")

await dp.start_polling(bot)

message.platform 속성은 "telegram" 또는 "max"를 반환해 플랫폼별 로직을 구현할 수 있습니다.

aiogram에서 마이그레이션

순수 aiogram 3.x에서 전환할 때 변경 사항은 최소입니다. import만 바꾸고 create_bot()을 사용하면 됩니다. 별도의 Bot, Dispatcher, Router 초기화가 필요 없습니다.

기존 aiogram 코드:

from aiogram import Bot, Dispatcher, Router
from aiogram.filters import Command
from aiogram.fsm.state import State, StatesGroup
from aiogram.fsm.context import FSMContext

bot = Bot(token="TOKEN")
dp = Dispatcher()
router = Router()
dp.include_router(router)

@router.message(Command("start"))
async def start(message):
    await message.answer("안녕하세요!")

await dp.start_polling(bot)

마이그레이션 후:

from obabot import create_bot
from obabot.filters import Command
from obabot.fsm import State, StatesGroup, FSMContext

bot, dp, router = create_bot(tg_token="TOKEN")

@router.message(Command("start"))
async def start(message):
    await message.answer("안녕하세요!")

await dp.start_polling(bot)

FSM, 필터, 키보드 등 나머지 코드는 그대로 사용할 수 있습니다.

Message 인터페이스와 기본 메서드

모든 Message 객체는 통합 인터페이스를 공유합니다:

• message.text — 텍스트
• message.from_user — 발신자
• message.chat — 채팅
• message.message_id — ID
• message.platform — 플랫폼

메서드:

• await message.answer("답변")
• await message.reply("메시지 답변")
• await message.delete()
• await message.edit_text("새 텍스트")

FSM: 상태 머신

FSM은 aiogram과 동일하게 작동합니다:

from obabot.fsm import State, StatesGroup, FSMContext

class Form(StatesGroup):
    name = State()
    age = State()

@router.message(Command("start"))
async def start(message, state: FSMContext):
    await state.set_state(Form.name)
    await message.answer("이름이 어떻게 되세요?")

@router.message(Form.name)
async def process_name(message, state: FSMContext):
    await state.update_data(name=message.text)
    await state.set_state(Form.age)
    await message.answer("나이가 어떻게 되세요?")

인라인 키보드와 필터

키보드 생성:

from obabot.types import InlineKeyboardMarkup, InlineKeyboardButton

keyboard = InlineKeyboardMarkup(inline_keyboard=[
    [
        InlineKeyboardButton(text="버튼 1", callback_data="btn1"),
        InlineKeyboardButton(text="버튼 2", callback_data="btn2"),
    ]
])

await message.answer("하나 선택하세요:", reply_markup=keyboard)

필터:

• @router.message(Command("start", "help")) — 여러 명령어
• @router.message(F.text.startswith("!")) — 접두사
• @router.message(F.photo) — 사진
• @router.callback_query(F.data == "click") — 콜백

토큰 없이 테스트

test_mode=True로 네트워크 호출을 모두 건너뜁니다:

bot, dp, router = create_bot(test_mode=True)

Python 3.10–3.14, aiogram 3.0.0–3.24 지원. 완전한 단위 테스트 커버리지.

핵심 장점

• 단일 코드베이스: Telegram과 Max에 하나의 핸들러만—어댑터 불필요.
• 완벽 호환: aiogram 3.x API 100% + platform 속성.
• FSM과 필터: 상태, 인라인 키보드, 마법 필터 F 완전 지원.
• 쉬운 마이그레이션: import 2줄과 초기화만 변경.
• 테스트: API 호출 없는 독립 모드.

— Editorial Team