illest.py

Write bots for ILLEST the way you write them for discord. illest.py has discord.py's shape: the same classes, decorators, events and arguments. Code written for discord.py 2.x usually runs once its import is changed.

pip install illest.py

Python 3.10 or newer. The encryption engine, illest-crypto, comes with it as a compiled wheel for Windows and Linux (x86-64 and ARM64).

A bot in twenty lines

import illest
from illest import app_commands
from illest.ext import commands

bot = commands.Bot(command_prefix="!", intents=illest.Intents.default())


@bot.event
async def setup_hook():
    await bot.tree.sync()  # registers the slash commands below


@bot.event
async def on_ready():
    print(f"signed in as {bot.user}")


@bot.command()
async def ping(ctx: commands.Context):
    await ctx.reply("pong")


@bot.tree.command(description="Roll a die")
@app_commands.describe(sides="How many sides it has")
async def roll(interaction: illest.Interaction, sides: app_commands.Range[int, 2, 100] = 6):
    import random
    await interaction.response.send_message(f"{random.randint(1, sides)}")


bot.run("illb_...")

Make the bot and its token in ILLEST under Settings → Developers. Open the bot there, copy its invite link from Installation, and add it to a server you manage.

To run against your own server instead of chat.illest.world, set ILLEST_GATEWAY_URL (for example ws://localhost:8766/gateway) or pass server_url= to the client.

What you get

Where it differs, and why

ILLEST is end-to-end encrypted: the server stores ciphertext and holds no keys. Most differences follow from that, and each is deliberate. The full list, with what to write instead, is in the documentation.

• A bot is a device. Its token enrols a device the first time it runs; the device key is kept under ~/.illest/bots/. Keep that folder: losing it is losing the device.
• A bot reads from when it joined. channel.history() and fetch_message() return the messages this bot holds, from when it was let into the channel's group. There is nothing older to fetch: the server cannot read it either.
• Commands, presses, picks and forms travel sealed, as messages in the conversation that only the bot opens. The server never sees which command was used or with what.
• ephemeral=True is a rendering rule. Every honest client shows the message to its one reader only; inside an encrypted group nothing stronger exists, and the library does not pretend otherwise.
• Who sent it is what their device proves. message.author_verified and interaction.sender_verified say whether the sender's own device vouched for the account. Authorise nothing on a sender that is not verified.
• Permissions have discord's names and ILLEST's bits. illest.Permissions(ban_members=True).value is the number to use in an ILLEST invite link; a number from a discord permissions calculator means something else here.
• Intents filter, scopes grant. An intent decides which events reach your handlers; the bot's scopes (set by its owner under Developers → Bot) decide what it may read and do. Intents.default() includes members and message content.
• No voice. A bot cannot join a call: calls are encrypted from each person's device. VoiceChannel.connect() raises.
• No sharding. One connection serves any number of servers; AutoShardedBot is Bot.
• tree.sync() takes effect at once, global commands included.

Examples

examples/ holds runnable bots: basic (events and prefix commands), slash commands (groups, choices, autocomplete, context menus), views (buttons, select menus, a persistent view, a modal), moderation and tasks and cogs. Each reads its token from ILLEST_TOKEN.

Documentation

The API reference is built with MkDocs: pip install "illest.py[docs]", then mkdocs serve in this folder.

Licence

MIT. illest-crypto, the compiled encryption engine it installs, is free to use and redistribute unmodified; see its own licence.