matrix-python 1.4.0a0__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.0a0 → matrix_python-1.4.3a0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: matrix-python
-Version: 1.4.0a0
+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.0a0 → 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.0a0 → 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.0a0 → 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.0a0 → 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.0a0 → 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.0a0 → 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.0a0 → 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.0a0 → 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.0a0 → 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.0a0'
-__version_tuple__ = version_tuple = (1, 4, 0, 'a0')
+__version__ = version = '1.4.3a0'
+__version_tuple__ = version_tuple = (1, 4, 3, 'a0')
 
-__commit_id__ = commit_id = 'g9a7d62be9'
+__commit_id__ = commit_id = 'gba1ba5d3c'

{matrix_python-1.4.0a0 → 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):
@@ -105,7 +110,7 @@ class Bot(Registry):
             )
 
         self.extensions[extension.name] = extension
-        extension.load()
+        extension.load(self)
         self.log.debug("loaded extension '%s'", extension.name)
 
     def unload_extension(self, ext_name: str) -> None:
@@ -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.0a0 → matrix_python-1.4.3a0}/matrix/extension.py

@@ -1,8 +1,10 @@
-import logging
 import inspect
+import logging
+from typing import Callable, Optional
 
-from typing import Any, Callable, Coroutine, Optional
+from matrix.protocols import BotLike
 from matrix.registry import Registry
+from matrix.room import Room
 
 logger = logging.getLogger(__name__)
 
@@ -10,10 +12,19 @@ logger = logging.getLogger(__name__)
 class Extension(Registry):
     def __init__(self, name: str, prefix: Optional[str] = None) -> None:
         super().__init__(name, prefix=prefix)
+
+        self.bot: Optional[BotLike] = None
         self._on_load: Optional[Callable] = None
         self._on_unload: Optional[Callable] = None
 
-    def load(self) -> None:
+    def get_room(self, room_id: str) -> Room:
+        if self.bot is None:
+            raise RuntimeError("Extension is not loaded")
+        return self.bot.get_room(room_id)
+
+    def load(self, bot: BotLike) -> None:
+        self.bot = bot
+
         if self._on_load:
             self._on_load()
 
@@ -35,6 +46,8 @@ class Extension(Registry):
         return func
 
     def unload(self) -> None:
+        self.bot = None
+
         if self._on_unload:
             self._on_unload()