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

{matrix_python-1.0.4a0 → matrix_python-1.1.0a0}/.github/workflows/publish.yml

@@ -13,6 +13,8 @@ jobs:
 
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - uses: actions/setup-python@v5
         with:

{matrix_python-1.0.4a0 → matrix_python-1.1.0a0}/.gitignore

@@ -175,4 +175,5 @@ cython_debug/
 
 .DS_Store
 
-.vscode
+.vscode
+matrix/_version.py

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrix-python
-Version: 1.0.4a0
+Version: 1.1.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.0.4a0 → matrix_python-1.1.0a0}/matrix/__init__.py

@@ -1,6 +1,11 @@
 """A simple, developer-friendly library to create powerful Matrix bots."""
 
-__version__ = "1.0.4-alpha"
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("matrix-python")
+except PackageNotFoundError:
+    from matrix._version import version as __version__
 
 from .bot import Bot
 from .group import Group

matrix_python-1.1.0a0/matrix/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+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')
+
+__commit_id__ = commit_id = 'gcd36e40dc'

{matrix_python-1.0.4a0 → matrix_python-1.1.0a0}/matrix/bot.py

@@ -1,4 +1,5 @@
 import time
+import inspect
 import asyncio
 import logging
 
@@ -113,7 +114,7 @@ class Bot:
 
         :raises TypeError: If the function is not a coroutine.
         """
-        if not asyncio.iscoroutinefunction(func):
+        if not inspect.iscoroutinefunction(func):
             raise TypeError("Checks must be coroutine")
 
         self.checks.append(func)
@@ -161,7 +162,7 @@ class Bot:
         """
 
         def wrapper(f: Callback) -> Callback:
-            if not asyncio.iscoroutinefunction(f):
+            if not inspect.iscoroutinefunction(f):
                 raise TypeError("Event handlers must be coroutines")
 
             if event_spec:
@@ -285,7 +286,7 @@ class Bot:
         """
 
         def wrapper(f: Callback) -> Callback:
-            if not asyncio.iscoroutinefunction(f):
+            if not inspect.iscoroutinefunction(f):
                 raise TypeError("Scheduled tasks must be coroutines")
 
             self.scheduler.schedule(cron, f)
@@ -324,7 +325,7 @@ class Bot:
         """
 
         def wrapper(func: ErrorCallback) -> Callable:
-            if not asyncio.iscoroutinefunction(func):
+            if not inspect.iscoroutinefunction(func):
                 raise TypeError("The error handler must be a coroutine.")
 
             if exception:
@@ -336,22 +337,16 @@ class Bot:
         return wrapper
 
     def get_room(self, room_id: str) -> Room:
-        """
-        Retrieve a Room instance based on the room_id.
-
-        :param room_id: The ID of the room to retrieve.
-        :type room_id: str
-        :return: An instance of the Room class.
-        :rtype: Room
-        """
-        return Room(room_id=room_id, bot=self)
+        """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 _auto_register_events(self) -> None:
         for attr in dir(self):
             if not attr.startswith("on_"):
                 continue
             coro = getattr(self, attr, None)
-            if asyncio.iscoroutinefunction(coro):
+            if inspect.iscoroutinefunction(coro):
                 try:
                     self.event(coro)
                 except ValueError:  # ignore unknown name
@@ -389,8 +384,9 @@ class Bot:
 
             await ctx.command(ctx)
 
-    async def _build_context(self, room: MatrixRoom, event: Event) -> Context:
+    async def _build_context(self, matrix_room: MatrixRoom, event: Event) -> Context:
         """Builds the base context and extracts the command from the event"""
+        room = self.get_room(matrix_room.room_id)
         ctx = Context(bot=self, room=room, event=event)
 
         if not self.prefix or not ctx.body.startswith(self.prefix):

{matrix_python-1.0.4a0 → matrix_python-1.1.0a0}/matrix/command.py

@@ -1,15 +1,18 @@
-import asyncio
 import inspect
+import types
 
 from typing import (
     TYPE_CHECKING,
     Any,
+    Union,
     Optional,
     Callable,
     Coroutine,
     List,
     get_type_hints,
     DefaultDict,
+    get_args,
+    get_origin,
 )
 
 from .errors import MissingArgumentError, CheckError, CooldownError
@@ -98,7 +101,7 @@ class Command:
         :type func: Callback
         :raises TypeError: If the provided function is not a coroutine.
         """
