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

matrix_python-1.4.4a0/.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.4a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrix-python
-Version: 1.4.1a0
+Version: 1.4.4a0
 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.4a0}/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.4a0}/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.4a0}/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.4a0}/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.4a0}/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.4a0}/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.4a0/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.4a0}/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.4a0}/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.4a0}/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.4a0'
+__version_tuple__ = version_tuple = (1, 4, 4, 'a0')
 
-__commit_id__ = commit_id = 'gcd71354ad'
+__commit_id__ = commit_id = 'gaaee53bc7'

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

@@ -3,7 +3,7 @@ import inspect
 import asyncio
 import logging
 
-from typing import Union, Optional, Any
+from typing import Optional, Any
 
 from nio import AsyncClient, Event, MatrixRoom
 
@@ -15,7 +15,12 @@ from .extension import Extension
 from .registry import Registry
 from .help import HelpCommand, DefaultHelpCommand
 from .scheduler import Scheduler
-from .errors import AlreadyRegisteredError, CommandNotFoundError, CheckError
+from .errors import (
+    AlreadyRegisteredError,
+    CommandNotFoundError,
+    CheckError,
+    RoomNotFoundError,
+)
 
 
 class Bot(Registry):
@@ -28,29 +33,36 @@ 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._config: Config | None = None
+        self._client: AsyncClient | None = None
+        self._synced: asyncio.Event = asyncio.Event()
+        self._help: HelpCommand | None = help_
 
-        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
 
-        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):
@@ -70,10 +82,23 @@ class Bot(Registry):
             except ValueError:
                 continue
 
-    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 get_room(self, room_id: str) -> Room | None:
+        """Retrieve a `Room` instance by its Matrix room ID.
+
+        Returns the `Room` object corresponding to `room_id` if it exists in
+        the client's known rooms. Returns `None` if the room cannot be found.
+
+        ## Example
+
+        ```python
+        room = bot.get_room("!abc123:matrix.org")
+        if room:
+            print(room.name)
+        ```
+        """
+        if matrix_room := self.client.rooms.get(room_id):
+            return Room(matrix_room=matrix_room, client=self.client)
+        return None
 
     def load_extension(self, extension: Extension) -> None:
         self.log.debug(f"Loading extension: '{extension.name}'")
@@ -192,7 +217,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 +245,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:
@@ -228,17 +275,26 @@ class Bot(Registry):
             login_resp = await self.client.login(self.config.password)
             self.log.info("logged in: %s", login_resp)
 
-        self.scheduler.start()
+        sync_task = asyncio.create_task(self.client.sync_forever(timeout=30_000))
 
+        await self._wait_until_synced()
         await self._on_ready()
-        await self.client.sync_forever(timeout=30_000)
+
+        self.scheduler.start()
+        await sync_task
+
+    async def _wait_until_synced(self) -> None:
+        await self._synced.wait()
 
     # 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:
+        if not self._synced.is_set():
+            self._synced.set()
+
         # ignore bot events
         if event.sender == self.client.user:
             return
@@ -248,6 +304,11 @@ class Bot(Registry):
             return
 
         try:
+            room = self.get_room(matrix_room.room_id)
+
+            if not room:
+                raise RoomNotFoundError(f"Room '{matrix_room.room_id}' not found.")
+
             await self._dispatch_matrix_event(room, event)
         except Exception as error:
             await self._on_error(error)
@@ -257,14 +318,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,8 +337,12 @@ 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)
+
+        if not room:
+            raise RoomNotFoundError(f"Room '{matrix_room.room_id}' not found.")
+
         ctx = Context(bot=self, room=room, event=event)
         prefix = self.prefix or self.config.prefix
 

{matrix_python-1.4.1a0 → matrix_python-1.4.4a0}/matrix/errors.py

@@ -13,6 +13,10 @@ class MatrixError(Exception):
     pass
 
 
+class RoomNotFoundError(MatrixError):
+    pass
+
+
 class RegistryError(MatrixError):
     pass
 

{matrix_python-1.4.1a0 → matrix_python-1.4.4a0}/matrix/extension.py

@@ -17,7 +17,20 @@ class Extension(Registry):
         self._on_load: Optional[Callable] = None
         self._on_unload: Optional[Callable] = None
 
-    def get_room(self, room_id: str) -> Room:
+    def get_room(self, room_id: str) -> Room | None:
+        """Retrieve a `Room` instance by its Matrix room ID.
+
+        Returns the `Room` object corresponding to `room_id` if it exists in
+        the client's known rooms. Returns `None` if the room cannot be found.
+
+        ## Example
+
+        ```python
+        room = extension.get_room("!abc123:matrix.org")
+        if room:
+            print(room.name)
+        ```
+        """
         if self.bot is None:
             raise RuntimeError("Extension is not loaded")
         return self.bot.get_room(room_id)