matrix-python 1.4.1a0__tar.gz → 1.4.3a0__tar.gz

matrix_python-1.4.3a0/.github/workflows/tests.yml

@@ -0,0 +1,35 @@
+name: Tests
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v3
+        with:
+          python-version: "3.12"
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[dev]
+      - name: Lint with Black
+        run: |
+          black --check matrix/ tests/ examples/
+      - name: Check typing with mypy
+        run: |
+          mypy matrix
+      - name: Test with pytest
+        run: |
+          pytest -v

{matrix_python-1.4.1a0 → matrix_python-1.4.3a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrix-python
-Version: 1.4.1a0
+Version: 1.4.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>
@@ -718,6 +718,7 @@ decorator-based API similar to popular event-driven frameworks, allowing
 developers to focus on behavior rather than boilerplate.
 
 #### Key Features
+
 - Minimal setup, easy to extend
 - Event-driven API using async/await
 - Clean command registration
@@ -727,6 +728,7 @@ developers to focus on behavior rather than boilerplate.
 # Quickstart
 
 **Requirements**
+
 - Python 3.10+
 
 ```
@@ -734,38 +736,45 @@ pip install matrix-python
 ```
 
 If you plan on contributing to matrix.py, we recommend to install the development libraries:
+
 ```
 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.
-
+*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.
 
 ```python
 from matrix import Bot, Context
 
-bot = Bot(config="config.yml")
+bot = Bot()
 
 
 @bot.command("ping")
 async def ping(ctx: Context):
-    await ctx.send("Pong!")
+    await ctx.reply("Pong!")
 
 
-bot.start()
+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)
 
 # Contributing
-We welcome everyone to contribute! 
+
+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!
+- 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).
+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).
 
 # License
+
 matrix.py is released under [GPL-3.0](https://opensource.org/license/gpl-3-0)

{matrix_python-1.4.1a0 → matrix_python-1.4.3a0}/README.md

@@ -19,6 +19,7 @@ decorator-based API similar to popular event-driven frameworks, allowing
 developers to focus on behavior rather than boilerplate.
 
 #### Key Features
+
 - Minimal setup, easy to extend
 - Event-driven API using async/await
 - Clean command registration
@@ -28,6 +29,7 @@ developers to focus on behavior rather than boilerplate.
 # Quickstart
 
 **Requirements**
+
 - Python 3.10+
 
 ```
@@ -35,38 +37,45 @@ pip install matrix-python
 ```
 
 If you plan on contributing to matrix.py, we recommend to install the development libraries:
+
 ```
 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.
-
+*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.
 
 ```python
 from matrix import Bot, Context
 
-bot = Bot(config="config.yml")
+bot = Bot()
 
 
 @bot.command("ping")
 async def ping(ctx: Context):
-    await ctx.send("Pong!")
+    await ctx.reply("Pong!")
 
 
-bot.start()
+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)
 
 # Contributing
-We welcome everyone to contribute! 
+
+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!
+- 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).
+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).
 
 # License
