telemaster-lib 1.0.2

Professional Telegram account management library built on Telethon — structured API with Result objects.

📡 TeleMaster

Professional Telegram account management library — 67 methods, zero print(), zero input()

Installation • Quick Start • Features • API • Examples • العربية

---

✨ Why TeleMaster?

Feature	Raw Telethon	TeleMaster
Error handling	Manual try/except everywhere	✅ Built-in, returns Result
Login flow	Monolithic, requires input()	✅ Step-by-step, UI-agnostic
Output	print() mixed with logic	✅ Zero prints, pure data
API surface	Low-level RPC calls	✅ 67 high-level methods
Speed	Standard crypto	✅ cryptg accelerated
Type hints	Partial	✅ Full typing, PEP 561

📦 Installation

# From PyPI (when published)
pip install telemaster

# From GitHub
pip install git+https://github.com/OmarMoh12/telemaster.git

# From source
git clone https://github.com/OmarMoh12/telemaster.git
cd telemaster
pip install -e .

# With speed optimizations
pip install -e ".[fast]"

🚀 Quick Start

import asyncio
from telemaster import TeleMaster

async def main():
    tm = TeleMaster(
        phone="[phone]",
        api_id=12345,
        api_hash="your_api_hash",
    )

    # Connect
    await tm.connect()

    # Login (step-by-step — no input() needed!)
    result = await tm.send_code()
    code = "12345"  # Get this from your UI, bot, webhook, etc.
    result = await tm.verify_code(code)

    if result.error_type == "2FA_REQUIRED":
        result = await tm.verify_2fa("your_password")

    # Send a message
    result = await tm.send_message("me", "Hello! 🚀")
    if result:
        print(f"Sent! Message ID: {result.data.id}")
    else:
        print(f"Error: {result.error}")

    await tm.disconnect()

asyncio.run(main())

🔑 The Result Pattern

Every method returns a Result object — never raises exceptions:

from telemaster import Result

result = await tm.send_message("me", "Hello!")

if result:                          # bool check
    msg = result.data               # The actual data
    print(msg.id, msg.text)
else:
    print(result.error)             # Human-readable error
    print(result.error_type)        # Error class name
    print(result.wait_seconds)      # For flood/slowmode errors

📋 Features

🔐 Authentication

await tm.connect()                         # Connect to servers
await tm.is_authorized()                   # Check session
await tm.send_code()                       # Send SMS code
await tm.verify_code("12345")              # Verify code
await tm.verify_2fa("password")            # 2FA password
await tm.logout()                          # Invalidate session
await tm.disconnect()                      # Close connection

💬 Messages

await tm.send_message(target, "Hello!")    # Send text
await tm.send_private("@user", "Hi!")      # Send private
await tm.edit_message(target, msg_id, "New text")
await tm.delete_messages(target, [1, 2, 3])
await tm.read_messages(target, limit=20)
await tm.read_private_messages("@user")
await tm.read_group_messages("@group")
await tm.read_channel_messages("@channel")
await tm.forward_message(from_chat, msg_id, to_chat)
await tm.get_dialogs(limit=50)
await tm.search_messages(target, "query")
await tm.mark_as_read(target)

📷 Media

await tm.send_photo(target, "photo.jpg", caption="📸")
await tm.send_video(target, "video.mp4", caption="🎬")
await tm.send_file(target, "doc.pdf", caption="📄")
await tm.send_voice(target, "voice.ogg")
await tm.send_album(target, ["img1.jpg", "img2.jpg"])
await tm.download_media(message)

👤 Profile

await tm.get_account_info()                # Full profile info
await tm.update_first_name("John")
await tm.update_last_name("Doe")
await tm.update_bio("Hello world!")
await tm.update_username("johndoe")
await tm.set_profile_photo("photo.jpg")
await tm.delete_profile_photo()
await tm.delete_all_profile_photos()
await tm.get_profile_photos("@user")

👥 Groups & Channels

