Metadata-Version: 2.4
Name: netcherTG
Version: 0.2.0
Summary: A simple, dependency-light library for building Telegram bots
Author: Necher
License: MIT
Project-URL: Homepage, https://pypi.org/project/netcherTG/
Keywords: telegram,bot,telegram-bot,api
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25

# netcherTG

A simple, dependency-light Python library for building Telegram bots on top
of the official Telegram Bot HTTP API.

## Install

```bash
pip install netcherTG
```

## Getting a bot token

Message [@BotFather](https://t.me/BotFather) on Telegram, run `/newbot`,
and follow the prompts to get an API token.

## Quick start

```python
from netcherTG import Bot

bot = Bot("123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11")

@bot.command("start")
def start(bot, message):
    bot.send_message(message.chat_id, f"Hello, {message.username}!")

@bot.command("echo")
def echo(bot, message):
    text = " ".join(message.args()) or "(nothing to echo)"
    bot.send_message(message.chat_id, text)

@bot.message_handler()
def fallback(bot, message):
    bot.send_message(message.chat_id, "I didn't understand that.")

bot.run()
```

## Inline keyboards

```python
from netcherTG import Bot, keyboards

bot = Bot("YOUR_TOKEN")

@bot.command("menu")
def menu(bot, message):
    kb = keyboards.inline_keyboard([
        [("Yes", "yes"), ("No", "no")],
    ])
    bot.send_message(message.chat_id, "Choose one:", reply_markup=kb)

@bot.callback_query_handler()
def on_click(bot, query):
    bot.answer_callback_query(query.id, text="Got it!")
    bot.send_message(query.message.chat_id, f"You picked: {query.data}")

bot.run()
```

## Reply keyboards

```python
from netcherTG import keyboards

kb = keyboards.reply_keyboard([["Option A", "Option B"], ["Cancel"]])
bot.send_message(chat_id, "Pick one:", reply_markup=kb)
```

## What's new in 0.2.0

Features you won't find built into most other Telegram bot libraries:

### Automatic `/help`

If you don't define your own `/help`, one is generated for you from your
commands' docstrings:

```python
@bot.command("start")
def start(bot, message):
    "Start the bot"
    ...
```
Users typing `/help` get a clean list of all commands automatically.
Turn it off with `bot.disable_auto_help()`.

### Typo suggestions

If a user sends an unknown command, netcherTG suggests the closest match:

```
User: /stwrt
Bot:  Unknown command. Did you mean /start?
```

### Built-in per-user sessions (no separate FSM library needed)

```python
@bot.command("setname")
def setname(bot, message):
    bot.session(message.user_id)["awaiting_name"] = True

@bot.message_handler()
def on_text(bot, message):
    s = bot.session(message.user_id)
    if s.get("awaiting_name"):
        s["name"] = message.text
        s["awaiting_name"] = False
        bot.send_message(message.chat_id, f"Saved: {message.text}")
```

### Rate limiting per handler, per user

```python
@bot.command("draw")
@bot.rate_limit(seconds=5)
def draw(bot, message):
    ...
```
Repeat calls inside the window are silently ignored — no spam replies.

### "Typing..." context manager

```python
with bot.typing(message.chat_id):
    result = slow_computation()
bot.send_message(message.chat_id, result)
```

### Auto-retry with backoff

`bot.run()` no longer crashes on a dropped connection — it retries with
exponential backoff (up to `max_backoff` seconds) automatically.

### Escaping helpers

```python
from netcherTG import escape_markdown, escape_html

bot.send_message(chat_id, escape_markdown(user_input), parse_mode="MarkdownV2")
```
Avoids `400 Bad Request: can't parse entities` errors from unescaped
special characters.

## API overview

| Method | Description |
|---|---|
| `Bot(token)` | Create a bot instance |
| `bot.send_message(chat_id, text, ...)` | Send a text message |
| `bot.send_photo(chat_id, photo_url, caption=None)` | Send a photo |
| `bot.edit_message_text(chat_id, message_id, text)` | Edit an existing message |
| `bot.delete_message(chat_id, message_id)` | Delete a message |
| `bot.answer_callback_query(id, text=None)` | Acknowledge a button press |
| `bot.get_me()` | Get info about the bot |
| `@bot.command(name)` | Register a `/command` handler |
| `@bot.message_handler()` | Register a handler for plain text messages |
| `@bot.callback_query_handler()` | Register a handler for inline button presses |
| `bot.run(poll_interval=1.0)` | Start long-polling |
| `bot.session(user_id)` | Get/create a per-user state dict |
| `bot.clear_session(user_id)` | Clear a user's stored session |
| `@bot.rate_limit(seconds)` | Throttle a handler per user |
| `bot.typing(chat_id)` | Context manager for "typing..." indicator |
| `bot.disable_auto_help()` | Turn off the auto-generated `/help` |
| `escape_markdown(text)` / `escape_html(text)` | Escape text for safe sending |

## License

MIT