+
 matrix.py is released under [GPL-3.0](https://opensource.org/license/gpl-3-0)

{matrix_python-1.4.1a0 → matrix_python-1.4.3a0}/examples/checks.py

@@ -1,7 +1,7 @@
 from matrix import Bot, Context
 from matrix.errors import CheckError
 
-bot = Bot(config="config.yaml")
+bot = Bot()
 
 allowed_users = {"@alice:matrix.org", "@bob:matrix.org"}
 
@@ -23,4 +23,4 @@ async def permission_error_handler(ctx: Context, error: CheckError) -> None:
     await ctx.reply(f"Access denied: {error}")
 
 
-bot.start()
+bot.start(config="config.yaml")

{matrix_python-1.4.1a0 → matrix_python-1.4.3a0}/examples/cooldown.py

@@ -1,7 +1,7 @@
 from matrix import Bot, Context, cooldown
 from matrix.errors import CooldownError
 
-bot = Bot(config="config.yaml")
+bot = Bot()
 
 
 # Invoke by using !hello
@@ -27,4 +27,4 @@ async def cooldown_function(ctx: Context, error: CooldownError) -> None:
     await ctx.reply(f"⏳ Try again in {error.retry:.1f}s")
 
 
-bot.start()
+bot.start(config="config.yaml")

{matrix_python-1.4.1a0 → matrix_python-1.4.3a0}/examples/error_handling.py

@@ -1,7 +1,7 @@
 from matrix import Bot, Context
 from matrix.errors import CommandNotFoundError, MissingArgumentError
 
-bot = Bot(config="config.yaml")
+bot = Bot()
 
 
 @bot.error(CommandNotFoundError)
@@ -30,4 +30,4 @@ async def command_error(ctx: Context, error: MissingArgumentError) -> None:
     await ctx.reply(f"{error}")
 
 
-bot.start()
+bot.start(config="config.yaml")

{matrix_python-1.4.1a0 → matrix_python-1.4.3a0}/examples/extension.py

@@ -34,12 +34,14 @@ async def divide_error(ctx: Context, error):
 
 
 """
+# bot.py
+
 from matrix import Bot
 from math_extension import extension as math_extension
 
-bot = Bot(config="config.yaml")
+bot = Bot()
 
 
 bot.load_extension(math_extension)
-bot.start()
+bot.start(config="config.yaml")
 """

{matrix_python-1.4.1a0 → matrix_python-1.4.3a0}/examples/ping.py

@@ -1,6 +1,6 @@
 from matrix import Bot, Context
 
-bot = Bot(config="config.yaml")
+bot = Bot()
 
 
 @bot.command("ping")
@@ -8,4 +8,4 @@ async def ping(ctx: Context) -> None:
     await ctx.reply("Pong!")
 
 
-bot.start()
+bot.start(config="config.yaml")

matrix_python-1.4.3a0/examples/reaction.py

@@ -0,0 +1,39 @@
+from asyncio import Event
+from nio import MatrixRoom, RoomMessageText, ReactionEvent
+from matrix import Bot, Room, Message
+
+bot = Bot()
+
+
+@bot.event
+async def on_message(room: Room, event: RoomMessageText) -> None:
+    """
+    This function listens for new messages in a room and reacts based
+    on the message content.
+    """
+    message = await room.fetch_message(event.event_id)
+
+    if message.body.lower().startswith("thanks"):
+        await message.react("🙏")
+
+    if message.body.lower().startswith("hello"):
+        # Can also react with a text message instead of emoji
+        await message.react("hi")
+
+    if message.body.lower().startswith("❤️"):
+        await message.react("❤️")
+
+
+@bot.event
+async def on_react(room: Room, event: ReactionEvent) -> None:
+    """
+    This function listens for new member reaction to messages in a room,
+    and reacts based on the reaction emoji.
+    """
+    message = await room.fetch_message(event.reacts_to)
+
+    if message.key == "🙏":
+        await message.react("❤️")
+
+
+bot.start(config="config.yaml")

{matrix_python-1.4.1a0 → matrix_python-1.4.3a0}/examples/scheduler.py

@@ -1,6 +1,6 @@
 from matrix import Bot, Context
 
-bot = Bot(config="config.yaml")
+bot = Bot()
 
 room_id = "!your_room_id:matrix.org"  # Replace with your room ID
 
@@ -15,19 +15,19 @@ async def ping(ctx: Context) -> None:
 @bot.schedule("* * * * *")
 async def scheduled_task() -> None:
     # This task runs every minute.
-    await room.send(message="Scheduled ping!")
+    await room.send("Scheduled ping!")
 
 
 @bot.schedule("0 * * * *")
 async def hourly_task() -> None:
     # This task runs every hour.
-    await room.send(message="This is your hourly update!")
+    await room.send("This is your hourly update!")
 
 
 @bot.schedule("0 9 * * 1-5")
 async def weekday_morning_task() -> None:
     # This task runs every weekday at 9 AM.
-    await room.send(message="Good morning! Here's your weekday update!")
+    await room.send("Good morning! Here's your weekday update!")
 
 
-bot.start()
+bot.start(config="config.yaml")

{matrix_python-1.4.1a0 → matrix_python-1.4.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 .message import Message
 from .extension import Extension
 
 __all__ = [
@@ -27,5 +28,6 @@ __all__ = [
     "HelpCommand",
     "cooldown",
     "Room",
+    "Message",
     "Extension",
 ]

{matrix_python-1.4.1a0 → matrix_python-1.4.3a0}/matrix/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.4.1a0'
-__version_tuple__ = version_tuple = (1, 4, 1, 'a0')
+__version__ = version = '1.4.3a0'
+__version_tuple__ = version_tuple = (1, 4, 3, 'a0')
 
-__commit_id__ = commit_id = 'gcd71354ad'
+__commit_id__ = commit_id = 'gba1ba5d3c'

{matrix_python-1.4.1a0 → matrix_python-1.4.3a0}/matrix/bot.py

@@ -28,29 +28,34 @@ class Bot(Registry):
     """
 
     def __init__(
-        self, *, config: Union[Config, str], help: Optional[HelpCommand] = None
+        self,
+        *,
+        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__)
 
-        super().__init__(self.__class__.__name__, prefix=self.config.prefix)
-
-        self.client: AsyncClient = AsyncClient(self.config.homeserver)
+        self._config: Config | None = None
+        self._client: AsyncClient | None = None
+        self._help: HelpCommand | None = help_
         self.extensions: dict[str, Extension] = {}
         self.scheduler: Scheduler = Scheduler()
         self.log: logging.Logger = logging.getLogger(__name__)
+        self.start_at: float | None = None
 
-        self.start_at: float | None = None  # unix timestamp
+    @property
+    def client(self) -> AsyncClient:
+        assert self._client is not None, "Bot has not been started."
+        return self._client
 
-        self.help: HelpCommand = help or DefaultHelpCommand(prefix=self.prefix)
-        self.register_command(self.help)
+    @property
+    def config(self) -> Config:
+        assert self._config is not None, "Bot has not been started."
+        return self._config
 
-        self.client.add_event_callback(self._on_matrix_event, Event)
-        self._auto_register_events()
+    @property
+    def help(self) -> HelpCommand:
+        assert self._help is not None, "Bot has not been started."
+        return self._help
 
     def _auto_register_events(self) -> None:
         for attr in dir(self):
@@ -192,7 +197,26 @@ class Bot(Registry):
 
     # ENTRYPOINT
 
-    def start(self) -> None:
+    def _load_config(self, config: Config | str) -> None:
+        if self._config is not None:
+            raise RuntimeError("Config is already loaded.")
+
+        if isinstance(config, str):
+            config = Config(config_path=config)
+        elif not isinstance(config, Config):
+            raise TypeError("config must be a Config instance or a config file path")
+
+        self._config = config
+        self._client = AsyncClient(config.homeserver)
+        self._help = self._help or DefaultHelpCommand()
+
+        self.prefix = config.prefix
+        self.register_command(self.help)
+
+        self.client.add_event_callback(self._on_matrix_event, Event)
+        self._auto_register_events()
+
+    def start(self, *, config: Config | str) -> None:
         """
         Synchronous entry point for running the bot.
 
@@ -201,6 +225,9 @@ class Bot(Registry):
         :func:`asyncio.run`, and ensures the client is closed gracefully
         on interruption.
         """
+        if config is not None:
+            self._load_config(config)
+
         try:
             asyncio.run(self.run())
         except KeyboardInterrupt:
@@ -235,10 +262,10 @@ class Bot(Registry):
 
     # MATRIX EVENTS
 
-    async def on_message(self, room: MatrixRoom, event: Event) -> None:
+    async def on_message(self, room: Room, event: Event) -> None:
         await self._process_commands(room, event)
 
-    async def _on_matrix_event(self, room: MatrixRoom, event: Event) -> None:
+    async def _on_matrix_event(self, matrix_room: MatrixRoom, event: Event) -> None:
         # ignore bot events
         if event.sender == self.client.user:
             return
@@ -248,6 +275,7 @@ class Bot(Registry):
             return
 
         try:
+            room = self.get_room(matrix_room.room_id)
             await self._dispatch_matrix_event(room, event)
         except Exception as error:
             await self._on_error(error)
@@ -257,14 +285,14 @@ class Bot(Registry):
         for handler in self._hook_handlers.get(event_name, []):
             await handler(*args, **kwargs)
 
-    async def _dispatch_matrix_event(self, room: MatrixRoom, event: Event) -> None:
+    async def _dispatch_matrix_event(self, room: Room, event: Event) -> None:
         """Fire all listeners registered for a named matrix event."""
         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:
+    async def _process_commands(self, room: Room, event: Event) -> None:
         """Parse and execute commands"""
         ctx = await self._build_context(room, event)
 
@@ -276,7 +304,7 @@ class Bot(Registry):
             await self._on_command(ctx)
             await ctx.command(ctx)
 
-    async def _build_context(self, matrix_room: MatrixRoom, event: Event) -> Context:
+    async def _build_context(self, matrix_room: Room, event: Event) -> Context:
         room = self.get_room(matrix_room.room_id)
         ctx = Context(bot=self, room=room, event=event)
         prefix = self.prefix or self.config.prefix

{matrix_python-1.4.1a0 → matrix_python-1.4.3a0}/matrix/message.py

@@ -1,5 +1,8 @@
-from typing import TYPE_CHECKING
-from nio import AsyncClient
+from typing import TYPE_CHECKING, Self
+
+from nio import AsyncClient, Event
+
+from matrix.types import Reaction
 from matrix.content import ReactionContent, EditContent
 from matrix.errors import MatrixError
 
@@ -10,28 +13,35 @@ if TYPE_CHECKING:
 class Message:
     """Represents a Matrix message with methods to interact with it."""
 
-    def __init__(
-        self, *, room: "Room", event_id: str, body: str | None, client: AsyncClient
-    ) -> None:
+    def __init__(self, *, room: "Room", event: Event, client: AsyncClient) -> None:
         self._room = room
-        self._event_id = event_id
-        self._body = body
+        self._matrix_event: Event = event
         self._client = client
 
+        self._body = getattr(self._matrix_event, "body", None)
+
+    def __repr__(self) -> str:
+        return f"<Message id={self.event_id!r} body={self.body!r}>"
+
     @property
     def room(self) -> "Room":
         """The room this message was sent in."""
         return self._room
 
     @property
-    def id(self) -> str:
-        """The event ID of this message."""
-        return self._event_id
+    def event(self) -> Event:
+        """The matrix event of this message"""
+        return self._matrix_event
+
+    @property
+    def client(self) -> AsyncClient:
+        """The Matrix client."""
+        return self._client
 
     @property
     def event_id(self) -> str:
-        """The event ID of this message (alias for id)."""
-        return self._event_id
+        """The event ID of this message."""
+        return str(self._matrix_event.event_id)
 
     @property
     def body(self) -> str | None:
@@ -39,9 +49,41 @@ class Message:
         return self._body
 
     @property
-    def client(self) -> AsyncClient:
-        """The Matrix client."""
-        return self._client
+    def key(self) -> str | None:
+        """The key of this message."""
+        return getattr(self._matrix_event, "key", None)
+
+    async def fetch_reactions(self) -> list[Reaction]:
+        """Fetch all reactions for this message.
+
+        Returns a dict mapping emoji to a list of sender IDs who reacted with it.
+
+        ## Example
+        ```python
+            @bot.command()
+            async def reactions(ctx: Context):
+                reactions = await ctx.message.fetch_reactions()
+
+                for emoji, senders in reactions.items():
+                    await ctx.reply(f"{emoji}: {len(senders)} reaction(s)")
+        ```
+        """
+        raw: dict[str, list[str]] = {}
+
+        try:
+            async for event in self.client.room_get_event_relations(
+                room_id=self.room.room_id,
+                event_id=self.event_id,
+            ):
+                emoji = getattr(event, "key", None)
+                sender = getattr(event, "sender", None)
+
+                if emoji and sender:
+                    raw.setdefault(emoji, []).append(sender)
+        except Exception as e:
+            raise MatrixError(f"Failed to fetch reactions: {e}")
+
+        return [Reaction(key=emoji, senders=senders) for emoji, senders in raw.items()]
 
     async def reply(self, body: str) -> "Message":
         """Reply to this message.
@@ -57,7 +99,7 @@ class Message:
         ```
         """
         try:
-            return await self.room.send_text(content=body, reply_to=self.id)
+            return await self.room.send_text(content=body, reply_to=self.event_id)
         except Exception as e:
             raise MatrixError(f"Failed to send reply: {e}")
 
@@ -72,7 +114,7 @@ class Message:
             await msg.react("👍")
         ```
         """
-        content = ReactionContent(event_id=self.id, emoji=emoji)
+        content = ReactionContent(event_id=self.event_id, emoji=emoji)
 
         try:
             await self.client.room_send(
@@ -95,7 +137,7 @@ class Message:
             await msg.edit("Hello world!")
         ```
         """
-        content = EditContent(new_body, original_event_id=self.id)
+        content = EditContent(new_body, original_event_id=self.event_id)
 
         try:
             await self.client.room_send(
@@ -122,10 +164,7 @@ class Message:
         try:
             await self.client.room_redact(
                 room_id=self.room.room_id,
-                event_id=self.id,
+                event_id=self.event_id,
             )
         except Exception as e:
             raise MatrixError(f"Failed to delete message: {e}")
-
-    def __repr__(self) -> str:
-        return f"<Message id={self.id!r} body={self.body!r}>"