netcherTG

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

Install

pip install netcherTG

Getting a bot token

Message @BotFather on Telegram, run /newbot, and follow the prompts to get an API token.

Quick start

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

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

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:

@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)

@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

@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

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

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

License

MIT