Forem: idk

Writing a 0-dependency Telegram SDK with auto-generated types

idk — Wed, 31 Dec 2025 09:03:57 +0000

Why I built a zero-dependency Telegram SDK from scratch

Let's be honest: most Telegram Bot SDKs are either too heavy or have inconsistent type definitions. I wanted something lean, fast, and 100% type-safe.

That's why I created Surfgram.

The "Zero" Philosophy

The main goal was to have 0 dependencies. No axios, no node-fetch, just native Node.js https.

Lightweight: Tiny bundle size and fast installation.
Secure: Fewer dependencies means a smaller attack surface.

Auto-generated Types

Instead of manually maintaining interfaces (which is a nightmare), I built a generator that scrapes the official Telegram Bot API documentation.

Always up-to-date: If the API changes, I just rerun the generator.
Strict Safety: I focused on eliminating undefined errors by using strict null checks and proper type guards for API responses.

How it looks

import { Bot, Message } from 'surfgram';

const bot = new Bot('TOKEN');

bot.onMessage('/start', (message: Message) => {
  message.sendMessage({ text: 'hi there' });
});

bot.startPolling();

Give it a try!

The project is fully open-source. I’m looking for feedback on the architecture and type generation logic.

GitHub: https://github.com/surfgram/surfgram

If you like the "no-bloat" approach, a ⭐ would be much appreciated!

Quillion - Python Web Framework for Backend Developers

idk — Fri, 10 Oct 2025 06:53:53 +0000

Tired of feeling like HTML, CSS, and JavaScript are from another planet? Want to build web apps using just Python?

What My Project Does

Quillion is a fast, easy-to-use Python web framework that lets you create interactive web applications without writing frontend code. It uses a WebAssembly (WASM) core compiled from Rust for DOM rendering, while providing a clean Python API for business logic. The framework handles browser communication through WebSockets, making real-time features easy to implement.

Target Audience

This framework is specifically designed for:

Backend Developers who want to build web interfaces without learning HTML/CSS/JavaScript
Data Scientists needing to create interactive dashboards and tools
Python Developers who found Streamlit or Dash too limiting

Comparison with Alternatives

vs. Streamlit/Dash: Better performance through WASM architecture with more customization options
vs. Flask/Django: Eliminates need for HTML templates and JavaScript - pure Python only
vs. PyScript: Higher-level framework with built-in rendering and real-time communication

Quick Start

q new myapp
cd myapp  
q run

GitHub: https://github.com/base-of-base/quillion

PySupercell Core Guide: Building Your Own Supercell Game Server

idk — Tue, 01 Jul 2025 09:53:23 +0000

So you've decided to create your own server for a Supercell game and Python caught your eye. Among countless questionable projects, you stumbled upon PySupercell Core. What now?

Why PySupercell Core?

Supercell games (Clash of Clans, Brawl Stars etc.) share similar architecture—they’re built on a core (server foundation). PySupercell Core (PSC) is a fresh Python core that:

Implements Supercell’s base server architecture
Easily adapts to any SC game
But isn’t a ready-made server—you’ll write the logic yourself

Most other Python servers/cores are slow and outdated. PSC is fast and user-friendly

Installing PSC

Clone the repo:

git clone https://github.com/REtard-1337/pysupercell-core
cd pysupercell-core

Install dependencies:
```
pip install -r requirements.txt
```

Picking Ur Game

Navigate to logic/messages/ and find logic_magic_message_factory.py
Here magic is Clash of Clans' codename. Swap it for your game:

Game	Codename
Clash of Clans	`magic`
Brawl Stars	`laser`
Clash Royale	`scroll`
Hay Day	`soil`
Boom Beach	`reef`
Squad Busters	`squad`

Server Configuration

Open config.toml and set game parameters. Example for Brawl Stars v52.13.77:

[game]
major_version = 52
build = 13
content_version = 77
environment = "int"

Now your server seems ready... but when you launch it...

— Wait, why is the client stuck at "Connecting to server..."? That means PSC is broken!!!
— Nope, it works! PSC is a core, not a full server. You must implement all packets yourself

Writing Messages

Let’s take LoginMessage as an example.

Create logic/messages/auth/login_message.py

Code the packet:

from titan.message.piranha_message import PiranhaMessage
from titan.math.logic_long import LogicLong

class LoginMessage(PiranhaMessage):
    def __init__(self):
        super().__init__()
        self.account_id = LogicLong() 
        self.pass_token = ""
        self.major_version = 0

    def decode(self):
        super().decode()
        self.account_id = self.stream.read_long()
        self.pass_token = self.stream.read_string() 
        self.major_version = self.stream.read_int()
        # ...

    def get_message_type(self) -> int:
        return 10101

But this seems complicated, so let’s break it down.

First, imports:

