DOCSEARCHbyAlgolia
Submit Docs

TGPy Documentation

website·Indexed 32 days ago

https://pcraft.dev/

A command line application and framework for running Python code directly within Telegram. It is based on the Telethon library and allows users to send messages, manage chats, and create modules and recipes for automating Telegram tasks. The documentation includes installation guides, asyncio basics, and a comprehensive guide on designing Telegram bots, including command design, button flows, and message formatting.

Tokens
22.1K
Snippets
104
Records
207
Agent score
52%

What's inside TGPy

  1. Overview of TGPy capabilities

    TGPy is a 'userbot for programmers' built on the Telethon library. It enables the execution of Python code snippets directly within Telegram messages. Key features include:

    • Integration with Python libraries and APIs.
    • Creation of reusable functions and TGPy modules.
    • Customization of Python syntax and command creation via code transformers and hooks.
    • Use cases include in-chat calculations, searching lyrics, bulk message deletion, and chat activity analysis.

  2. Overview of the Folds Telegram bot framework

    Folds is a minimalistic and scalable Python framework for creating Telegram bots. Unlike most bot frameworks, it wraps the Telethon library to interact directly with the Telegram API rather than the Telegram Bot API. This architecture removes the natural limitations of the Bot API and allows developers to reuse code for both bots and userbots (user accounts).

  3. Use Python features and Telegram integration in TGPy

    TGPy supports full Python functionality, including module imports and function definitions. It also allows interaction with Telegram features, such as sending messages, directly from the Python code.

  4. Use the TGPy context object (ctx)

    The ctx object provides metadata about the current execution environment and allows control over output behavior.
    # Access the message where the code is running
current_msg = ctx.msg

# Check if the code is executing as part of a module
if ctx.is_module:
    print("Running from module")

# Prevent TGPy from editing the final output message so the user can edit it manually
ctx.is_manual_output = True

  5. Understand and use TGPy recipes

    TGPy recipes are short tutorials and use cases designed to help developers re-implement specific scenarios or gain a deeper understanding of TGPy and Telethon features. They provide copy-pasteable code snippets that can be modified to fit specific project needs and can be read in any order.

  6. Manage sticker and custom emoji sets with Telegram Bots

    Telegram bots can create, rename, edit, and delete sticker and custom emoji sets. While users often use the @Stickers bot or the Stickers Mini App, developers can use the Telegram Bot API to automate these workflows for brand packs, community generators, or moderation tools.

    Key constraints:

    • Only bots can create sticker and custom emoji sets.
    • Every pack must have a designated user as its owner.
    • Custom emoji sets can be created by any bot and owned by any user, but only Telegram Premium users can use custom emoji from these sets.

  7. Access bot instances in separate skill files using context variables

    When defining a Skill in a separate file where the bot instance is not directly available, you can use folds.context.bot to access information about the current bot executing the rule, such as the bot's username.
    from folds import Skill
from folds.context import bot

skill = Skill()

@skill.private_message
async def f():
    print(bot)
    return 'You are speaking to @' + bot.me.username

  8. Use Telethon objects in TGPy

    TGPy is built on the Telethon library. Developers can use Telethon objects and methods for messages, users, and chats. The following built-in objects are available in the TGPy environment:

    • client: The Telethon client instance used for general functionality (e.g., sending messages, listing chats).
    • msg: The current message object.
    • orig: The message object that is being replied to (returns None if the current message is not a reply).

  9. Requirements for building a basic Telegram bot

    To create a functional Telegram bot, you need four fundamental components: a bot registered via BotFather, a control token, a programming library compatible with your chosen language, and a program capable of receiving updates and sending responses. For production, the program should be deployed to a hosting service rather than run locally.

  10. Requirements for using Telegram bots in channels

    Bots can only participate in Telegram channels if they are added as administrators. Channel owners can customize the specific admin rights granted to the bot. If specific features are required, these rights should be configured via BotFather.

  11. Persist bot data from updates

    The Bot API does not provide methods to fetch the latest user messages or a list of chats where the bot belongs. Information about users and chats is primarily provided within the updates themselves (e.g., when a user sends a message). To maintain a list of bot users or a history of received messages, you must save this data to a database as it arrives. If this information is lost, it cannot be retrieved via the Bot API.

  12. Identify Telegram users by ID for reliable storage

    When storing user profile information, use the user ID as the primary identifier. Other profile data—such as first name, last name, and username—can change over time or may be missing entirely (e.g., a user may have no username or last name). Relying on the ID ensures a consistent way to identify a user across profile updates.
    # Example of safely constructing a display name when last_name might be None
if user.last_name is None:
    full_name = user.first_name
else:
    full_name = f'{user.first_name} {user.last_name}'