illest 2.2.0__tar.gz

illest-2.2.0/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 VERAKS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+The ILLEST name and marks are trademarks of VERAKS and are not licensed by
+this notice.

illest-2.2.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.4
+Name: illest
+Version: 2.2.0
+Summary: The Python library for ILLEST: bots with commands, slash commands and buttons, end-to-end encrypted, and Rich Presence.
+Author: VERAKS
+License-Expression: MIT
+Project-URL: Homepage, https://illest.world
+Project-URL: Documentation, https://developer.illest.world/docs/introduction
+Project-URL: Changelog, https://developer.illest.world/docs/changelog
+Keywords: illest,illest.py,bot,chat bot,rich presence,e2ee,mls
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets>=12.0
+Requires-Dist: cryptography>=42.0
+Requires-Dist: illest-crypto<3,>=2.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
+Dynamic: license-file
+
+# illest.py
+
+The Python library for [ILLEST](https://illest.world): bots with prefix commands, slash commands, buttons, menus and forms, all
+end-to-end encrypted, and Rich Presence for games and tools that show what their player is doing.
+
+```bash
+pip install illest
+```
+
+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
+
+```python
+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
+
+- **The client:** `Client`, `commands.Bot`, `Intents`, `@bot.event`, `wait_for`, `setup_hook`.
+- **Prefix commands** (`ext.commands`): commands, groups, cogs, extensions, checks, cooldowns, converters, `Greedy`, `Range`,
+  flags, the help command, and hybrid commands that are slash commands too.
+- **Slash commands** (`app_commands`): `CommandTree`, `@tree.command`, `Group`, `describe`, `choices`, `autocomplete`, `rename`,
+  `Range`, `Transform`, context menus, `default_permissions`, `guild_only`, checks and cooldowns, `tree.sync(guild=...)`.
+- **Interactions:** `response.send_message`, `defer` (with "thinking"), `edit_message`, `send_modal`, `followup`,
+  `original_response`.
+- **Components** (`ui`): `View`, `Button`, `Select`, `UserSelect`, `RoleSelect`, `ChannelSelect`, `MentionableSelect`, `Modal`,
+  `TextInput`, and persistent views (`timeout=None` and `custom_id`, `bot.add_view`).
+- **Background tasks** (`ext.tasks.loop`) with `before_loop`, `after_loop`, `change_interval` and times of day.
+- **Messages:** `Embed`, `File`, `AllowedMentions`, `Colour`, `Permissions`, `PermissionOverwrite`,
+  `utils.get/find/format_dt/oauth_url`.
+- **Moderation:** `Member.ban/kick/timeout/add_roles/remove_roles/edit`, `Guild.unban/bans/audit_logs`, `TextChannel.purge`,
+  and creating and editing channels, categories, roles and invites, behind the bot's scopes and the server's roles.
+- **Rich Presence** (`illest.rpc`): `Presence` and `AsyncPresence` tell the person's friends what they are doing in your game or
+  tool, through the ILLEST desktop app.
+- Rate limits, reconnects and `run()`'s logging set-up, handled for you.
+
+## What end-to-end encryption changes
+
+ILLEST is end-to-end encrypted: the server stores ciphertext and holds no keys. A bot is built for that, and each of these is
+deliberate. Moving a bot from discord.py? [The migration guide](docs/differences.md) has the full list, with what to write instead.
+
+- **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 are ILLEST's bits.** `illest.Permissions(ban_members=True).value` is the number to use in an ILLEST invite
+  link; build it with `illest.Permissions` or the bot's Installation page rather than copying a number from elsewhere.
+- **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](examples/basic_bot.py) (events and prefix commands), [slash commands](examples/slash_commands.py)
+(groups, choices, autocomplete, context menus), [views](examples/views.py) (buttons, select menus, a persistent view, a modal),
+[moderation](examples/moderation.py), [tasks and cogs](examples/tasks_and_cogs.py), and [a test bot](examples/test_bot.py) that
+touches every part once. Each reads its token from `ILLEST_TOKEN`. [Rich Presence](examples/rich_presence.py) reads an application
+id from `ILLEST_APP_ID` instead.
+
+## Documentation
+
+The documentation is at [developer.illest.world](https://developer.illest.world/docs/introduction). To build it here with
+MkDocs: `pip install "illest[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.

illest-2.2.0/README.md

@@ -0,0 +1,112 @@
+# illest.py
+
+The Python library for [ILLEST](https://illest.world): bots with prefix commands, slash commands, buttons, menus and forms, all
+end-to-end encrypted, and Rich Presence for games and tools that show what their player is doing.
+
+```bash
+pip install illest
+```
+
+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
+
+```python
+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
+
+- **The client:** `Client`, `commands.Bot`, `Intents`, `@bot.event`, `wait_for`, `setup_hook`.
+- **Prefix commands** (`ext.commands`): commands, groups, cogs, extensions, checks, cooldowns, converters, `Greedy`, `Range`,
+  flags, the help command, and hybrid commands that are slash commands too.
+- **Slash commands** (`app_commands`): `CommandTree`, `@tree.command`, `Group`, `describe`, `choices`, `autocomplete`, `rename`,
+  `Range`, `Transform`, context menus, `default_permissions`, `guild_only`, checks and cooldowns, `tree.sync(guild=...)`.
+- **Interactions:** `response.send_message`, `defer` (with "thinking"), `edit_message`, `send_modal`, `followup`,
+  `original_response`.
+- **Components** (`ui`): `View`, `Button`, `Select`, `UserSelect`, `RoleSelect`, `ChannelSelect`, `MentionableSelect`, `Modal`,
+  `TextInput`, and persistent views (`timeout=None` and `custom_id`, `bot.add_view`).
+- **Background tasks** (`ext.tasks.loop`) with `before_loop`, `after_loop`, `change_interval` and times of day.
+- **Messages:** `Embed`, `File`, `AllowedMentions`, `Colour`, `Permissions`, `PermissionOverwrite`,
+  `utils.get/find/format_dt/oauth_url`.
+- **Moderation:** `Member.ban/kick/timeout/add_roles/remove_roles/edit`, `Guild.unban/bans/audit_logs`, `TextChannel.purge`,
+  and creating and editing channels, categories, roles and invites, behind the bot's scopes and the server's roles.
+- **Rich Presence** (`illest.rpc`): `Presence` and `AsyncPresence` tell the person's friends what they are doing in your game or
+  tool, through the ILLEST desktop app.
+- Rate limits, reconnects and `run()`'s logging set-up, handled for you.
+
+## What end-to-end encryption changes
+
+ILLEST is end-to-end encrypted: the server stores ciphertext and holds no keys. A bot is built for that, and each of these is
+deliberate. Moving a bot from discord.py? [The migration guide](docs/differences.md) has the full list, with what to write instead.
+
+- **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 are ILLEST's bits.** `illest.Permissions(ban_members=True).value` is the number to use in an ILLEST invite
+  link; build it with `illest.Permissions` or the bot's Installation page rather than copying a number from elsewhere.
+- **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](examples/basic_bot.py) (events and prefix commands), [slash commands](examples/slash_commands.py)
+(groups, choices, autocomplete, context menus), [views](examples/views.py) (buttons, select menus, a persistent view, a modal),
+[moderation](examples/moderation.py), [tasks and cogs](examples/tasks_and_cogs.py), and [a test bot](examples/test_bot.py) that
+touches every part once. Each reads its token from `ILLEST_TOKEN`. [Rich Presence](examples/rich_presence.py) reads an application
+id from `ILLEST_APP_ID` instead.
+
+## Documentation
+
+The documentation is at [developer.illest.world](https://developer.illest.world/docs/introduction). To build it here with
+MkDocs: `pip install "illest[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.

illest-2.2.0/illest/__init__.py

@@ -0,0 +1,169 @@
+"""illest: the Python library for ILLEST, for bots and Rich Presence.
+
+    from illest.ext import commands
+
+    bot = commands.Bot(command_prefix="/", token="illb_...")
+
+    @bot.command(name="ping")
+    async def ping(ctx):
+        await ctx.reply("pong")
+
+    bot.run()
+
+## The everyday names
+
+`Client`, `Intents`, `Embed`, `ButtonStyle`, `ui.Button`, `ext.commands.Bot`,
+`Context`, `@bot.event`, `@bot.command()`, `ctx.send/reply`,
+`message.reply`, `embed=`, `view=`, `ephemeral=True`. Moving a bot written
+for another library: the migration guide on the developer site.
+
+## What is different, and why
+
+This network is end-to-end encrypted. The server stores ciphertext and holds
+no keys, so:
+
+* **A bot is a real device.** Its token ENROLs it; its device key (generated
+  once, kept under `~/.illest/bots/`) is what proves it at sign-in. Losing
+  that file is losing the device, which is losing history only it held.
+* **A bot joins groups like a member.** Invite it to your server; somebody's
+  client lets it into each channel's group. "Invited" and "able to read" are
+  different moments: usually seconds apart while it is online.
+* **A bot that was stopped catches up by itself.** While it is away its groups move on (members join and leave, keys are
+  replaced). When it starts, and when it signs in again after the server no longer held its session, it brings every group it
+  holds up to the server's epoch, a channel at a time and unhurried, before it handles anything; a channel it cannot catch up is
+  logged by its id and the rest go on. A message that arrives sealed at an epoch ahead of the bot's makes it catch that channel up
+  once and try the message again; if that fails too the message is dropped, and logged without its content. Messages sent while the
+  bot was away are not fetched: it reads what arrives while it is connected.
+* **Who sent it is what their device proves, not what the server says.** Every message and every button press carries
+  `author_id` (`sender_id` on an `Interaction`) from the server, and the library checks it against the sender's leaf in the group:
+  a frame that names an account other than the one the leaf proves is dropped. A sender whose leaf proves no account (a bot, or
+  a device with no certificate) is still delivered, but `Message.author_verified` (`Interaction.sender_verified`,
+  `Context.author_verified`) is False, and `author_id` is then only the server's word: do not authorise anything by it.
+* **An account is the key it first showed.** A certificate proves that some account key vouched for a device, and anybody can
+  make a key. So the library remembers the first key each account shows (in `pins.json`, in its state folder) and holds the
+  account to it: an invitation written by a device under another key is turned down, a member the server lists who lets
+  themselves in under another key is not taken in, and a message from a device under another key is delivered with
+  `author_verified` False and `author_key_changed` True. The change is said once in the log and to `on_key_change(user_id)`.
+  It happens when a person sets their account up again, and when somebody else writes as them: ask them another way, then call
+  `client.accept_key_change(user_id)`. An invitation is opened only from a device the channel lists.
+* **A button answers only to who could see it.** `@bot.on_button` runs only for a press on a message this bot sent, naming a
+  button that message carried and left enabled, from somebody who could see it (and, for a message meant for one reader, who is
+  proven to be that reader). The library remembers its buttons in its state folder, so they survive a restart.
+* **Ephemeral is a rendering rule.** `ephemeral=True` marks a message
+  visible only to its one reader on every client that honours the rule. It
+  is not cryptography against other members of the group (no such thing
+  exists inside an MLS group), and this library says so rather than implying
+  otherwise.
+"""
+
+from ._version import __version__
+from . import abc, app_commands, ui, utils
+from .activity import Activity, BaseActivity, CustomActivity, Game, Streaming
+from .attachment import AttachmentError
+from .client import Client
+from .colour import Color, Colour
+from .content import Button, ContentError
+from .embeds import Embed
+from .enums import *  # noqa: F401,F403
+from .enums import __all__ as _enums
+from .errors import (
+    AuthFailed,
+    BadRequest,
+    BotForbidden,
+    ClientException,
+    ConnectionClosed,
+    DiscordException,
+    DiscordServerError,
+    Forbidden,
+    GatewayError,
+    GatewayNotFound,
+    HTTPException,
+    IllestException,
+    InteractionResponded,
+    InvalidData,
+    LoginFailure,
+    MissingScope,
+    NotFound,
+    PrivilegedIntentsRequired,
+    RateLimited,
+    ServerError,
+    StaleEpoch,
+    UnknownAction,
+)
+from .file import File
+from .replies import AskReply
+from .ui.layout import MediaGalleryItem, SeparatorSpacing, UnfurledMediaItem
+from .intents import Intents
+from .interactions import Interaction, InteractionCallbackResponse, InteractionResponse, Webhook, WebhookMessage
+from .mentions import AllowedMentions
+from .models import *  # noqa: F401,F403
+from .models import __all__ as _models
+from .object import Object
+from .permissions import PermissionOverwrite, Permissions
+from .ui.select import SelectOption
+from .utils import setup_logging
+
+#: The scopes a bot token can hold, as the server names them (`actions::bots::SCOPES`).
+SCOPES = ("messages.read", "messages.write", "guilds.read", "members.read", "moderate", "guilds.manage")
+
+__all__ = [
+    "SCOPES",
+    "AllowedMentions",
+    "Activity",
+    "AttachmentError",
+    "AuthFailed",
+    "BadRequest",
+    "BaseActivity",
+    "BotForbidden",
+    "Button",
+    "Client",
+    "ClientException",
+    "Color",
+    "Colour",
+    "ConnectionClosed",
+    "ContentError",
+    "CustomActivity",
+    "DiscordException",
+    "DiscordServerError",
+    "AskReply",
+    "Embed",
+    "MediaGalleryItem",
+    "SeparatorSpacing",
+    "UnfurledMediaItem",
+    "File",
+    "Forbidden",
+    "Game",
+    "GatewayError",
+    "GatewayNotFound",
+    "HTTPException",
+    "IllestException",
+    "Intents",
+    "Interaction",
+    "InteractionCallbackResponse",
+    "InteractionResponded",
+    "InteractionResponse",
+    "InvalidData",
+    "LoginFailure",
+    "MissingScope",
+    "NotFound",
+    "Object",
+    "PermissionOverwrite",
+    "Permissions",
+    "SelectOption",
+    "PrivilegedIntentsRequired",
+    "RateLimited",
+    "ServerError",
+    "StaleEpoch",
+    "Streaming",
+    "UnknownAction",
+    "Webhook",
+    "WebhookMessage",
+    "__version__",
+    "abc",
+    "app_commands",
+    "setup_logging",
+    "ui",
+    "utils",
+    *_enums,
+    *_models,
+]