Metadata-Version: 2.1
Name: PyRubikaBotAPI
Version: 1.0.2
Summary: A Python library with a simple and familiar interface for working with the official Rubika bot API
Home-page: https://github.com/alireza-sadeghian/PyRubikaBotAPI
Author: Alireza Sadeghian
Author-email: alireza.amid110@gmail.com
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: requests

# PyRubikaBotAPI

A powerful and intuitive Python library for building Rubika bots – from simple echo bots to advanced interactive assistants.

[![PyPI version](https://img.shields.io/pypi/v/PyRubikaBotAPI)](https://pypi.org/project/PyRubikaBotAPI/)
[![Python](https://img.shields.io/badge/python-3.10+-blue)](https://www.python.org/)

---

## Installation

Requires **Python 3.10** or higher.

```bash
pip install PyRubikaBotAPI
```

To upgrade pip first:
```bash
python -m pip install --upgrade pip
```

---

## Quick Start

1. Create a bot via [@BotFather](https://rubika.ir) and get your token.
2. Write your first bot:

```python
from rubibot import RubiBot

bot = RubiBot("YOUR_BOT_TOKEN")

@bot.message_handler(commands=["start"])
def start(message):
    bot.send_message(message.chat_id, "Hello! Welcome to my Rubika bot.")

bot.polling()
```

Run the script and your bot is live!

---

## Core Features

### Message Handlers
Handle incoming messages based on commands, content type, or custom logic. Handlers are executed in order, and **only the first matching handler runs** for each message.

```python
# Handle /start and /help
@bot.message_handler(commands=["start", "help"])
def handle_commands(message):
    ...

# Handle all stickers
@bot.message_handler(content_types=["sticker"])
def sticker_handler(message):
    ...

# Catch-all for any text message
@bot.message_handler()
def echo(message):
    bot.reply_to(message, f"You said: {message.text}")
```

**Supported content types:** `text`, `file`, `location`, `sticker`, `contact`, `poll`  
**Supported update types:** `NewMessage`, `UpdatedMessage`, `RemovedMessage`, `StartedBot`, `StoppedBot`

---

### Sending Messages & Replies

- `send_message(chat_id, text, ...)` – Send text (max ~4096 chars). Supports inline/chat keypads, silent notifications, reply IDs.
- `reply_to(message, text, ...)` – Convenience method to reply directly to a user's message.

```python
bot.send_message(chat_id, "Hello World!")
bot.reply_to(message, "Thanks for your message!")
```

---

### Media & Files

Send photos, videos, voices, GIFs, and other files. All methods accept a file path (`str`) or a file-like object (`BufferedReader`).

| Method        | Max Size | Formats               |
|---------------|----------|-----------------------|
| `send_photo`  | 10 MB    | PNG, JPG, GIF, WEBP   |
| `send_voice`  | –        | MP3                   |
| `send_video`  | 50 MB    | MP4                   |
| `send_gif`    | –        | MP4 (no sound)        |
| `send_file`   | 50 MB    | Any                   |

```python
bot.send_photo(chat_id, "image.png", text="Check this out!")
bot.send_video(chat_id, "video.mp4", text="Watch this")
```

---

### Interactive Keypads

Two types of keypads are available:

- **ChatKeypad** – Persistent buttons at the bottom of the chat.
- **InlineKeypad** – Buttons directly under a message.

```python
from rubibot.types import KeypadSimpleButton, KeypadRow, InlineKeypad, ChatKeypad

# Create buttons
btn1 = KeypadSimpleButton("Option 1", "id1")
btn2 = KeypadSimpleButton("Option 2", "id2")

row = KeypadRow().add(btn1, btn2)

inline_kb = InlineKeypad().add(row)
chat_kb = ChatKeypad(resize_keyboard=True).add(row)

# Send with inline buttons
bot.send_message(chat_id, "Choose:", inline_keypad=inline_kb)

# Send with chat keypad
bot.send_message(chat_id, "Menu:", chat_keypad=chat_kb)

# Remove chat keypad
from rubibot.types import ChatKeypadRemove
bot.send_message(chat_id, "Keypad removed", chat_keypad=ChatKeypadRemove())
```

For advanced inputs, use `KeypadCalendarButton`, `KeypadNumberPickerButton`, `KeypadStringPickerButton`, `KeypadLocationButton`, `KeypadTextboxButton`. (See documentation for details.)

---

### Polls & Contacts

```python
from rubibot.types import ChatPoll

poll = ChatPoll("Your favorite language?")
poll.add_options("Python", "JavaScript", "Go")
bot.send_poll(chat_id, poll)

bot.send_contact(chat_id, "Ali", "Rezaei", "+989123456789")
```

---

### Message Management

- **Forward:** `bot.forward(from_chat_id, to_chat_id, message_id)`
- **Edit:** `bot.edit_message(chat_id, message_id, new_text="...", new_inline_keypad=...)`
- **Delete:** `bot.delete_message(chat_id, message_id)`

---

### Bot & Chat Information

- `bot.get_me()` – Get bot details (username, avatar, description, share URL).
- `bot.get_chat(chat_id)` – Get chat info (title, username, type).

```python
info = bot.get_me()
print(info.username)

chat = bot.get_chat("chat_id")
print(chat.title)
```

---

### Commands Registration

```python
from rubibot.types import BotCommand

bot.set_commands(
    BotCommand("/start", "Start the bot"),
    BotCommand("/help", "Show help menu")
)
```

---

### Running the Bot

#### Polling (for development / testing)
```python
bot.polling(t=1, limit=10)   # Check updates every 1 second
```
⚠️ Polling is not optimized for production. Use webhooks instead.

#### Webhooks (production)
```python
bot.set_webhook("https://your-server.com/webhook")
```

Then process incoming JSON manually with `process_new_updates`:
```python
from rubibot.updates import Update

# Inside your web framework endpoint:
update = Update(request.json)
bot.process_new_updates([update])
```

---

## Working with Updates & Models

### Message Object
When a handler is called, you receive a `Message` object with useful attributes:
`chat_id`, `message_id`, `text`, `sender_id`, `file`, `location`, `sticker`, `contact`, `poll`, `aux` (button data), `forwarded_from`, etc.

```python
@bot.message_handler()
def handler(message):
    if message.has_file():
        file_id = message.file.id
        url = bot.get_file(file_id)
        data = bot.download_file(url)
        # Save or process the file
```

### Aux Data (Button Clicks)
When a user taps a button, `message.aux.button_id` gives the ID you assigned. Use it to branch logic.

### Next‑Step Handlers
You can register a one‑time handler for the very next message in a specific chat or from a specific user – useful for multi‑step flows:

```python
bot.register_next_step_message_handler_by_chat_id(chat_id, my_callback)
```

---

## Complete Example

```python
from rubibot import RubiBot
from rubibot.types import (
    Message, KeypadSimpleButton, KeypadRow,
    ChatKeypad, ChatKeypadRemove, BotCommand
)

bot = RubiBot("YOUR_TOKEN")

@bot.message_handler(commands=["start"])
def start(message: Message):
    btn = KeypadSimpleButton("Say Hello", "hello_btn")
    row = KeypadRow().add(btn)
    kb = ChatKeypad(resize_keyboard=True).add(row)

    bot.send_message(message.chat_id, "Welcome!", chat_keypad=kb)

@bot.message_handler()
def handle_all(message: Message):
    if message.aux and message.aux.button_id == "hello_btn":
        bot.reply_to(message, "Hello! Keypad removed.", chat_keypad=ChatKeypadRemove())
    else:
        bot.reply_to(message, f"You said: {message.text}")

@bot.message_handler(content_types=["file"])
def file_handler(message: Message):
    url = bot.get_file(message.file.id)
    data = bot.download_file(url)
    with open("received_file", "wb") as f:
        f.write(data)
    bot.send_message(message.chat_id, "File saved!")

if __name__ == "__main__":
    bot.set_commands(
        BotCommand("start", "Start the bot")
    )
    bot.polling()
```

---

## Documentation & Community

- **Rubika Channel:** [PyRubikaBotAPI](https://rubika.ir/PyRubikaBotAPI)
- **GitHub Repository:** [alireza-sadeghian/PyRubikaBotAPI](https://github.com/alireza-sadeghian/PyRubikaBotAPI)

More examples and detailed API docs are available there.

---

## Author

**Alireza Sadeghian**  
📧 alireza.amid110@gmail.com

---

**License:** MIT
