matrix-python 1.4.8a0__py3-none-any.whl → 1.4.10a0__py3-none-any.whl

matrix/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.4.8a0'
-__version_tuple__ = version_tuple = (1, 4, 8, 'a0')
+__version__ = version = '1.4.10a0'
+__version_tuple__ = version_tuple = (1, 4, 10, 'a0')
 
 __commit_id__ = commit_id = None

matrix/checks.py

@@ -8,10 +8,18 @@ def cooldown(rate: int, period: float) -> Callable:
     """
     Decorator to cooldown a command.
 
-    :param rate: The number of request a user can send.
-    :type rate: int
-    :param period: The period in seconds of the cooldown.
-    :type period: float
+    ## Example
+
+    ```python
+    @cooldown(rate=3, period=10)
+    @bot.command("hello")
+    async def hello(ctx: Context) -> None:
+        await ctx.reply("Hello!")
+
+    @hello.error(CooldownError)
+    async def hello_error(ctx: Context, error: CooldownError) -> None:
+        await ctx.reply(f"Slow down! Try again in {error.retry:.1f}s.")
+    ```
     """
 
     def wrapper(cmd: "Command") -> "Command":

matrix/command.py

@@ -30,19 +30,6 @@ ErrorCallback = Callable[["Context", Exception], Coroutine[Any, Any, Any]]
 class Command:
     """
     Represents a command that can be executed with a context and arguments.
-
-    :param func: The coroutine that is executed when the command is invoked.
-    :type func: Callable[..., Coroutine[Any, Any, Any]]
-
-    :param name: Optional name. Defaults to the function's name.
-    :param description: Optional description of what the command does.
-    :param prefix: Optional prefix for the command.
-    :param parent: Optional parent command name for subcommands.
-    :param usage: Optional usage string for the command.
-    :param cooldown: Optional cooldown settings as a tuple of (rate, period).
-
-    :raises TypeError: If the provided name is not a string.
-    :raises TypeError: If the provided callback is not a coroutine.
     """
 
     def __init__(
@@ -85,9 +72,6 @@ class Command:
     def callback(self) -> Callback:
         """
         Returns the coroutine function for this command.
-
-        :return: The command's coroutine function.
-        :rtype: Callback
         """
         return self._callback
 
@@ -96,10 +80,6 @@ class Command:
         """
         Sets the coroutine function for the command and extracts type
         hints and parameters.
-
-        :param func: The coroutine function to use.
-        :type func: Callback
-        :raises TypeError: If the provided function is not a coroutine.
         """
         if not inspect.iscoroutinefunction(func):
             raise TypeError("Commands must be coroutines")
@@ -113,9 +93,6 @@ class Command:
     def _build_help(self) -> str:
         """
         Returns the help text for the command.
-
-        :return: The help text for the command.
-        :rtype: str
         """
         default_help = f"{self.description}\n\nusage: {self.usage}"
         return inspect.cleandoc(default_help)
@@ -124,9 +101,6 @@ class Command:
         """
         Builds and returns the default usage string for the command.
         set at the command initalization.
-
-        :return: A usage string.
-        :rtype: str
         """
         params = " ".join(f"[{p.name}]" for p in self.params)
         command_name = self.name
@@ -186,10 +160,17 @@ class Command:
         """
         Register a check callback
 
-        :param func: The check callback
-        :type func: Callback
+        ## Example
+
+        ```python
+        @bot.command("secret")
+        async def secret(ctx: Context) -> None:
+            await ctx.reply("Access granted!")
 
-        :raises TypeError: If the function is not a coroutine.
+        @secret.check
+        async def is_allowed(ctx: Context) -> bool:
+            return ctx.sender == "@admin:matrix.org"
+        ```
         """
         if not inspect.iscoroutinefunction(func):
             raise TypeError("Checks must be coroutine")
@@ -227,10 +208,17 @@ class Command:
         """
         Registers a coroutine to be called before the command is invoked.
 
-        :param func: The coroutine function to call before command invocation.
-        :type func: Callback
+        ## Example
 
-        :raises TypeError: If the function is not a coroutine.
+        ```python
+        @bot.command("ping")
+        async def ping(ctx: Context) -> None:
+            await ctx.reply("Pong!")
+
+        @ping.before_invoke
+        async def before_ping(ctx: Context) -> None:
+            print(f"ping invoked by {ctx.sender}")
+        ```
         """
 
         if not inspect.iscoroutinefunction(func):
@@ -242,10 +230,17 @@ class Command:
         """
         Registers a coroutine to be called after the command is invoked.
 
-        :param func: The coroutine function to call after command execution.
-        :type func: Callback
+        ## Example
+
+        ```python
+        @bot.command("ping")
+        async def ping(ctx: Context) -> None:
+            await ctx.reply("Pong!")
 
-        :raises TypeError: If the function is not a coroutine.
+        @ping.after_invoke
+        async def after_ping(ctx: Context) -> None:
+            print(f"ping completed for {ctx.sender}")
+        ```
         """
 
         if not inspect.iscoroutinefunction(func):
@@ -257,11 +252,21 @@ class Command:
         """
         Decorator used to register an error handler for this command.
 
-        :param exception: Exception type to register the handler for.
-        :type exception: Optional[Exception]
-        :return: A decorator that registers the provided coroutine as an
-            error handler and returns the original function.
-        :rtype: Callable
+        ## Example
+
+        ```python
+        @bot.command("div")
+        async def div(ctx: Context, a: int, b: int) -> None:
+            await ctx.reply(f"{a / b}")
+
+        @div.error(ZeroDivisionError)
+        async def div_error(ctx: Context, error: ZeroDivisionError) -> None:
+            await ctx.reply("Cannot divide by zero!")
+
+        @div.error(MissingArgumentError)
+        async def div_missing(ctx: Context, error: MissingArgumentError) -> None:
+            await ctx.reply(f"Missing argument: {error}")
+        ```
         """
 
         def wrapper(func: ErrorCallback) -> Callable:
@@ -279,11 +284,6 @@ class Command:
     async def on_error(self, ctx: "Context", error: Exception) -> None:
         """
         Executes the registered error handler if present.
-
-        :param ctx: The command execution context.
-        :type ctx: Context
-        :param error: The exception that was raised.
-        :type error: Exception
         """
 
         if handler := self._error_handlers.get(type(error)):
@@ -322,9 +322,6 @@ class Command:
     async def __call__(self, ctx: "Context") -> None:
         """
         Execute the command with parsed arguments.
-
-        :param ctx: The command execution context.
-        :type ctx: Context
         """
         await self._invoke(ctx)
 

matrix/context.py

@@ -38,9 +38,6 @@ class Context:
         Returns the list of parsed arguments from the message body.
 
         If a command is present, the command name is excluded.
-
-        :return: The list of arguments.
-        :rtype: List[str]
         """
         if self.subcommand:
             return self._args[2:]

matrix/extension.py

@@ -1,21 +1,31 @@
 import inspect
 import logging
-from typing import Callable, Optional
+from typing import Callable
 
 from matrix.protocols import BotLike
 from matrix.registry import Registry
+from matrix.config import Config
 from matrix.room import Room
 
 logger = logging.getLogger(__name__)
 
 
 class Extension(Registry):
-    def __init__(self, name: str, prefix: Optional[str] = None) -> None:
+    def __init__(self, name: str, prefix: str | None = None) -> None:
         super().__init__(name, prefix=prefix)
 
-        self.bot: Optional[BotLike] = None
-        self._on_load: Optional[Callable] = None
-        self._on_unload: Optional[Callable] = None
+        self._bot: BotLike | None = None
+        self._on_load: Callable | None = None
+        self._on_unload: Callable | None = None
+
+    @property
+    def bot(self) -> BotLike:
+        assert self._bot, "Extension is not loaded"
+        return self._bot
+
+    @property
+    def config(self) -> Config:
+        return self.bot.config
 
     def get_room(self, room_id: str) -> Room | None:
         """Retrieve a `Room` instance by its Matrix room ID.
@@ -31,12 +41,10 @@ class Extension(Registry):
             print(room.name)
         ```
         """
-        if self.bot is None:
-            raise RuntimeError("Extension is not loaded")
         return self.bot.get_room(room_id)
 
     def load(self, bot: BotLike) -> None:
-        self.bot = bot
+        self._bot = bot
 
         if self._on_load:
             self._on_load()
@@ -59,7 +67,7 @@ class Extension(Registry):
         return func
 
     def unload(self) -> None:
-        self.bot = None
+        self._bot = None
 
         if self._on_unload:
             self._on_unload()

matrix/group.py

@@ -52,13 +52,21 @@ class Group(Command):
         The command name defaults to the function name unless
         explicitly provided.
 
-        :param name: The name of the command. If omitted, the function
-                     name is used.
-        :type name: str, optional
-        :raises TypeError: If the decorated function is not a coroutine.
-        :raises ValueError: If a command with the same name is registered.
-        :return: Decorator that registers the command handler.
-        :rtype: Callback
+        ## Example
+
+        ```python
+        @bot.group("math")
+        async def math(ctx: Context) -> None:
+            await ctx.send_help()
+
+        @math.command()
+        async def add(ctx: Context, a: int, b: int) -> None:
+            await ctx.reply(f"{a + b}")
+
+        @math.command("sub")
+        async def subtract(ctx: Context, a: int, b: int) -> None:
+            await ctx.reply(f"{a - b}")
+        ```
         """
 
         def wrapper(func: Callback) -> Command:

matrix/help/help_command.py

@@ -17,11 +17,7 @@ class HelpCommand(Command, ABC):
     DEFAULT_PER_PAGE = 5
 
     def __init__(self, prefix: Optional[str] = None, per_page: int = DEFAULT_PER_PAGE):
-        """Initialize the help command.
-
-        :param prefix: Command prefix override
-        :param per_page: Number of commands to display per page
-        """
+        """Initialize the help command."""
         super().__init__(
             self.execute,
             name="help",
@@ -32,18 +28,48 @@ class HelpCommand(Command, ABC):
 
     @abstractmethod
     def format_help_page(self, page: Page[Command], title: str = "Commands") -> str:
+        """Format a full page of commands into a displayable string.
+
+        ## Example
+
+        ```python
+        def format_help_page(self, page, title="Commands") -> str:
+            lines = [f"**{title}**"]
+            for cmd in page.items:
+                lines.append(self.format_command(cmd))
+            lines.append(self.format_page_info(page))
+            return "\\n".join(lines)
+        ```
+        """
         pass  # pragma: no cover
 
     @abstractmethod
     def format_subcommand_page(self, page: Page[Command], group_name: str) -> str:
+        """Format a full page of subcommands for a group into a displayable string.
+
+        ## Example
+
+        ```python
+        def format_subcommand_page(self, page, group_name) -> str:
+            lines = [f"**{group_name} subcommands**"]
+            for cmd in page.items:
+                lines.append(self.format_subcommand(cmd))
+            lines.append(self.format_page_info(page))
+            return "\\n".join(lines)
+        ```
+        """
         pass  # pragma: no cover
 
     @abstractmethod
     def format_command(self, cmd: Command) -> str:
         """Format a single command for display.
 
-        :param cmd: The command to format
-        :return: Formatted string representation of the command
+        ## Example
+
+        ```python
+        def format_command(self, cmd) -> str:
+            return f"**{cmd.name}** — {cmd.description}"
+        ```
         """
         pass  # pragma: no cover
 
@@ -51,8 +77,12 @@ class HelpCommand(Command, ABC):
     def format_group(self, group: Group) -> str:  # pragma: no cover
         """Format a group command for display.
 
-        :param group: The group to format
-        :return: Formatted string representation of the group
+        ## Example
+
+        ```python
+        def format_group(self, group) -> str:
+            return f"**{group.name}** [group] — {group.description}"
+        ```
         """
         pass
 
@@ -60,8 +90,12 @@ class HelpCommand(Command, ABC):
     def format_subcommand(self, subcommand: Command) -> str:
         """Format a subcommand for display.
 
-        :param subcommand: The subcommand to format
-        :return: Formatted string representation of the subcommand
+        ## Example
+
+        ```python
+        def format_subcommand(self, subcommand) -> str:
+            return f"  **{subcommand.name}** — {subcommand.description}"
+        ```
         """
         pass  # pragma: no cover
 
@@ -69,8 +103,12 @@ class HelpCommand(Command, ABC):
     def format_page_info(self, page: Page[Command]) -> str:
         """Format the page information display.
 
-        :param page: Page object containing pagination info
-        :return: Formatted page information string
+        ## Example
+
+        ```python
+        def format_page_info(self, page) -> str:
+            return f"Page {page.page_number}/{page.total_pages}"
+        ```
         """
         pass  # pragma: no cover
 
@@ -98,43 +136,25 @@ class HelpCommand(Command, ABC):
         pass  # pragma: no cover
 
     def get_commands_paginator(self, ctx: Context) -> Paginator[Command]:
-        """Get a paginator for all commands.
-
-        :param ctx: Command context
-        :return: Paginator configured with all commands
-        """
+        """Get a paginator for all commands."""
         all_commands = list(ctx.bot.commands.values())
         sorted_commands = sorted(all_commands, key=lambda c: c.name.lower())
 
         return Paginator(sorted_commands, self.per_page)
 
     def get_subcommands_paginator(self, group: Group) -> Paginator[Command]:
-        """Get a paginator for all subcommands in a group.
-
-        :param group: The group to get subcommands from
-        :return: Paginator configured with all subcommands
-        """
+        """Get a paginator for all subcommands in a group."""
         subcommands = list(getattr(group, "commands", {}).values())
         sorted_subcommands = sorted(subcommands, key=lambda c: c.name.lower())
 
         return Paginator(sorted_subcommands, self.per_page)
 
     def find_command(self, ctx: Context, command_name: str) -> Optional[Command]:
-        """Find a command by name.
-
-        :param ctx: Command context
-        :param command_name: Name of the command to find
-        :return: Command if found, None otherwise
-        """
+        """Find a command by name."""
         return ctx.bot.commands.get(command_name)
 
     def find_subcommand(self, group: Group, subcommand_name: str) -> Optional[Command]:
-        """Find a subcommand within a group.
-
-        :param group: The group to search in
-        :param subcommand_name: Name of the subcommand to find
-        :return: Subcommand if found, None otherwise
-        """
+        """Find a subcommand within a group."""
         group_commands = getattr(group, "commands", {})
         return group_commands.get(subcommand_name)
 
@@ -175,11 +195,7 @@ class HelpCommand(Command, ABC):
             await self.on_empty_page(ctx)
 
     async def show_help_page(self, ctx: Context, page_number: int = 1) -> None:
-        """Show a paginated help page for all commands.
-
-        :param ctx: Command context
-        :param page_number: Page number to display
-        """
+        """Show a paginated help page for all commands."""
         paginator = self.get_commands_paginator(ctx)
         page = paginator.get_page(page_number)
         help_message = self.format_help_page(page)
@@ -271,12 +287,7 @@ class DefaultHelpCommand(HelpCommand):
     """
 
     def format_help_page(self, page: Page[Command], title: str = "Commands") -> str:
-        """Format a complete help page.
-
-        :param page: Page object containing commands and pagination info
-        :param title: Title for the help page
-        :return: Complete formatted help page
-        """
+        """Format a complete help page."""
         help_entries = []
 
         if not page.items:
@@ -294,12 +305,7 @@ class DefaultHelpCommand(HelpCommand):
         return f"**{title}**\n\n{help_text}\n\n{page_info}"
 
     def format_subcommand_page(self, page: Page[Command], group_name: str) -> str:
-        """Format a complete subcommand help page.
-
-        :param page: Page object containing subcommands and pagination info
-        :param group_name: Name of the parent group
-        :return: Complete formatted subcommand help page
-        """
+        """Format a complete subcommand help page."""
         help_entries = []
 
         if not page.items:
@@ -314,11 +320,7 @@ class DefaultHelpCommand(HelpCommand):
         return f"**{group_name} Subcommands**\n\n{help_text}\n\n{page_info}"
 
     def format_command(self, cmd: Command) -> str:
-        """Format a single command for display.
-
-        :param cmd: The command to format
-        :return: Formatted string representation of the command
-        """
+        """Format a single command for display."""
         return (
             f"**{cmd.name}**\n"
             f"Usage: `{cmd.usage}`\n"
@@ -326,11 +328,7 @@ class DefaultHelpCommand(HelpCommand):
         )
 
     def format_group(self, group: Group) -> str:
-        """Format a group command for display.
-
-        :param group: The group to format
-        :return: Formatted string representation of the group
-        """
+        """Format a group command for display."""
         subcommands_text = ""
         subcommand_count = len(getattr(group, "commands", {}))
 
@@ -344,11 +342,7 @@ class DefaultHelpCommand(HelpCommand):
         )
 
     def format_subcommand(self, subcommand: Command) -> str:
-        """Format a subcommand for display.
-
-        :param subcommand: The subcommand to format
-        :return: Formatted string representation of the subcommand
-        """
+        """Format a subcommand for display."""
         return (
             f"**{subcommand.name}**\n"
             f"Usage: `{subcommand.usage}`\n"
@@ -356,11 +350,7 @@ class DefaultHelpCommand(HelpCommand):
         )
 
     def format_page_info(self, page: Page[Command]) -> str:
-        """Format the page information display.
-
-        :param page: Page object containing pagination info
-        :return: Formatted page information string
-        """
+        """Format the page information display."""
         return f"**Page {page.page_number}/{page.total_pages}**"
 
     async def on_command_not_found(self, ctx: Context, command_name: str) -> None:

matrix/help/pagination.py

@@ -7,22 +7,14 @@ class Paginator(Generic[T]):
     """A generic paginator for any list of items."""
 
     def __init__(self, items: List[T], per_page: int = 5):
-        """Initialize the paginator.
-
-        :param items: List of items to paginate
-        :param per_page: Number of items per page
-        """
+        """Initialize the paginator."""
         self.items = items
         self.per_page = per_page
         self.total_items = len(items)
         self.total_pages = max(1, -(-self.total_items // self.per_page))
 
     def get_page(self, page_number: int) -> "Page[T]":
-        """Get a specific page of items.
-
-        :param page_number: Page number to retrieve (1-indexed)
-        :return: Page object containing items and metadata
-        """
+        """Get a specific page of items."""
         # Clamp page number to valid range
         page_number = max(1, min(page_number, self.total_pages))
 
@@ -38,10 +30,7 @@ class Paginator(Generic[T]):
         )
 
     def get_pages(self) -> List["Page[T]"]:
-        """Get all pages.
-
-        :return: List of all pages
-        """
+        """Get all pages."""
         return [self.get_page(i) for i in range(1, self.total_pages + 1)]
 
 
@@ -56,14 +45,7 @@ class Page(Generic[T]):
         per_page: int,
         total_items: int,
     ):
-        """Initialize a page.
-
-        :param items: Items on this page
-        :param page_number: Current page number
-        :param total_pages: Total number of pages
-        :param per_page: Items per page
-        :param total_items: Total number of items across all pages
-        """
+        """Initialize a page."""
         self.items = items
         self.page_number = page_number
         self.total_pages = total_pages

matrix/protocols.py

@@ -1,9 +1,13 @@
 from typing import Protocol
 
+from matrix.config import Config
 from matrix.room import Room
 
 
 class BotLike(Protocol):
     prefix: str | None
 
+    @property
+    def config(self) -> Config: ...
+
     def get_room(self, room_id: str) -> Room | None: ...

matrix/registry.py

@@ -2,7 +2,20 @@ import inspect
 import logging
 
 from collections import defaultdict
-from typing import Any, Callable, Coroutine, Optional, Type, Union, Dict, List
+from typing import (
+    TypeVar,
+    Any,
+    Callable,
+    Coroutine,
+    Literal,
+    Optional,
+    Type,
+    Union,
+    Dict,
+    List,
+    cast,
+    overload,
+)
 
 from nio import (
     Event,
@@ -25,6 +38,8 @@ GroupCallable = Callable[[Callable[..., Coroutine[Any, Any, Any]]], Group]
 ErrorCallback = Callable[[Exception], Coroutine]
 CommandErrorCallback = Callable[[Context, Exception], Coroutine[Any, Any, Any]]
 
+F = TypeVar("F", ErrorCallback, CommandErrorCallback)
+
 
 class Registry:
     """
@@ -355,43 +370,91 @@ class Registry:
 
         return wrapper
 
+    @overload
     def error(
-        self, exception: Optional[type[Exception]] = None
-    ) -> Callable[[ErrorCallback], ErrorCallback]:
+        self,
+        exception: Optional[type[Exception]] = None,
+        *,
+        context: Literal[True],
+    ) -> Callable[[CommandErrorCallback], CommandErrorCallback]: ...
+
+    @overload
+    def error(
+        self,
+        exception: Optional[type[Exception]] = None,
+        *,
+        context: Literal[False] = ...,
+    ) -> Callable[[ErrorCallback], ErrorCallback]: ...
+
+    def error(
+        self,
+        exception: Optional[type[Exception]] = None,
+        *,
+        context: bool = False,
+    ) -> Union[
+        Callable[[ErrorCallback], ErrorCallback],
+        Callable[[CommandErrorCallback], CommandErrorCallback],
+    ]:
         """Decorator to register an error handler.
 
         If an exception type is provided, the handler is only invoked for
         that specific exception. If omitted, the handler acts as a generic
         fallback for any unhandled error.
 
+        Set ``context=True`` to receive the command context alongside the error,
+        useful for command-specific errors where you want to reply to the user.
+
         ## Example
 
         ```python
         @bot.error(ValueError)
         async def on_value_error(error):
-            await room.send(f"Bad value: {error}")
+            pass
 
         @bot.error()
         async def on_any_error(error):
-            await room.send(f"Something went wrong: {error}")
+            pass
+
+        @bot.error(CommandNotFoundError, context=True)
+        async def on_command_not_found(ctx, error):
+            await ctx.reply("Command not found!")
         ```
         """
 
-        if not exception:
-            exception = Exception
-
-        def wrapper(func: ErrorCallback) -> ErrorCallback:
+        def wrapper(
+            func: F,
+        ) -> F:
             if not inspect.iscoroutinefunction(func):
                 raise TypeError("Error handlers must be coroutines")
 
-            self._error_handlers[exception] = func
+            if context:
+                self._register_command_error(
+                    cast(CommandErrorCallback, func), exception
+                )
+            else:
+                self._register_error(cast(ErrorCallback, func), exception)
 
             logger.debug(
                 "registered error handler '%s' on %s",
                 func.__name__,
                 type(self).__name__,
             )
-
             return func
 
         return wrapper
+
+    def _register_error(
+        self, func: ErrorCallback, exception: Optional[type[Exception]] = None
+    ) -> None:
+        if not exception:
+            exception = Exception
+        self._error_handlers[exception] = func
+
+    def _register_command_error(
+        self,
+        func: CommandErrorCallback,
+        exception: Optional[type[Exception]] = None,
+    ) -> None:
+        if not exception:
+            exception = Exception
+        self._command_error_handlers[exception] = func

matrix/scheduler.py

@@ -21,11 +21,6 @@ class Scheduler:
     def _parse_cron(self, cron: str) -> dict:
         """
         Parse a cron string into a dictionary suitable for CronTrigger.
-
-        :param cron: The cron string to parse.
-        :type cron: str
-        :return: A dictionary with cron fields.
-        :rtype: dict
         """
         fields = cron.split()
         if len(fields) != 5:
@@ -42,10 +37,13 @@ class Scheduler:
         """
         Schedule a coroutine function to be run at specified intervals.
 
-        :param cron: The cron string defining the schedule.
-        :type cron: str
-        :param func: The coroutine function to run.
-        :type func: Callback
+        ## Example
+
+        ```python
+        @bot.schedule("0 9 * * 1-5")
+        async def morning_update() -> None:
+            await room.send("Good morning!")
+        ```
         """
         cron_trigger = CronTrigger(**self._parse_cron(cron))
         self.scheduler.add_job(func, trigger=cron_trigger, name=func.__name__)

{matrix_python-1.4.8a0.dist-info → matrix_python-1.4.10a0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrix-python
-Version: 1.4.8a0
+Version: 1.4.10a0
 Summary: An easy-to-use Matrix bot framework designed for quick development and minimal setup
 Author: Simon Roy,  Chris Dedman Rollet 
 Maintainer-email: Code Society Lab <admin@codesociety.xyz>
@@ -40,57 +40,72 @@ Provides-Extra: dev
 Requires-Dist: pytest==9.0.3; extra == "dev"
 Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
 Requires-Dist: black==26.3.1; extra == "dev"
-Requires-Dist: mypy==1.20.0; extra == "dev"
+Requires-Dist: mypy==1.20.1; extra == "dev"
 Requires-Dist: types-PyYAML==6.0.12.20260408; extra == "dev"
 Requires-Dist: types-Markdown==3.10.2.20260408; extra == "dev"
+Provides-Extra: doc
+Requires-Dist: mkdocs==1.6.1; extra == "doc"
+Requires-Dist: mkdocs-material==9.7.6; extra == "doc"
+Requires-Dist: mkdocstrings[python]==1.0.4; extra == "doc"
 
 <div align="center">
   <em>A simple, developer-friendly library to create powerful <a href="https://matrix.org">Matrix</a> bots.</em>
 </div>
 
-<img alt="image" src="https://github.com/user-attachments/assets/d9140a9e-27fa-44e4-a5ca-87ee7bbf868f" />
+<div align="center">
+  <img alt="matrix.py" src="https://github.com/user-attachments/assets/d9140a9e-27fa-44e4-a5ca-87ee7bbf868f" />
+</div>
+
+<div align="center">
 
-<hr />
+[<img src="https://img.shields.io/badge/Get%20Started-black?style=for-the-badge" />](https://matrixpy.code-society.xyz/guides/introduction/)
+[<img src="https://img.shields.io/badge/Reference-555555?style=for-the-badge" />](https://matrixpy.code-society.xyz/reference/bot/)
+
+</div>
+
+<div align="center">
 
-[![Static Badge](https://img.shields.io/badge/%F0%9F%93%9A-Documentation-%235c5c5c)](https://github.com/Code-Society-Lab/matrixpy/wiki)
 [![Join Discord](https://discordapp.com/api/guilds/823178343943897088/widget.png?style=shield)](https://discord.gg/code-society-823178343943897088)
-[![Join Matrix](https://img.shields.io/matrix/codesociety%3Amatrix.org?logo=matrix&label=%20&labelColor=%23202020&color=%23202020)](https://matrix.to/#/%23codesociety:matrix.org )
+[![Join Matrix](https://img.shields.io/matrix/codesociety%3Amatrix.org?logo=matrix&label=%20&labelColor=%23202020&color=%23202020)](https://matrix.to/#/%23codesociety:matrix.org)
 [![Tests](https://github.com/Code-Society-Lab/matrixpy/actions/workflows/tests.yml/badge.svg)](https://github.com/Code-Society-Lab/matrixpy/actions/workflows/tests.yml)
 [![CodeQL Advanced](https://github.com/Code-Society-Lab/matrixpy/actions/workflows/codeql.yml/badge.svg)](https://github.com/Code-Society-Lab/matrixpy/actions/workflows/codeql.yml)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/Code-Society-Lab/matrixpy/badge)](https://securityscorecards.dev/viewer/?uri=github.com/Code-Society-Lab/matrixpy)
 
-Matrix.py is a lightweight and intuitive Python library to build bots on
-the [Matrix protocol](https://matrix.org). It provides a clean,
-decorator-based API similar to popular event-driven frameworks, allowing
-developers to focus on behavior rather than boilerplate.
+</div>
 
-#### Key Features
+---
 
-- Minimal setup, easy to extend
-- Event-driven API using async/await
-- Clean command registration
-- Automatic event handler registration
-- Built on [matrix-nio](https://github.com/matrix-nio/matrix-nio)
+Matrix.py is a lightweight and intuitive Python library to build bots on the [Matrix protocol](https://matrix.org). It
+provides a clean, decorator-based API similar to popular event-driven frameworks, allowing developers to focus on
+behavior rather than boilerplate.
 
-# Quickstart
+- **Minimal setup** — install and have a working bot running in minutes
+- **Event-driven** — async/await API reacting to any Matrix room event
+- **Command system** — decorator-based commands with automatic argument parsing
+- **Extensions** — split your bot into modules as it grows
 
-**Requirements**
+## Quickstart
 
-- Python 3.10+
+**Requirements:** Python 3.10+
 
-```
+```bash
 pip install matrix-python
 ```
 
-If you plan on contributing to matrix.py, we recommend to install the development libraries:
+Using a virtual environment is strongly recommended:
 
-```
-pip install -e .[dev]
+```bash
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+pip install matrix-python
 ```
 
-*Note*: It is recommended to use
-a [virtual environment](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/)
-when installing python packages.
+Create a `config.yml`:
+
+```yaml
+USERNAME: "@yourbot:matrix.org"
+PASSWORD: "your_password"
+```
 
 ```python
 from matrix import Bot, Context
@@ -106,23 +121,29 @@ async def ping(ctx: Context):
 bot.start(config="config.yml")
 ```
 
-[Documentation](https://github.com/Code-Society-Lab/matrixpy/wiki) - [Examples](https://github.com/Code-Society-Lab/matrixpy/tree/main/examples)
+Send `!ping` in any room the bot is in, it will reply `Pong!`.
+
+## Where to go next
 
-# Contributing
+- [**Guides**](https://matrixpy.codesociety.xyz/guides/introduction/) — step-by-step tutorials covering commands,
+  events, checks, extensions, and more
+- [**Reference**](https://matrixpy.codesociety.xyz/reference/bot/) — complete API documentation for every class and
+  function
+- [**Examples**](https://matrixpy.codesociety.xyz/examples/) — ready-to-run example bots
+  demonstrating common patterns
 
-We welcome everyone to contribute!
+## Contributing
 
-Whether it's fixing bugs, suggesting features, or improving the docs - every bit helps.
+We welcome everyone to contribute! Whether it's fixing bugs, suggesting features, or improving the docs. Every bit
+helps.
 
-- Submit an issue
-- Open a pull request
-- Or just hop into our [Matrix](https://matrix.to/#/%23codesociety:matrix.org)
-  or [Discord](https://discord.gg/code-society-823178343943897088) server and say hi!
+- [Submit an issue](https://github.com/Code-Society-Lab/matrixpy/issues)
+- [Open a pull request](https://github.com/Code-Society-Lab/matrixpy/blob/main/CONTRIBUTING.md)
+- Hop into our [Matrix](https://matrix.to/#/%23codesociety:matrix.org)
+  or [Discord](https://discord.gg/code-society-823178343943897088) and say hi!
 
-If you intend to contribute, please read the [CONTRIBUTING.md](./CONTRIBUTING.md) first. Additionally, **every
-contributor** is expected to follow the [code of conduct](./CODE_OF_CONDUCT.md).
+Please read the [CONTRIBUTING.md](./CONTRIBUTING.md) and follow the [code of conduct](./CODE_OF_CONDUCT.md).
 
-# License
+## License
 
-This project is licensed under the terms
-of [MIT license](https://github.com/Code-Society-Lab/matrixpy/blob/main/LICENSE).
+Released under the [MIT License](https://github.com/Code-Society-Lab/matrixpy/blob/main/LICENSE).

matrix_python-1.4.10a0.dist-info/RECORD

@@ -0,0 +1,25 @@
+matrix/__init__.py,sha256=g8yEFjELnnwlvOKns-Ug6LgOezkjAFZ-Opt7esbBHKg,728
+matrix/_version.py,sha256=mIVsMSXZUY9bR5xv4sLyWvbSaMCfZOJSgUtWBegbo6Q,530
+matrix/bot.py,sha256=tbcn1Ra025I9plM-gf0NpzPKSTBlYe0_L8_RLO8w9GM,11984
+matrix/checks.py,sha256=8geXrN8dEIR8HMbc2DQz4XFxLnBvjeqLUUqO9w1JPnA,678
+matrix/command.py,sha256=I5sb9tTnhEd2RRfWRfGcJy3Xj0pA856KnHPm6JKPY7A,9942
+matrix/config.py,sha256=JW_BBs-msIhtv1AGebZumLsx4td-Gp-NZaNYPJxRsEo,3680
+matrix/content.py,sha256=z5_E2rTvHsODE52OiDkhDHNQAryx5NLhyHjBb65Xe-U,3853
+matrix/context.py,sha256=tmtgzv3mtw4yNBw5ZUuDTr8fes1zWlaFZp7oU-WzAmk,3965
+matrix/errors.py,sha256=HKGb5NUeFuZvieXgpLlVSmUxK4jpA0ODuiPQqQlbQTE,1676
+matrix/extension.py,sha256=5f6pW_6D8wwN5qKhnQRkCWWDkkQw9t47j5XRNZNsyGQ,2399
+matrix/group.py,sha256=P4NWNczfUpl0693lWswqafpEnYfzNXH_gz3swIlaxaE,3734
+matrix/message.py,sha256=w6pu86goylxdrX5fgXPUMB_tW0bOFIk6tKy6qkXTjl4,5136
+matrix/protocols.py,sha256=pIkHL4yuenvxh-gFhRPudCHJcfMBRxq2lUL5S5sPxpM,250
+matrix/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+matrix/registry.py,sha256=OiEWaO66k4QOnOPCaXL5Ys-_TnVioI4q5ulyRP_fGS4,14202
+matrix/room.py,sha256=PBuMWQo8mKy2d2XIeMbBlVBTnnqZjOPPGpKLp4K1AVM,14038
+matrix/scheduler.py,sha256=8GDzxJhuDh32HRz3DyVw0SKXAQ9Az3t3jsDersSoB70,1597
+matrix/types.py,sha256=UFjC7p8RAf7piEPvp2X3NuWdqBwkM9Yc3He7KWb9icc,384
+matrix/help/__init__.py,sha256=1u7V7T_-VgYDeQCTXsc4y8Fo-8gJhOqYJq2U3cUjMWg,168
+matrix/help/help_command.py,sha256=DEhOpMGx0-43m--sVqQjq-w71r6yKsrxSPDMFsr4oE4,12277
+matrix/help/pagination.py,sha256=tmqgz_msP0qWefCiMDzDcGMP830z89VgQHxptj8ogzc,2175
+matrix_python-1.4.10a0.dist-info/METADATA,sha256=YFYoLz8OIUYp28jtwVVyluQ5A6QwRRtMehpJzbwOnwk,6209
+matrix_python-1.4.10a0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+matrix_python-1.4.10a0.dist-info/top_level.txt,sha256=BvHVM9c7-5SLzg-1OCRpHKgqAubWhRN1e38e6coHs-g,7
+matrix_python-1.4.10a0.dist-info/RECORD,,

matrix_python-1.4.8a0.dist-info/RECORD

@@ -1,25 +0,0 @@
-matrix/__init__.py,sha256=g8yEFjELnnwlvOKns-Ug6LgOezkjAFZ-Opt7esbBHKg,728
-matrix/_version.py,sha256=Sp0Aavn8Gz-jkQehzIA2xsa-Il-CUVey1i9m5oSJ344,528
-matrix/bot.py,sha256=tbcn1Ra025I9plM-gf0NpzPKSTBlYe0_L8_RLO8w9GM,11984
-matrix/checks.py,sha256=F_7432_OcFO-im4fRAj62MUsyv1mXywT4OsGC_7xbBQ,486
-matrix/command.py,sha256=GrP3WsT07sKehGX7PHfnT7gRX22d99877VPd0X2ViEw,10514
-matrix/config.py,sha256=JW_BBs-msIhtv1AGebZumLsx4td-Gp-NZaNYPJxRsEo,3680
-matrix/content.py,sha256=z5_E2rTvHsODE52OiDkhDHNQAryx5NLhyHjBb65Xe-U,3853
-matrix/context.py,sha256=-CbxY-LtK9-jgHERhvJH73B3SpO-Uk5ty0j1TMKfzuI,4032
-matrix/errors.py,sha256=HKGb5NUeFuZvieXgpLlVSmUxK4jpA0ODuiPQqQlbQTE,1676
-matrix/extension.py,sha256=RbCx58CdRXF8kGUgS-ec1aZdd-K5hQedhCCQ0-YR4Vg,2272
-matrix/group.py,sha256=TRIX7PE3lcB2ZWu3xY2W2OAmE_a8-i2zHNBYnX5uj28,3691
-matrix/message.py,sha256=w6pu86goylxdrX5fgXPUMB_tW0bOFIk6tKy6qkXTjl4,5136
-matrix/protocols.py,sha256=nFb4tLanwtrKWoIhZ96xMwXPjD3RF5ITca_yXtakXC4,166
-matrix/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-matrix/registry.py,sha256=PgdmbBADS-yqdFdj9x3QSsVfefx8Li848CU_UBbqCLQ,12646
-matrix/room.py,sha256=PBuMWQo8mKy2d2XIeMbBlVBTnnqZjOPPGpKLp4K1AVM,14038
-matrix/scheduler.py,sha256=EXsL9i8IDXhcpdW8lti0BR5XcIgkmud4iwOPaqcE9Gw,1727
-matrix/types.py,sha256=UFjC7p8RAf7piEPvp2X3NuWdqBwkM9Yc3He7KWb9icc,384
-matrix/help/__init__.py,sha256=1u7V7T_-VgYDeQCTXsc4y8Fo-8gJhOqYJq2U3cUjMWg,168
-matrix/help/help_command.py,sha256=xCLmKklw74LEMjbUfgQR9eaPMFvi3sPtDw2n2pnAnVQ,12800
-matrix/help/pagination.py,sha256=sJk0wC46sFHf7xl7WsGRAUc4FC7b9hPqmwQDmvcjwgM,2717
-matrix_python-1.4.8a0.dist-info/METADATA,sha256=Cw_QAKOVIvymFvEELdhYf72O0UkQOSk21KMpc01KAOY,5421
-matrix_python-1.4.8a0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-matrix_python-1.4.8a0.dist-info/top_level.txt,sha256=BvHVM9c7-5SLzg-1OCRpHKgqAubWhRN1e38e6coHs-g,7
-matrix_python-1.4.8a0.dist-info/RECORD,,