Metadata-Version: 2.4
Name: pybotaltgram
Version: 1.0.5
Summary: Python SDK for AltGram Bot API
License: MIT
Project-URL: Homepage, https://t.me/altgramofficial
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28

# 🤖 AltGramApi

> Python-библиотека для [AltGram Bot API](https://t.me/altgramofficial) в стиле pyTelegramBotAPI — просто, быстро, по-русски.

[![PyPI version](https://img.shields.io/pypi/v/altgramapi?color=blue&label=PyPI)](https://pypi.org/project/altgramapi/)
[![Python](https://img.shields.io/pypi/pyversions/altgramapi)](https://pypi.org/project/altgramapi/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Downloads](https://img.shields.io/pypi/dm/altgramapi)](https://pypi.org/project/altgramapi/)

---

## ⚡ Установка

```bash
pip install altgramapi
```

---

## 🚀 Быстрый старт

```python
import altgrambot as ag

bot = ag.Bot("ВАШ_ТОКЕН")

@bot.message_handler(commands=["start"])
def on_start(msg: ag.Message):
    msg.reply("Привет! Я работаю на AltGram 🚀")

@bot.message_handler(content_types=["text"])
def echo(msg: ag.Message):
    msg.reply(msg.text)

bot.polling()
```

---

## ✨ Возможности

- 🎯 **Декораторы** — регистрация хендлеров в одну строку
- ⌨️ **Клавиатуры** — `InlineKeyboardBuilder` и `ReplyKeyboardBuilder` с fluent API
- ✍️ **Форматирование** — `EntityBuilder` вместо parse_mode (bold, italic, code, spoiler...)
- 🔍 **Фильтры** — мощная система с поддержкой `&`, `|`, `~`
- 📁 **Файлы** — отправка и скачивание любых медиа
- 🔄 **Long polling** — встроенный, с авто-рестартом при ошибках
- 🌐 **Webhook** — поддержка Flask/FastAPI
- 💬 **Хелперы** — `msg.reply()`, `msg.delete()`, `query.answer()` прямо на объектах

---

## 📖 Примеры

### Инлайн-клавиатура

```python
@bot.message_handler(commands=["menu"])
def menu(msg: ag.Message):
    kb = (
        ag.InlineKeyboardBuilder()
        .button("✅ Да",  callback_data="yes", style="success")
        .button("❌ Нет", callback_data="no",  style="danger")
        .row()
        .button("🌐 Сайт", url="https://t.me/altgramofficial")
        .build()
    )
    msg.reply("Выберите:", reply_markup=kb)

@bot.callback_query_handler(data="yes")
def on_yes(query: ag.CallbackQuery):
    query.answer("Отлично! ✅")
    query.edit_message_text("Вы нажали Да!")
```

### Форматирование текста

```python
@bot.message_handler(commands=["info"])
def info(msg: ag.Message):
    text, entities = (
        ag.EntityBuilder()
        .bold("AltGramApi v1.0\n\n")
        .plain("Библиотека для ")
        .link("AltGram", "https://t.me/altgramofficial")
        .plain("\n\nУстановка: ")
        .code("pip install altgramapi")
        .build()
    )
    msg.reply(text, entities=entities)
```

### Фильтры

```python
from altgrambot.filters import F

# Только в личке
@bot.message_handler(filters=[F.command("start") & F.chat_type("private")])
def private_start(msg): ...

# Фото или видео, не в ответ
@bot.message_handler(filters=[
    (F.content_type("photo") | F.content_type("video")) & ~F.is_reply()
])
def on_media(msg): ...
```

### Отправка файлов

```python
# Из интернета
bot.send_photo(chat_id, "https://example.com/photo.jpg", caption="Фото")

# Файл с диска
bot.send_document(chat_id, open("file.pdf", "rb"), caption="Документ")

# Скачать файл
data = bot.download_file(file_id)
bot.download_file_to(file_id, "saved.jpg")
```

### Webhook (Flask)

```python
from flask import Flask, request
app = Flask(__name__)

@app.post("/webhook")
def webhook():
    bot.process_webhook_update(request.get_json())
    return {"ok": True}

bot.set_webhook("https://yourdomain.com/webhook")
app.run(port=8443)
```

---

## 📋 Все методы

### Отправка сообщений

| Метод | Описание |
|-------|----------|
| `send_message(chat_id, text)` | Текст |
| `send_photo(chat_id, photo)` | Фото |
| `send_document(chat_id, doc)` | Файл |
| `send_video(chat_id, video)` | Видео |
| `send_audio(chat_id, audio)` | Аудио |
| `send_voice(chat_id, voice)` | Голосовое |
| `send_animation(chat_id, gif)` | GIF |
| `send_sticker(chat_id, file_id)` | Стикер |
| `send_video_note(chat_id, file_id)` | Круглое видео |
| `send_contact(chat_id, phone, name)` | Контакт |
| `send_location(chat_id, lat, lon)` | Геолокация |
| `send_venue(chat_id, lat, lon, title, addr)` | Место |
| `send_live_photo(chat_id, photo, video)` | Live Photo |

### Редактирование и удаление

| Метод | Описание |
|-------|----------|
| `edit_message_text(chat_id, msg_id, text)` | Изменить текст |
| `edit_message_reply_markup(chat_id, msg_id, kb)` | Изменить кнопки |
| `delete_message(chat_id, msg_id)` | Удалить |
| `edit_ephemeral_message_text(...)` | Редактировать эфемерное |
| `delete_ephemeral_message(...)` | Удалить эфемерное |

### Прочее

| Метод | Описание |
|-------|----------|
| `get_me()` | Информация о боте |
| `set_my_commands(cmds)` | Установить команды меню |
| `get_my_commands()` | Список команд |
| `answer_callback_query(id, text)` | Ответить на callback |
| `answer_inline_query(id, results)` | Ответить на inline |
| `get_file(file_id)` | Метаданные файла |
| `download_file(file_id)` | Скачать → bytes |
| `download_file_to(file_id, path)` | Скачать → файл |
| `set_webhook(url)` | Установить webhook |
| `delete_webhook()` | Удалить webhook |
| `set_chat_menu_button(btn)` | Кнопка меню |

---

## 🎛️ Хендлеры

```python
@bot.message_handler(commands=["start"])          # По команде
@bot.message_handler(content_types=["photo"])     # По типу контента
@bot.message_handler(regexp=r"^\d+$")             # По regex
@bot.message_handler(func=lambda m: m.chat.id > 0) # Своя функция
@bot.message_handler(chat_types=["private"])      # Тип чата
@bot.message_handler()                            # Catch-all

@bot.callback_query_handler(data="btn")           # Точное совпадение
@bot.callback_query_handler(regexp=r"^page:")     # По regex

@bot.edited_message_handler(content_types=["text"]) # Редактирование
@bot.inline_query_handler()                          # Inline-режим

@bot.error_handler()                              # Перехват ошибок
```

---

## 🔍 Система фильтров

```python
from altgrambot.filters import F

F.command("start", "help")   # Команды
F.text("ping")               # Точный текст
F.text_contains("hello")     # Содержит
F.text_starts_with("/")      # Начинается с
F.regexp(r"^\d+$")           # Regex
F.content_type("photo")      # Тип контента
F.chat_type("private")       # Тип чата
F.from_user(123456)          # Конкретный юзер
F.is_reply()                 # Это ответ
F.has_caption()              # Есть подпись

# Логика
F.command("ban") & F.chat_type("group")   # И
F.content_type("photo") | F.content_type("video")  # ИЛИ
~F.is_reply()                             # НЕ
```

---

## ✍️ EntityBuilder — форматирование

AltGram не поддерживает `parse_mode`. Используй `EntityBuilder`:

```python
text, entities = (
    ag.EntityBuilder()
    .bold("Заголовок\n")
    .italic("Подзаголовок\n\n")
    .plain("Обычный текст ")
    .code("инлайн код")
    .newline()
    .pre("блок кода", language="python")
    .underline("подчёркнутый")
    .strikethrough("зачёркнутый")
    .spoiler("спойлер")
    .link("ссылка", "https://example.com")
    .mention("Юзер", user_id=123456)
    .blockquote("цитата")
    .build()
)
bot.send_message(chat_id, text, entities=entities)
```

---

## 💬 Хелперы на объектах

```python
# Message
msg.reply("с цитатой")
msg.answer("без цитаты")
msg.reply_photo(photo)
msg.reply_document(doc)
msg.delete()
msg.edit_text("новый текст")
msg.content_type    # 'text' / 'photo' / 'video' / ...
msg.command         # 'start' для /start
msg.args            # ['arg1', 'arg2'] для /cmd arg1 arg2

# CallbackQuery
query.answer("текст")
query.answer("Алерт!", show_alert=True)
query.edit_message_text("новый текст")
query.edit_reply_markup(kb)
query.delete_message()
```

---

## 🔄 Polling

```python
bot.polling()                        # Обычный
bot.polling(skip_pending=True)       # Пропустить старые
bot.infinity_polling()               # Не падать при ошибках
bot.stop_polling()                   # Остановить
```

---

## 📦 Структура пакета

```
altgrambot/
  bot.py         — Bot класс, все методы API
  types.py       — Message, User, Chat, CallbackQuery...
  keyboards.py   — InlineKeyboardBuilder, ReplyKeyboardBuilder
  entities.py    — EntityBuilder (форматирование)
  filters.py     — Фильтры + F-namespace
  exceptions.py  — APIError, NetworkError...
```

---

## 🔗 Ссылки

- 📦 [PyPI](https://pypi.org/project/altgramapi/)
- 💬 [AltGram](https://t.me/altgramofficial)
- 🐛 Нашёл баг? Напиши в AltGram

---

<p align="center">Сделано с ❤️ для AltGram сообщества</p>