-        if not asyncio.iscoroutinefunction(func):
+        if not inspect.iscoroutinefunction(func):
             raise TypeError("Commands must be coroutines")
 
         self._callback = func
@@ -134,23 +137,51 @@ class Command:
         return f"{self.prefix}{command_name} {params}"
 
     def _parse_arguments(self, ctx: "Context") -> list[Any]:
+        args = ctx.args
         parsed_args = []
 
         for i, param in enumerate(self.params):
             param_type = self.type_hints.get(param.name, str)
 
-            if i >= len(ctx.args):
+            if i >= len(args):
                 if param.default is not inspect.Parameter.empty:
                     parsed_args.append(param.default)
-                else:
-                    raise MissingArgumentError(param)
-                continue
+                    continue
+                raise MissingArgumentError(param)
 
-            converted_arg = param_type(ctx.args[i])
+            if param.kind is inspect.Parameter.VAR_POSITIONAL:
+                parsed_args.extend(
+                    self._convert_type(param_type, arg) for arg in args[i:]
+                )
+                return parsed_args
+
+            converted_arg = self._convert_type(param_type, args[i])
             parsed_args.append(converted_arg)
 
         return parsed_args
 
+    def _convert_type(self, param_type: type, value: str) -> Any:
+        origin = get_origin(param_type)
+
+        if origin is Union or isinstance(param_type, types.UnionType):
+            union_types = get_args(param_type)
+
+            for union_type in union_types:
+                if union_type is type(None):
+                    continue
+
+                try:
+                    return union_type(value)
+                except (ValueError, TypeError):
+                    continue
+
+            return value
+
+        try:
+            return param_type(value)
+        except (ValueError, TypeError):
+            return value
+
     def check(self, func: Callback) -> None:
         """
         Register a check callback
@@ -160,7 +191,7 @@ class Command:
 
         :raises TypeError: If the function is not a coroutine.
         """
-        if not asyncio.iscoroutinefunction(func):
+        if not inspect.iscoroutinefunction(func):
             raise TypeError("Checks must be coroutine")
 
         self.checks.append(func)
@@ -202,7 +233,7 @@ class Command:
         :raises TypeError: If the function is not a coroutine.
         """
 
-        if not asyncio.iscoroutinefunction(func):
+        if not inspect.iscoroutinefunction(func):
             raise TypeError("The hook must be a coroutine.")
 
         self._before_invoke_callback = func
@@ -217,7 +248,7 @@ class Command:
         :raises TypeError: If the function is not a coroutine.
         """
 
-        if not asyncio.iscoroutinefunction(func):
+        if not inspect.iscoroutinefunction(func):
             raise TypeError("The hook must be a coroutine.")
 
         self._after_invoke_callback = func
