tflows.py

tflows.py is a lightweight automation and Discord bot framework built around a scripting engine. Instead of writing Python event handlers for every action, you define bot behavior as simple text scripts:

from tflows import FlowBot

bot = FlowBot(prefix="!")

bot.command(
    name="ping",
    code="""
    // Send a reply with the current latency
    reply Pong! $ping
    """,
)

bot.run("YOUR_BOT_TOKEN")

It is designed for fast bot development, easy customization, and extensible command logic — while staying fully compatible with discord.py so you can mix scripts and regular commands.

Features

• Script-based command system — write bot logic as plain text
• Built-in $variable templates ($user, $server, $args, $ping, ...)
• Command arguments: $args, $arg(0), $argcount
• Rich embeds, both as blocks and single-line commands
• Built-in help command, aliases, and command descriptions
• Comment support in scripts (//, #, --)
• Async Discord integration using discord.py 2.x
• Extensible registry: add your own functions and variables
• Mixing with regular discord.py commands, cogs, and listeners

Installation

pip install tflows

Requires Python 3.10+.

Quick Start

from tflows import FlowBot

bot = FlowBot(prefix="!")

bot.command(
    name="hello",
    code="""
    reply Hello $user(display)!
    """,
)

bot.run("YOUR_BOT_TOKEN")

Command registration

FlowBot.command(name, code, description="", aliases=()) registers a script command:

bot.command(
    name="greet",
    code="reply Hello $args",
    description="Greets the given name.",
    aliases=("hi", "hey"),
)

Both !greet, !hi and !hey now trigger the same script.

The built-in help command

By default !help lists every script command, and !help <command> shows its description, aliases, usage, and source script. Disable it with FlowBot(prefix="!", help_command=False).

Variables

Variables are replaced anywhere in a script, including inside function arguments. Usage is $name or $name(option).

Unknown variables are left untouched so typos never silently corrupt output.

Example:

!greet world

reply Hello $args            # -> Hello world
reply First: $arg(0)         # -> First: world
reply Count: $argcount       # -> Count: 1

Functions

Every line of a script calls one function:

<function-name> <arguments...>

Core functions

Embeds

The block form is best for rich, multi-line embeds:

embed
$title[Server Stats]
$desc[
Members: $membercount
Uptime: $uptime(full)
]
$footer[Requested by $user(display)]
$color[blurple]
$thumbnail[$bot(avatar)]
endembed

Supported keys: $title, $desc, $footer, $color (hex or named), $thumbnail, $image, $author, $timestamp. Named colors include white, black, red, green, blue, yellow, orange, purple, pink, grey, blurple, gold, teal, cyan, and brown.

A single-line form using the embed function is also available, with keys separated by | and fields via field: Name;Value;inline:

embed $embed<title: $user(display) | desc: Level 42 | color: green | field: Role;Admin;true>

Comments

Lines starting with //, #, or -- are ignored.

Mixing with discord.py

Because FlowBot subclasses discord.ext.commands.Bot, everything discord.py offers keeps working: cogs, listeners, @bot.event, app commands, etc. When a message matches the prefix but not a script command, it is passed through to discord.py's command processor automatically.

import discord
from discord.ext import commands
from tflows import FlowBot

class Moderation(commands.Cog):
    @commands.command()
    async def purge(self, ctx, limit: int):
        await ctx.channel.purge(limit=limit)

bot = FlowBot(prefix="!")
bot.command(name="hello", code="reply Hi $user(display)!")
bot.add_cog(Moderation(bot))
bot.run("YOUR_BOT_TOKEN")

Custom functions and variables

Functions are callables fn(ctx, args) and variables are callables var(ctx, args) that return a string (or an awaitable). Register them on the shared registry:

from tflows import FlowBot
from tflows.registry import registry

@registry.register("shrug")
async def shrug(ctx, args):
    await ctx.channel.send("¯\\_(ツ)_/¯")

@registry.register_var("uptime_hours")
def uptime_hours(ctx, args):
    return str(bot_uptime_seconds() // 3600)

bot = FlowBot(prefix="!")

Alternatively, create an isolated bot with its own registry: FlowBot(prefix="!", registry=FunctionRegistry()).

FlowBot options

Examples

See the examples/ directory:

• basic_bot.py — minimal bot
• variables.py — variable showcase
• embeds.py — block and single-line embeds
• automation.py — wait, react, delete, clear
• mixing.py — scripts alongside discord.py cogs

Run any example after installing the package:

python examples/basic_bot.py

License

Apache License 2.0 — see the License file. Attribution to the original author is required when redistributing or embedding the software; see NOTICE.