Tflows

A FlowBot-based scripting system that lets you define Discord bot behavior entirely through a concise, expressive DSL — no callback hell, no boilerplate.

What is Tflows?

Tflows is a lightweight Python library built on top of discord.py that replaces the traditional event-callback model with a compact domain-specific language (DSL). Instead of writing Python handler functions for every command, you pass a plain-text script to bot.command() and Tflows handles parsing, variable resolution, and Discord output at runtime.

It is designed for developers who want fast iteration — define a new command in seconds, iterate on its output without restarting the bot, and keep all logic in one readable place.

Key Features

Who is it for?

Tflows is for Discord bot developers who want to ship command logic quickly — whether you're prototyping a bot, building a community tool, or just tired of writing the same boilerplate over and over. It's especially useful when you want non-technical collaborators to edit bot behavior without touching Python.

Installation #

Install Tflows from PyPI using pip. No additional dependencies need to be manually installed — discord.py is pulled in automatically.

$ pip install tflows

Verify the installation

import tflows
print(tflows.__version__)

Links

• PyPI Package
• GitHub Repository

Quick Start #

Below is a minimal working bot. It registers a single !test command that replies with a message showing current latency.

from tflows import FlowBot

bot = FlowBot(prefix="!")

bot.command(
  name="test",
  code="""
send Hello World $ping
"""
)

bot.run("YOUR_BOT_TOKEN")

Trigger it in Discord with !test. The bot replies: Hello World 42ms (latency will vary).

A richer example with an embed

embed
$title[Server Status]
$desc[
Latency: $pingms
Server: $server
Members: $membercount
Time: $time(24h)
]

Architecture #

Tflows is a thin orchestration layer over discord.py. It replaces the event-callback model with a parse-and-execute pipeline that runs inside a command's context.

Components

FlowBot #

FlowBot is the main entry point. It subclasses discord.py's commands.Bot and adds DSL-aware command registration.

from tflows import FlowBot

bot = FlowBot(prefix="!")

bot.command(
    name="greet",
    code="""
send Hi $id(user)!
"""
)

bot.run("TOKEN")

Constructor

bot.command() Parameters

Execution lifecycle

DSL Commands #

The DSL supports a small set of keywords that control output mode and content. Every script is evaluated line-by-line from top to bottom.

send

Sends a plain text message to the channel. Everything after the keyword is the message content.

send Hello World $ping

embed

Switches the output mode to embed. After this keyword, subsequent $title and $desc directives build up a discord.Embed object. No arguments required.

Embed directives

Available variables in directives

Embed DSL #

Embeds are Discord's rich message format — they support titles, descriptions, colors, and more. Tflows' embed mode lets you build them declaratively with zero Python embed object management.

embed
$title[Hello from Tflows]
$desc[
Ping: $pingms
Server: $server
Members: $membercount
]

How it works

Supported fields

Variables #

Variables are special tokens embedded in your DSL scripts, prefixed with $. They are resolved at runtime against the live Discord command context and replaced with their current values before output is generated.

Variables come in two flavors: static (no arguments, always produce the same type of value) and function (accept an optional mode flag in parentheses).

send Pong! $pingms

embed
$title[Uptime Variants]

$desc[
Default: $uptime
Full: $uptime(full)
Short: $uptime(short)
Clock: $uptime(clock)
Seconds: $uptime(seconds)
Custom: $uptime(d, h, m, s)
]

$log(CHANNEL_ID){User executed a command}

$log(123456789012345678){User executed !ping command}

$log(123456789012345678){$user used a command at $time}

$log(987654321098765432){$user was muted by <@$id> for spam}

$image
$image(user)
$image(mention)
$image(act)

$server
$server(name)
$server(boost)
$server(boostlvl)

$membercount
$membercount(all)
$membercount(user)
$membercount(bots)

$time()
$time(12h)
$time(24h)
$time(nodate)
$time(notime)
$time(nodate;24h)

$id
$id(user)
$id(mention)
$id(act)

Execution Flow #

Understanding exactly what happens when a user invokes a Tflows command helps you write more predictable scripts and debug issues faster.

Best Practices #

Following these patterns will make your Tflows scripts more readable, maintainable, and robust.

Common Mistakes #

These are the most frequent errors new Tflows users encounter, and how to fix them.

Forgetting the embed keyword

Using $title or $desc without first writing embed on its own line will not produce an embed — the directives will either error or be ignored.

# ❌ embed mode never activated
$title[My Title]
$desc[My description]

# ✅ embed mode activated first
embed
$title[My Title]
$desc[My description]

Wrong bracket syntax for directives

Directive values must use square brackets […]. Parentheses and curly braces will not be parsed correctly.

$title(Wrong brackets)   # ❌ parentheses
$desc{Also wrong}       # ❌ curly braces

$title[Correct]          # ✅ square brackets

Incorrect mode flag names

Mode flags are case-sensitive and must match the documented identifiers exactly. Check the Variables reference for the exact spelling.

$membercount(users)   # ❌ should be "user"
$image(Mention)       # ❌ should be lowercase "mention"

Using mention without an actual mention

$id(mention) and $image(mention) fall back to the author if no mention is present — but the fallback exists to prevent crashes, not to produce the expected output. If you need flexible mention handling, use act mode instead and document the expected usage.

Examples #

Server info command

bot.command(
    name="server",
    code="""
embed
$title[$server Info]
$desc[
Members: $membercount
Humans: $membercount(user)
Bots: $membercount(bots)
Boost Level: $server(boostlvl)
Boosts: $server(boost)
]
"""
)

Ping + time status command

bot.command(
    name="status",
    code="""
embed
$title[Bot Status]
$desc[
Latency: $pingms
Time: $time(nodate;24h)
Date: $time(notime)
]
"""
)

Avatar + ID lookup

bot.command(
    name="whois",
    code="""
embed
$title[User Info]
$desc[
ID: $id(act)
Avatar: $image(act)
]
"""
)

Simple plain-text output

send Pong! $pingms — $time(nodate;24h)

Complete time system demo

bot.command(
    name="time",
    code="""
embed
$title[Tflows Time Demo]
$desc[
Default: $time()
No Date: $time(nodate)
No Time: $time(notime)
24h: $time(24h)
12h: $time(12h)
24h No Date: $time(nodate;24h)
]
"""
)