@@ -234,7 +265,7 @@ class Command:
         """
 
         def wrapper(func: ErrorCallback) -> Callable:
-            if not asyncio.iscoroutinefunction(func):
+            if not inspect.iscoroutinefunction(func):
                 raise TypeError("The error handler must be a coroutine.")
 
             if exception:

matrix_python-1.1.0a0/matrix/content.py

@@ -0,0 +1,174 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from markdown import markdown
+from typing import Any
+
+
+class BaseMessageContent(ABC):
+    """Base class for outgoing message payloads."""
+
+    msgtype: str
+
+    @abstractmethod
+    def build(self) -> dict[str, Any]:
+        pass
+
+
+@dataclass
+class TextContent(BaseMessageContent):
+    msgtype = "m.text"
+    body: str
+
+    def build(self) -> dict:
+        return {"msgtype": self.msgtype, "body": self.body}
+
+
+@dataclass
+class MarkdownMessage(TextContent):
+    def build(self) -> dict:
+        return {
+            "msgtype": self.msgtype,
+            "body": self.body,
+            "format": "org.matrix.custom.html",
+            "formatted_body": markdown(self.body, extensions=["nl2br"]),
+        }
+
+
+@dataclass
+class NoticeContent(TextContent):
+    msgtype = "m.notice"
+
+
+@dataclass
+class ReplyContent(TextContent):
+    reply_to_event_id: str
+
+    def build(self) -> dict:
+        return {
+            "msgtype": self.msgtype,
+            "body": self.body,
+            "m.relates_to": {"m.in_reply_to": {"event_id": self.reply_to_event_id}},
+        }
+
+
+@dataclass
+class EditContent(TextContent):
+    original_event_id: str
+
+    def build(self) -> dict:
+        return {
+            "msgtype": self.msgtype,
+            "body": f"* {self.body}",
+            "m.new_content": {
+                "msgtype": "m.text",
+                "body": self.body,
+            },
+            "m.relates_to": {
+                "rel_type": "m.replace",
+                "event_id": self.original_event_id,
+            },
+        }
+
+
+@dataclass
+class FileContent(BaseMessageContent):
+    msgtype = "m.file"
+    filename: str
+    url: str
+    mimetype: str
+
+    def build(self) -> dict:
+        return {
+            "msgtype": self.msgtype,
+            "body": self.filename,
+            "url": self.url,
+            "info": {"mimetype": self.mimetype},
+        }
+
+
+@dataclass
+class ImageContent(FileContent):
+    msgtype = "m.image"
+    height: int = 0
+    width: int = 0
+
+    def build(self) -> dict:
+        return {
+            "msgtype": self.msgtype,
+            "body": self.filename,
+            "url": self.url,
+            "info": {
+                "mimetype": self.mimetype,
+                "h": self.height,
+                "w": self.width,
+            },
+        }
+
+
+@dataclass
+class AudioContent(FileContent):
+    msgtype = "m.audio"
+    duration: int = 0
+
+    def build(self) -> dict:
+        return {
+            "msgtype": self.msgtype,
+            "body": self.filename,
+            "url": self.url,
+            "info": {
+                "mimetype": self.mimetype,
+                "duration": self.duration,
+            },
+        }
+
+
+@dataclass
+class VideoContent(FileContent):
+    msgtype = "m.video"
+    height: int = 0
+    width: int = 0
+    duration: int = 0
+
+    def build(self) -> dict:
+        return {
+            "msgtype": self.msgtype,
+            "body": self.filename,
+            "url": self.url,
+            "info": {
+                "mimetype": self.mimetype,
+                "h": self.height,
+                "w": self.width,
+                "duration": self.duration,
+            },
+        }
+
+
+@dataclass
+class LocationContent(BaseMessageContent):
+    msgtype = "m.location"
+    geo_uri: str
+    description: str = ""
+
+    def build(self) -> dict:
+        return {
+            "msgtype": self.msgtype,
+            "body": self.description or self.geo_uri,
+            "geo_uri": self.geo_uri,
+        }
+
+
+@dataclass
+class ReactionContent(BaseMessageContent):
+    """For sending reactions to an event."""
+
+    event_id: str
+    emoji: str
+
+    def build(self) -> dict:
+        return {
+            "m.relates_to": {
+                "rel_type": "m.annotation",
+                "event_id": self.event_id,
+                "key": self.emoji,
+            }
+        }

matrix_python-1.1.0a0/matrix/context.py

@@ -0,0 +1,142 @@
+import shlex
+
+from nio import Event
+from typing import TYPE_CHECKING, Optional, Any, List
+
+from .errors import MatrixError
+from .message import Message
+from .room import Room
+from .types import File, Image
+
+if TYPE_CHECKING:
+    from .bot import Bot  # pragma: no cover
+    from .command import Command  # pragma: no cover
+
+
+class Context:
+    """Represents the context in which a command is executed. Provides
+    access to the bot instance, room and event metadata, parsed arguments,
+    and other utilities.
+    """
+
+    def __init__(self, bot: "Bot", room: Room, event: Event):
+        self.bot = bot
+        self.room = room
+        self.event = event
+
+        self.body: str = getattr(event, "body", "")
+        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)
+
+    @property
+    def args(self) -> List[str]:
+        """
+        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:]
+
+        if self.command:
+            return self._args[1:]
+
+        return self._args
+
+    @property
+    def logger(self) -> Any:
+        """Logger for instance specific to the current room or event."""
+        return self.bot.log.getChild(self.room.room_id)
+
+    async def reply(
+        self,
+        content: str | None = None,
+        *,
+        raw: bool = False,
+        notice: bool = False,
+        file: File | None = None,
+    ) -> Message:
+        """Reply to the command with a message.
+
+        This is a convenience method that sends a message to the room where the
+        command was invoked. Supports text messages (with optional markdown
+        formatting) and file uploads (including images, videos, and audio).
+
+        See `Room.send()` for detailed usage examples and documentation.
+
+        ## Example
+
+        ```python
+        @bot.command()
+        async def hello(ctx: Context):
+            await ctx.reply("Hello **world**!")
+
+        @bot.command()
+        async def status(ctx: Context):
+            await ctx.reply("Bot is online!", notice=True)
+
+        @bot.command()
+        async def cat(ctx: Context):
+            # Upload and send an image
+            from PIL import Image as PILImage
+
+            with PILImage.open("cat.jpg") as img:
+                width, height = img.size
+
+            with open("cat.jpg", "rb") as f:
+                resp, _ = await ctx.room.client.upload(f, content_type="image/jpeg")
+
+            image = Image(
+                path=resp.content_uri,
+                filename="cat.jpg",
+                mimetype="image/jpeg",
+                width=width,
+                height=height
+            )
+            await ctx.reply(file=image)
+        ```
+        """
+
+        try:
+            return await self.room.send(
+                content,
+                raw=raw,
+                notice=notice,
+                file=file,
+            )
+        except Exception as e:
+            raise MatrixError(f"Failed to send message: {e}")
+
+    async def send_help(self) -> None:
+        """Send help from the current command context.
+
+        Displays help text for the current subcommand, command, or the bot's
+        general help menu depending on what's available in the context. The help
+        hierarchy is: subcommand help > command help > bot help.
+
+        ## Example
+
+        ```python
+        @bot.group()
+        async def config(ctx: Context):
+            # If user runs just "!config" with no subcommand
+            await ctx.send_help()
+        ```
+        """
+        if self.subcommand:
+            await self.reply(self.subcommand.help)
+            return
+
+        if self.command:
+            await self.reply(self.command.help)
+            return
+
+        await self.bot.help.execute(self)

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