from titan.message.piranha_message import PiranhaMessage
from titan.math.logic_long import LogicLong

Then create LoginMessage class—it must inherit from PiranhaMessage:

class LoginMessage(PiranhaMessage):
    ...

PiranhaMessage is the base class for all packets. It provides stream (like Classic-Brawl’s Reader/Writer)

Initialize fields in the constructor:

    def __init__(self):
        super().__init__()
        self.account_id = LogicLong()
        self.pass_token = ""
        self.major_version = 0

Now the decode:

    def decode(self):
        super().decode()
        self.account_id = self.stream.read_long()
        self.pass_token = self.stream.read_string()
        self.major_version = self.stream.read_int()

And message type:

    def get_message_type(self) -> int:
        return 10101

Fascinating! But what about server responses?
Create login_ok_message.py next to login_message.py:

from titan.math.logic_long import LogicLong
from titan.message.piranha_message import PiranhaMessage  

class LoginOkMessage(PiranhaMessage):  
    def __init__(self) -> None:  
        super().__init__()  
        self.account_id = LogicLong()  
        self.home_id = LogicLong()  
        self.pass_token = ""  
        ...  

    def encode(self):
        super().encode()
        self.stream.write_long(self.account_id)
        self.stream.write_long(self.home_id)
        self.stream.write_string(self.pass_token)
        # ...

    def get_message_type(self) -> int:
        return 20104

Not much to explain—since this is a server packet, we implement encode() using fields from the constructor

Handling Packets

Notice no process(), execute(), or handle() in message classes? Supercell uses a different approach—all packets are handled via MessageManager.receive_message
Example for LoginMessage:

# server/protocol/message_manager.py
from logic.messages.auth import LoginMessage, LoginOkMessage
from titan.math import LogicLong

class MessageManager:  
    def __init__(self, connection):
        self.connection = connection

    async def receive_message(self, message):
        match message.get_message_type():
            case 10101:
                await self.on_login(message)
            case _:
                ...   # other stuff

    async def on_login(self, message: LoginMessage):       
        response = LoginOkMessage()
        response.account_id = ...
        response.pass_token = ...
        # ...
        await self.connection.send_message(response)

What’s happening?
First, message_manager.py isn’t empty—it has base structure (see screenshot below)

We added a case to handle login_message when its ID arrives:

    async def receive_message(self, message):
        ...
            case 10101:
                await self.on_login(message)  # await 'cause async

Now observe on_login:

    async def on_login(self, message: LoginMessage):
        response = LoginOkMessage()
        response.account_id = ...
        response.pass_token = ...
        # ...
        await self.connection.send_message(response)

We pass the incoming packet:

    async def on_login(self, message: LoginMessage):

Create a response packet:

        response = LoginOkMessage()

Fill its fields:

        response.account_id = ...
        response.pass_token = ...

Then send it back:

        await self.connection.send_message(response)

Got questions? DM:

t.me/TheBladewise1337
t.me/user_with_username

Гайд на PySupercell Core: Создаём свой сервер для игр Supercell

idk — Tue, 01 Jul 2025 09:25:23 +0000

Итак, вы приняли решение создать свой собственный сервер для какой-нибудь Supercell'овской игры, и ваш взгляд пал на то, чтобы использовать Python для разработки. Среди множества проектов сомнительного качества вы наткнулись на PySupercell Core. А что дальше?

Почему PySupercell Core?

Игры Supercell (Clash of Clans, Brawl Stars и т. д.) имеют схожую архитектуру - это объясняется тем, что они сделаны на основе ядра (некой основы для сервера). PySupercell Core (далее PSC) — это новое Python-ядро, которое:

Реализует базовую архитектуру сервера как у Supercell
Легко адаптируется под любую игру SC
Но не является готовым сервером — вам предстоит дописать логику самостоятельно

Большинство других питонических серверов / ядер медленные и устаревшие. PSC же быстрый и удобный в использовании

Ставим PSC

Клонируем репозиторий:

git clone https://github.com/REtard-1337/pysupercell-core
cd pysupercell-core

Ставим зависимости:
```
pip install -r requirements.txt
```

Выбираем игру

В папке logic/messages/ ищем файл logic_magic_message_factory.py. Здесь magic — кодовое имя Clash of Clans. Меняем его на нужное нам:

Игра	Код-нейм
Clash of Clans	`magic`
Brawl Stars	`laser`
Clash Royale	`scroll`
Hay Day	`soil`
Boom Beach	`reef`
Squad Busters	`squad`

Конфигурация сервера

Открываем config.toml и задаем параметры игры. Например, для Brawl Stars версии 52.13.77:

[game]
major_version = 52
build = 13
content_version = 77
environment = "int"

И вот теперь, когда сервер настроен и вроде бы как готов к работе, вы запускаете его, но...

