matrix-python 1.1.0a0__tar.gz → 1.3.0a0__tar.gz

{matrix_python-1.1.0a0 → matrix_python-1.3.0a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrix-python
-Version: 1.1.0a0
+Version: 1.3.0a0
 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>

matrix_python-1.3.0a0/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.1.0a0 → matrix_python-1.3.0a0}/matrix/__init__.py

@@ -8,21 +8,24 @@ except PackageNotFoundError:
     from matrix._version import version as __version__
 
 from .bot import Bot
-from .group import Group
+from .group import Group, group
 from .config import Config
 from .context import Context
 from .command import Command
 from .help import HelpCommand
 from .checks import cooldown
 from .room import Room
+from .extension import Extension
 
 __all__ = [
     "Bot",
     "Group",
+    "group",
     "Config",
     "Command",
     "Context",
     "HelpCommand",
     "cooldown",
     "Room",
+    "Extension",
 ]

{matrix_python-1.1.0a0 → matrix_python-1.3.0a0}/matrix/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '1.1.0a0'
-__version_tuple__ = version_tuple = (1, 1, 0, 'a0')
+__version__ = version = '1.3.0a0'
+__version_tuple__ = version_tuple = (1, 3, 0, 'a0')
 
-__commit_id__ = commit_id = 'gcd36e40dc'
+__commit_id__ = commit_id = 'gfee3d765e'

matrix_python-1.3.0a0/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.1.0a0 → matrix_python-1.3.0a0}/matrix/command.py

@@ -298,7 +298,6 @@ class Command:
             await ctx.send_help()
 
         ctx.logger.exception("error while executing command '%s'", self)
-        raise error
 
     async def invoke(self, ctx: "Context") -> None:
         parsed_args = self._parse_arguments(ctx)

{matrix_python-1.1.0a0 → matrix_python-1.3.0a0}/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.1.0a0 → matrix_python-1.3.0a0}/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.0a0/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

{matrix_python-1.1.0a0 → matrix_python-1.3.0a0}/matrix/group.py

@@ -82,3 +82,49 @@ class Group(Command):
             await ctx.subcommand(ctx)
         else:
             await self.callback(ctx)
+
+
+def group(
+    name: str,
+    *,
+    description: Optional[str] = None,
+    prefix: Optional[str] = None,
+    parent: Optional[str] = None,
+    usage: Optional[str] = None,
+    cooldown: Optional[tuple[int, float]] = None,
+) -> Callable[[Callback], Group]:
+    """
+    Decorator to create a group with a callback.
+
+    This is equivalent to @bot.group() but for creating groups
+    without immediately registering them to a bot.
+
+    ## Example
+
+    ```python
+    @group("math", description="Math operations")
+    async def math(ctx):
+        await ctx.reply("Math help")
+
+
+    @math.command()
+    async def add(ctx, a: int, b: int):
+        await ctx.reply(f"{a + b}")
+
+
+    bot.register_group(math)
+    ```
+    """
+
+    def decorator(func: Callback) -> Group:
+        return Group(
+            func,
+            name=name,
+            description=description,
+            prefix=prefix,
+            parent=parent,
+            usage=usage,
+            cooldown=cooldown,
+        )
+
+    return decorator