await tm.join("@channel")
await tm.leave("@channel")
await tm.create_group("My Group", about="Description")
await tm.create_channel("My Channel", about="Description")
await tm.create_basic_group("Group", users=["@user1"])
await tm.update_group_title(target, "New Title")
await tm.update_group_about(target, "New Description")
await tm.update_group_photo(target, "photo.jpg")
await tm.update_group_username(target, "new_username")
await tm.get_participants(target, limit=100)
await tm.add_member(target, "@user")
await tm.kick_member(target, "@user")
await tm.get_invite_link(target)

📇 Contacts

await tm.add_contact("[phone]", "John", "Doe")
await tm.add_contact_by_username("@user", "John")
await tm.remove_contact(user_id)
await tm.get_contacts()
await tm.search_contacts("John")

🔒 Security (2FA)

await tm.enable_2fa("new_password", hint="my hint")
await tm.change_2fa("old_pass", "new_pass")
await tm.disable_2fa("current_password")
await tm.get_2fa_status()

📖 Stories

await tm.post_story("photo.jpg", caption="My story!")
await tm.delete_story(story_id)

❤️ Interactions

await tm.send_reaction(target, msg_id, "❤")
await tm.remove_reaction(target, msg_id)
await tm.send_custom_reaction(target, msg_id, emoji_id)
await tm.click_button(target, msg_id, button_text="Click me")
await tm.get_buttons(target, msg_id)

💾 Sessions

TeleMaster.list_sessions("./")        # Find .session files
TeleMaster.get_session_info("file.session")
TeleMaster.delete_session("file.session")

📂 Project Structure

telemaster/
├── telemaster/          # 📦 Core library
│   ├── __init__.py            # Public exports
│   ├── client.py              # TeleMaster facade (67 methods)
│   ├── models.py              # Result, AccountInfo, MessageInfo, etc.
│   ├── auth.py                # Step-by-step authentication
│   ├── messages.py            # Message operations
│   ├── media.py               # File uploads with captions
│   ├── profile.py             # Profile management
│   ├── groups.py              # Groups & channels
│   ├── contacts.py            # Contact management
│   ├── security.py            # 2FA management
│   ├── stories.py             # Stories
│   ├── interactions.py        # Reactions & buttons
│   ├── sessions.py            # Session file management
│   └── py.typed               # PEP 561 marker
├── examples/                  # 📝 Usage examples
│   ├── cli_login.py
│   ├── send_message.py
│   └── manage_profile.py
├── docs/                      # 📖 Documentation website
├── pyproject.toml             # Package configuration
├── requirements.txt
├── LICENSE                    # MIT
├── README.md
└── .gitignore

⚡ Performance

TeleMaster uses cryptg — a C-extension that accelerates Telethon's encryption by ~5x:

pip install telemaster[fast]

On Linux, uvloop is also included for faster async I/O.

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing
3. Commit changes: git commit -m "Add amazing feature"
4. Push: git push origin feature/amazing
5. Open a Pull Request

📄 License

MIT License — see LICENSE for details.

---

العربية

📡 مدير تيليجرام

مكتبة بايثون احترافية لإدارة حساب تيليجرام بالكامل — 67 دالة بدون أي print() أو input().

المميزات:

• 🔐 تسجيل دخول على خطوات (مناسب للبوتات والمواقع)
• 💬 إرسال/تعديل/حذف/قراءة رسائل
• 📷 رفع صور وفيديوهات وملفات مع كابشن
• 👤 إدارة الملف الشخصي (اسم، يوزر، بايو، صورة)
• 🔒 إدارة كلمة المرور الثنائية (2FA)
• 👥 إنشاء وإدارة مجموعات وقنوات
• 📖 نشر قصص
• ❤️ تفاعلات وضغط أزرار
• 💾 إدارة ملفات الجلسات

التثبيت:

pip install git+https://github.com/OmarMoh12/telemaster.git

مثال سريع:

from telemaster import TeleMaster

tm = TeleMaster(phone="+970...", api_id=123, api_hash="abc")
await tm.connect()
await tm.send_code()              # إرسال كود — بدون input!
await tm.verify_code("12345")     # تحقق من الكود
await tm.send_message("me", "مرحبا! 🚀")

---

Made with ❤️ by RoQ9