— Но падажи, почему-то на клиенте происходит бесконечное "подключение к серверу" — это значит, что PSC не работает!!!

— Нет, всё работает, просто PSC — это ядро, а не полноценный сервер. Все пакеты необходимо реализовать самостоятельно

Пишем месседжи

В качестве примера я возьму LoginMessage.

Создаём файл logic/messages/auth/login_message.py.

Пишем пакет:

from titan.message.piranha_message import PiranhaMessage
from titan.math.logic_long import LogicLong

class LoginMessage(PiranhaMessage):
    def __init__(self):
        super().__init__()
        self.account_id = LogicLong()
        self.pass_token = ""
        self.major_version = 0

    def decode(self):
        super().decode()
        self.account_id = self.stream.read_long()
        self.pass_token = self.stream.read_string()
        self.major_version = self.stream.read_int()
        # ...

    def get_message_type(self) -> int:
        return 10101

Но всё это какт сложно, потому давай разберём.
Сначала мы импортируем зависимости:

from titan.message.piranha_message import PiranhaMessage
from titan.math.logic_long import LogicLong

Далее создаём класс LoginMessage — он обязательно должен быть наследником от PiranhaMessage:

class LoginMessage(PiranhaMessage):
    ...

PiranhaMessage — это базовый класс для всех пакетов, который предоставляет доступ к stream — аналогу Reader/Writer из Classic-Brawl

Затем мы создаём конструктор класса и определяем в нём поля:

    def __init__(self):
        super().__init__()
        self.account_id = LogicLong()
        self.pass_token = ""
        self.major_version = 0

Теперь создаём декод:

    def decode(self):
        super().decode()
        self.account_id = self.stream.read_long()
        self.pass_token = self.stream.read_string()
        self.major_version = self.stream.read_int()

И теперь пишем get_message_type — он вернёт ID месседжа:

    def get_message_type(self) -> int:
        return 10101

И это всё, конечно, невероятно увлекательно, но как насчёт серверного пакета?
Рядом с login_message.py создаём новый файлик — login_ok_message.py:

from titan.math.logic_long import LogicLong
from titan.message.piranha_message import PiranhaMessage


class LoginOkMessage(PiranhaMessage):
    def __init__(self) -> None:
        super().__init__()
        self.account_id = LogicLong()
        self.home_id = LogicLong()
        self.pass_token = ""
        ...

    def encode(self):
        super().encode()
        self.stream.write_long(self.account_id)
        self.stream.write_long(self.home_id)
        self.stream.write_string(self.pass_token)
        # и чтот ещё

    def get_message_type(self) -> int:
        return 20104

Здесь нам разбирать особо нечего — скажу только, что раз это серверный пакет, то здесь должна быть реализована функция encode(), в которой мы используем созданные нами в конструкторе поля

Обработка пакетов

Уже заметили, что в классах месседжей нет ни process(), ни execute(), ни handle()? Как же так? Дело в том, что Supercell использует немного другой метод обработки пакетов — все пакеты обрабатываются через MessageManager.receive_message
Вот так, например, будет выглядеть обработка LoginMessage:

# server/protocol/message_manager.py
from logic.messages.auth import LoginMessage, LoginOkMessage
from titan.math import LogicLong

class MessageManager:
    def __init__(self, connection):
        self.connection = connection

    async def receive_message(self, message):
        match message.get_message_type():
            case 10101:
                await self.on_login(message)
            case _:
                ...   # чтот другое

    async def on_login(self, message: LoginMessage):        
        response = LoginOkMessage()
        response.account_id = ...
        response.pass_token = ...
        # ...
        await self.connection.send_message(response)

Что здесь происходит?
Начну с того, что изначально message_manager.py — это не пустой файлик. В нём уже есть базовая структура (см. скриншот ниже).

Мы просто добавили нужный кейс (назовём его просто условием), чтобы вызвать обработчик login message’а, если придёт пакет с нужным ID:

    async def receive_message(self, message):
        ...
            case 10101:
                await self.on_login(message) # Поскольку on_login - асинхронная функция, мы вызываем её с ключевым словом await.

А теперь посмотрим на сам on_login:

    async def on_login(self, message: LoginMessage):
        response = LoginOkMessage()
        response.account_id = ...
        response.pass_token = ...
        # ...
        await self.connection.send_message(response)

В аргументы функции передаём пакет, который обрабатываем:

    async def on_login(self, message: LoginMessage):

Потом создаём инстанс пакета, который хотим отправить клиенту:

        response = LoginOkMessage()

И заполняем поля — чтобы при енкоде сообщения туда вошли данные, нужные нам:

        response.account_id = ...
        response.pass_token = ...

И потом шлём назад нужный месседж клиенту:

await self.connection.send_message(response)