@@ -77,7 +77,7 @@ class Group(Command):
         return cmd
 
     async def invoke(self, ctx: "Context") -> None:
-        if subcommand := ctx.args.pop(0):
+        if ctx.args and (subcommand := ctx.args.pop(0)):
             ctx.subcommand = self.get_command(subcommand)
             await ctx.subcommand(ctx)
         else:

{matrix_python-1.0.4a0 → matrix_python-1.1.0a0}/matrix/help/help_command.py

@@ -1,4 +1,4 @@
-from typing import Optional, List
+from typing import Union, Optional, List
 from abc import ABC, abstractmethod
 
 from matrix.context import Context
@@ -187,13 +187,9 @@ class HelpCommand(Command, ABC):
         await ctx.reply(help_message)
 
     def parse_help_arguments(
-        self, args: List[str]
+        self, args: List[str | int]
     ) -> tuple[Optional[str], Optional[str], int]:
-        """Parse help command arguments to determine what to show.
-
-        :param args: List of arguments passed to help command
-        :return: Tuple of (command_name, subcommand_name, page_number)
-        """
+        """Parse help command arguments to determine what to show."""
         command_name = None
         subcommand_name = None
         page_number = 1
@@ -201,29 +197,39 @@ class HelpCommand(Command, ABC):
         if not args:
             return command_name, subcommand_name, page_number
 
-        # Check if first argument is a page number
-        if len(args) == 1 and args[0].isdigit():
-            page_number = int(args[0])
+        first_arg = args[0]
+        if len(args) == 1 and (
+            isinstance(first_arg, int)
+            or (isinstance(first_arg, str) and first_arg.isdigit())
+        ):
+            page_number = int(first_arg)
             return command_name, subcommand_name, page_number
 
-        command_name = args[0]
+        command_name = str(first_arg)
 
         if len(args) >= 2:
-            if args[1].isdigit():
-                page_number = int(args[1])
+            second_arg = args[1]
+            if isinstance(second_arg, int) or (
+                isinstance(second_arg, str) and second_arg.isdigit()
+            ):
+                page_number = int(second_arg)
             else:
-                subcommand_name = args[1]
+                subcommand_name = str(second_arg)
 
-                if len(args) >= 3 and args[2].isdigit():
-                    page_number = int(args[2])
+                if len(args) >= 3:
+                    third_arg = args[2]
+                    if isinstance(third_arg, int) or (
+                        isinstance(third_arg, str) and third_arg.isdigit()
+                    ):
+                        page_number = int(third_arg)
 
         return command_name, subcommand_name, page_number
 
     async def execute(
         self,
         ctx: Context,
-        cmd_or_page: str | None = None,
-        subcommand: str | None = None,
+        cmd_or_page: Union[str, int, None] = None,
+        subcommand: Union[str | None] = None,
     ) -> None:
         """
         Execute the help command using show_command_help and show_group_help.