matrix-python 1.2.0a0__tar.gz → 1.3.3a0__tar.gz

matrix_python-1.3.3a0/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "monthly"

matrix_python-1.3.3a0/.github/workflows/CODEOWNERS

@@ -0,0 +1 @@
+* @PenguinBoi12

{matrix_python-1.2.0a0 → matrix_python-1.3.3a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrix-python
-Version: 1.2.0a0
+Version: 1.3.3a0
 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>
@@ -697,8 +697,6 @@ Requires-Dist: mypy; extra == "dev"
 Requires-Dist: types-PyYAML; extra == "dev"
 Requires-Dist: types-Markdown; extra == "dev"
 
-<h1 align="center">Matrix.py</h1>
-
 <div align="center">
   <em>A simple, developer-friendly library to create powerful <a href="https://matrix.org">Matrix</a> bots.</em>
 </div>
@@ -708,13 +706,14 @@ Requires-Dist: types-Markdown; extra == "dev"
 <hr />
 
 [![Static Badge](https://img.shields.io/badge/%F0%9F%93%9A-Documentation-%235c5c5c)](https://github.com/Code-Society-Lab/matrixpy/wiki)
-[![Join on Discord](https://discordapp.com/api/guilds/823178343943897088/widget.png?style=shield)](https://discord.gg/code-society-823178343943897088)
+[![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 )
 [![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]([Matrix](https://matrix.org)). It provides a clean,
+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.
 
@@ -736,7 +735,7 @@ pip install matrix-python
 
 If you plan on contributing to matrix.py, we recommend to install the development libraries:
 ```
-pip install .[env]
+pip install -e .[dev]
 ```
 
 *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.
@@ -745,19 +744,18 @@ pip install .[env]
 ```python
 from matrix import Bot, Context
 
-bot = Bot(username="@gracehopper:matrix.org", password="grace1234")
+bot = Bot(config="config.yml")
 
 
 @bot.command("ping")
 async def ping(ctx: Context):
-    print(f"{ctx.sender} invoked {ctx.body} in room {ctx.room_name}.")
     await ctx.send("Pong!")
 
 
 bot.start()
 ```
 
-[Documentation](https://github.com/Code-Society-Lab/matrixpy/wiki) - [Examples]([https://github.com/Code-Society-Lab/matrixpy/wiki](https://github.com/Code-Society-Lab/matrixpy/tree/main/examples))
+[Documentation](https://github.com/Code-Society-Lab/matrixpy/wiki) - [Examples](https://github.com/Code-Society-Lab/matrixpy/tree/main/examples)
 
 # Contributing
 We welcome everyone to contribute! 
@@ -765,7 +763,7 @@ 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 [Discord community](https://discord.gg/code-society-823178343943897088) and say hi!
+- Or just hop into our [Matrix](https://matrix.to/#/%23codesociety:matrix.org) or [Discord](https://discord.gg/code-society-823178343943897088) server 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).
 

{matrix_python-1.2.0a0 → matrix_python-1.3.3a0}/README.md

@@ -1,5 +1,3 @@
-<h1 align="center">Matrix.py</h1>
-
 <div align="center">
   <em>A simple, developer-friendly library to create powerful <a href="https://matrix.org">Matrix</a> bots.</em>
 </div>
@@ -9,13 +7,14 @@
 <hr />
 
 [![Static Badge](https://img.shields.io/badge/%F0%9F%93%9A-Documentation-%235c5c5c)](https://github.com/Code-Society-Lab/matrixpy/wiki)
-[![Join on Discord](https://discordapp.com/api/guilds/823178343943897088/widget.png?style=shield)](https://discord.gg/code-society-823178343943897088)
+[![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 )
 [![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]([Matrix](https://matrix.org)). It provides a clean,
+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.
 
@@ -37,7 +36,7 @@ pip install matrix-python
 
 If you plan on contributing to matrix.py, we recommend to install the development libraries:
 ```
-pip install .[env]
+pip install -e .[dev]
 ```
 
 *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.
@@ -46,19 +45,18 @@ pip install .[env]
 ```python
 from matrix import Bot, Context
 
-bot = Bot(username="@gracehopper:matrix.org", password="grace1234")
+bot = Bot(config="config.yml")
 
 
 @bot.command("ping")
 async def ping(ctx: Context):
-    print(f"{ctx.sender} invoked {ctx.body} in room {ctx.room_name}.")
     await ctx.send("Pong!")
 
 
 bot.start()
 ```
 
-[Documentation](https://github.com/Code-Society-Lab/matrixpy/wiki) - [Examples]([https://github.com/Code-Society-Lab/matrixpy/wiki](https://github.com/Code-Society-Lab/matrixpy/tree/main/examples))
+[Documentation](https://github.com/Code-Society-Lab/matrixpy/wiki) - [Examples](https://github.com/Code-Society-Lab/matrixpy/tree/main/examples)
 
 # Contributing
 We welcome everyone to contribute! 
@@ -66,7 +64,7 @@ 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 [Discord community](https://discord.gg/code-society-823178343943897088) and say hi!
+- Or just hop into our [Matrix](https://matrix.to/#/%23codesociety:matrix.org) or [Discord](https://discord.gg/code-society-823178343943897088) server 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).
 

matrix_python-1.3.3a0/examples/extension.py

@@ -0,0 +1,45 @@
+from matrix import Extension, Context
+
+extension = Extension("math")
+
+
+@extension.group("math", description="Math Group")
+async def math_group(ctx: Context):
+    pass
+
+
+@math_group.command()
+async def add(ctx: Context, a: int, b: int):
+    await ctx.reply(f"**{a} + {b} = {a + b}**")
+
+
+@math_group.command()
+async def subtract(ctx: Context, a: int, b: int):
+    await ctx.reply(f"{a} - {b} = {a - b}")
+
+
+@math_group.command()
+async def multiply(ctx: Context, a: int, b: int):
+    await ctx.reply(f"{a} x {b} = {a * b}")
+
+
+@math_group.command()
+async def divide(ctx: Context, a: int, b: int):
+    await ctx.reply(f"{a} ÷ {b} = {a / b}")
+
+
+@divide.error(ZeroDivisionError)
+async def divide_error(ctx: Context, error):
+    await ctx.reply(f"Divide error: {error}")
+
+
+"""
+from matrix import Bot
+from math_extension import extension as math_extension
+
+bot = Bot(config="config.yaml")
+
+
+bot.load_extension(math_extension)
+bot.start()
+"""

{matrix_python-1.2.0a0 → matrix_python-1.3.3a0}/matrix/__init__.py

@@ -15,6 +15,7 @@ from .command import Command
 from .help import HelpCommand
 from .checks import cooldown
 from .room import Room
+from .extension import Extension
 
 __all__ = [
     "Bot",
@@ -26,4 +27,5 @@ __all__ = [
     "HelpCommand",
     "cooldown",
     "Room",
+    "Extension",
 ]

{matrix_python-1.2.0a0 → matrix_python-1.3.3a0}/matrix/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '1.2.0a0'
-__version_tuple__ = version_tuple = (1, 2, 0, 'a0')
+__version__ = version = '1.3.3a0'
+__version_tuple__ = version_tuple = (1, 3, 3, 'a0')
 
-__commit_id__ = commit_id = 'gdd753b685'
+__commit_id__ = commit_id = 'g7d083d049'

matrix_python-1.3.3a0/matrix/bot.py

@@ -0,0 +1,288 @@
+import time
+import inspect
+import asyncio
+import logging
+
+from typing import Union, Optional
+
+from nio import AsyncClient, Event, MatrixRoom
+
+from .room import Room
+from .group import Group
+from .config import Config
+from .context import Context
+from .extension import Extension
+from .registry import Registry
+from .help import HelpCommand, DefaultHelpCommand
+from .scheduler import Scheduler
+from .errors import AlreadyRegisteredError, CommandNotFoundError, CheckError
+
+
+class Bot(Registry):
+    """
+    The base class defining a Matrix bot.
+
+    This class manages the connection to a Matrix homeserver, listens
+    for events, and dispatches them to registered handlers. It also supports
+    a command system with decorators for easy registration.
+    """
+
+    def __init__(
+        self, *, config: Union[Config, str], help: Optional[HelpCommand] = None
+    ) -> None:
+        if isinstance(config, Config):
+            self.config = config
+        elif isinstance(config, str):
+            self.config = Config(config_path=config)
+        else:
+            raise TypeError("config must be a Config instance or a config file path")
+
+        super().__init__(self.__class__.__name__, prefix=self.config.prefix)
+
+        self.client: AsyncClient = AsyncClient(self.config.homeserver)
+        self.extensions: dict[str, Extension] = {}
+        self.scheduler: Scheduler = Scheduler()
+        self.log: logging.Logger = logging.getLogger(__name__)
+
+        self.start_at: float | None = None  # unix timestamp
+
+        self.help: HelpCommand = help or DefaultHelpCommand(prefix=self.prefix)
+        self.register_command(self.help)
+
+        self.client.add_event_callback(self._on_event, Event)
+        self._auto_register_events()
+
+    def get_room(self, room_id: str) -> Room:
+        """Retrieve a Room instance based on the room_id."""
+        matrix_room = self.client.rooms[room_id]
+        return Room(matrix_room=matrix_room, client=self.client)
+
+    def load_extension(self, extension: Extension) -> None:
+        self.log.debug(f"Loading extension: '{extension.name}'")
+
+        if extension.name in self.extensions:
+            raise AlreadyRegisteredError(extension)
+
+        for cmd in extension._commands.values():
+            if isinstance(cmd, Group):
+                self.register_group(cmd)
+            else:
+                self.register_command(cmd)
+
+        for event_type, handlers in extension._event_handlers.items():
+            self._event_handlers[event_type].extend(handlers)
+
+        self._checks.extend(extension._checks)
+        self._error_handlers.update(extension._error_handlers)
+        self._command_error_handlers.update(extension._command_error_handlers)
+
+        for job in extension._scheduler.jobs:
+            self.scheduler.scheduler.add_job(
+                job.func,
+                trigger=job.trigger,
+                name=job.name,
+            )
+
+        self.extensions[extension.name] = extension
+        extension.load()
+        self.log.debug("loaded extension '%s'", extension.name)
+
+    def unload_extension(self, ext_name: str) -> None:
+        self.log.debug("Unloading extension: '%s'", ext_name)
+
+        extension = self.extensions.pop(ext_name, None)
+        if extension is None:
+            raise ValueError(f"No extension named '{ext_name}' is loaded")
+
+        for cmd_name in extension._commands:
+            self._commands.pop(cmd_name, None)
+
+        for event_type, handlers in extension._event_handlers.items():
+            for handler in handlers:
+                self._event_handlers[event_type].remove(handler)
+
+        for check in extension._checks:
+            self._checks.remove(check)
+
+        for exc_type in extension._error_handlers:
+            self._error_handlers.pop(exc_type, None)
+
+        for exc_type in extension._command_error_handlers:
+            self._command_error_handlers.pop(exc_type, None)
+
+        for job in extension._scheduler.jobs:
+            bot_job = next((j for j in self.scheduler.jobs if j.func is job.func), None)
+            if bot_job:
+                bot_job.remove()
+
+        extension.unload()
+        self.log.debug("unloaded extension '%s'", ext_name)
+
+    def _auto_register_events(self) -> None:
+        for attr in dir(self):
+            if not attr.startswith("on_"):
+                continue
+            coro = getattr(self, attr, None)
+            if inspect.iscoroutinefunction(coro):
+                try:
+                    self.event(coro)
+                except ValueError:  # ignore unknown name
+                    continue
+
+    async def _on_event(self, room: MatrixRoom, event: Event) -> None:
+        # ignore bot events
+        if event.sender == self.client.user:
+            return
+
+        # ignore events that happened before the bot started
+        if self.start_at and self.start_at > (event.server_timestamp / 1000):
+            return
+
+        try:
+            await self._dispatch(room, event)
+        except Exception as error:
+            await self.on_error(error)
+
+    async def _dispatch(self, room: MatrixRoom, event: Event) -> None:
+        """Internal type-based fan-out plus optional command handling."""
+        for event_type, funcs in self._event_handlers.items():
+            if isinstance(event, event_type):
+                for func in funcs:
+                    await func(room, event)
+
+    async def _process_commands(self, room: MatrixRoom, event: Event) -> None:
+        """Parse and execute commands"""
+        ctx = await self._build_context(room, event)
+
+        if ctx.command:
+            for check in self._checks:
+                if not await check(ctx):
+                    raise CheckError(ctx.command, check)
+
+            await ctx.command(ctx)
+
+    async def _build_context(self, matrix_room: MatrixRoom, event: Event) -> Context:
+        room = self.get_room(matrix_room.room_id)
+        ctx = Context(bot=self, room=room, event=event)
+        prefix: str | None = None
+
+        if self.prefix is not None and ctx.body.startswith(self.prefix):
+            prefix = self.prefix
+        else:
+            prefix = next(
+                (
+                    cmd.prefix
+                    for cmd in self._commands.values()
+                    if cmd.prefix is not None and ctx.body.startswith(cmd.prefix)
+                ),
+                self.config.prefix,
+            )
+
+        if prefix is None or not ctx.body.startswith(prefix):
+            return ctx
+
+        if parts := ctx.body[len(prefix) :].split():
+            cmd_name = parts[0]
+            cmd = self._commands.get(cmd_name)
+
+            if cmd and cmd.prefix and not ctx.body.startswith(cmd.prefix):
+                return ctx
+
+            if not cmd:
+                raise CommandNotFoundError(cmd_name)
+
+            ctx.command = cmd
+
+        return ctx
+
+    async def on_message(self, room: MatrixRoom, event: Event) -> None:
+        """
+        Invoked when a message event is received.
+
+        This method is automatically called when a :class:`nio.RoomMessageText`
+        event is detected. It is primarily responsible for detecting and
+        processing commands that match the bot's defined prefix.
+
+        :param ctx: The context object containing information about the Matrix
+                    room and the message event.
+        :type ctx: Context
+        """
+        await self._process_commands(room, event)
+
+    async def on_ready(self) -> None:
+        """Invoked after a successful login, before sync starts."""
+        self.log.info("bot is ready")
+
+    async def on_error(self, error: Exception) -> None:
+        """
+        Handle errors by invoking a registered error handler,
+        a generic error callback, or logging the exception.
+
+        :param error: The exception instance that was raised.
+        :type error: Exceptipon
+        """
+        if handler := self._error_handlers.get(type(error)):
+            await handler(error)
+            return
+
+        if self._on_error:
+            await self._on_error(error)
+            return
+        self.log.exception("Unhandled error: '%s'", error)
+
+    async def on_command_error(self, ctx: "Context", error: Exception) -> None:
+        """
+        Handles errors raised during command invocation.
+
+        This method is called automatically when a command error occurs.
+        If a specific error handler is registered for the type of the
+        exception, it will be invoked with the current context and error.
+
+        :param ctx: The context in which the command was invoked.
+        :type ctx: Context
+        :param error: The exception that was raised during command execution.
+        :type error: Exception
+        """
+        if handler := self._command_error_handlers.get(type(error)):
+            await handler(ctx, error)
+
+    async def run(self) -> None:
+        """
+        Log in to the Matrix homeserver and begin syncing events.
+
+        This method should be used within an asynchronous context,
+        typically via :func:`asyncio.run`. It handles authentication,
+        calls the :meth:`on_ready` hook, and starts the long-running
+        sync loop for receiving events.
+        """
+        self.client.user = self.config.user_id
+
+        self.start_at = time.time()
+        self.log.info("starting – timestamp=%s", self.start_at)
+
+        if self.config.token:
+            self.client.access_token = self.config.token
+        else:
+            login_resp = await self.client.login(self.config.password)
+            self.log.info("logged in: %s", login_resp)
+
+        self.scheduler.start()
+
+        await self.on_ready()
+        await self.client.sync_forever(timeout=30_000)
+
+    def start(self) -> None:
+        """
+        Synchronous entry point for running the bot.
+
+        This is a convenience wrapper that allows running the bot like a
+        script using a blocking call. It internally calls :meth:`run` within
+        :func:`asyncio.run`, and ensures the client is closed gracefully
+        on interruption.
+        """
+        try:
+            asyncio.run(self.run())
+        except KeyboardInterrupt:
+            self.log.info("bot interrupted by user")
+        finally:
+            asyncio.run(self.client.close())

{matrix_python-1.2.0a0 → matrix_python-1.3.3a0}/matrix/context.py

@@ -28,7 +28,6 @@ class Context:
         self.sender: str = event.sender
 
         # Command metadata
-        self.prefix: str = bot.prefix
         self.command: Optional[Command] = None
         self.subcommand: Optional[Command] = None
         self._args: List[str] = shlex.split(self.body)

{matrix_python-1.2.0a0 → matrix_python-1.3.3a0}/matrix/errors.py

@@ -4,6 +4,7 @@ import inspect
 if TYPE_CHECKING:
     from .command import Command  # pragma: no cover
     from .group import Group  # pragma: no cover
+    from .extension import Extension
 
 Callback = Callable[..., Coroutine[Any, Any, Any]]
 
@@ -12,6 +13,17 @@ class MatrixError(Exception):
     pass
 
 
+class RegistryError(MatrixError):
+    pass
+
+
+class AlreadyRegisteredError(RegistryError):
+    def __init__(self, entry: "Command | Group | Extension"):
+        super().__init__(
+            f"{entry.__class__.__name__} '{entry.name}' is already registered"
+        )
+
+
 class CommandError(MatrixError):
     pass
 
@@ -21,7 +33,7 @@ class CommandNotFoundError(CommandError):
         super().__init__(f"Command with name '{cmd}' not found")
 
 
-class AlreadyRegisteredError(CommandError):
+class CommandAlreadyRegisteredError(CommandError):
     def __init__(self, cmd: "Command"):
         super().__init__(f"Command '{cmd}' is already registered")
 
@@ -40,11 +52,6 @@ class GroupError(CommandError):
     pass
 
 
-class GroupAlreadyRegisteredError(GroupError):
-    def __init__(self, group: "Group"):
-        super().__init__(f"Group '{group}' is already registered")
-
-
 class ConfigError(MatrixError):
     def __init__(self, error: str):
         super().__init__(f"Missing required configuration: '{error}'")

matrix_python-1.3.3a0/matrix/extension.py

@@ -0,0 +1,56 @@
+import logging
+import inspect
+
+from typing import Any, Callable, Coroutine, Optional
+from matrix.registry import Registry
+
+logger = logging.getLogger(__name__)
+
+
+class Extension(Registry):
+    def __init__(self, name: str, prefix: Optional[str] = None) -> None:
+        super().__init__(name, prefix=prefix)
+        self._on_load: Optional[Callable] = None
+        self._on_unload: Optional[Callable] = None
+
+    def load(self) -> None:
+        if self._on_load:
+            self._on_load()
+
+    def on_load(self, func: Callable) -> Callable:
+        """Decorator to register a function to be called after this extension
+        is loaded into the bot.
+
+        ## Example
+
+        ```python
+        @extension.on_load
+        def setup():
+            print("extension loaded")
+        ```
+        """
+        if inspect.iscoroutinefunction(func):
+            raise TypeError("on_load handler must not be a coroutine")
+        self._on_load = func
+        return func
+
+    def unload(self) -> None:
+        if self._on_unload:
+            self._on_unload()
+
+    def on_unload(self, func: Callable) -> Callable:
+        """Decorator to register a function to be called before this extension
+        is unloaded from the bot.
+
+        ## Example
+
+        ```python
+        @extension.on_unload
+        def teardown():
+            print("extension unloaded")
+        ```
+        """
+        if inspect.iscoroutinefunction(func):
+            raise TypeError("on_unload handler must not be a coroutine")
+        self._on_unload = func
+        return func