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

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

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

matrix_python-1.0.4a0/examples/README.md

@@ -0,0 +1,27 @@
+## Functionality Examples
+This directory contains multiple examples demonstrating how to use different
+features of the **[matrix.py]** library. Each example is self-contained and can be
+run independently.
+
+### How to Run the Examples
+- You will first need to update the environment variables in the [config.yaml](config.yaml)
+file with your Matrix credentials and desired settings.
+
+- To run any of the examples, navigate to the `examples` directory from your
+command line and execute the desired Python file using the command line.
+For instance:
+
+```bash
+python3 error_handling.py
+```
+
+Make sure you have all the necessary dependencies installed and configured
+before running the examples as instructed in the root [README file](../README.md).
+
+### Available Examples
+- [error_handling.py](error_handling.py): Demonstrates how to handle errors in commands.
+- [cooldown.py](cooldown.py): Shows how to implement cooldowns for commands.
+- [ping.py](ping.py): A simple ping command example.
+- [reaction.py](reaction.py): Example of handling reactions to messages.
+- [checks.py](checks.py): Demonstrates how to use checks for command execution.
+- [scheduler.py](scheduler.py): Shows how to schedule tasks.

{matrix_python-1.0.3a0 → matrix_python-1.0.4a0}/examples/checks.py

@@ -1,12 +1,13 @@
 from matrix import Bot, Context
+from matrix.errors import CheckError
 
-bot = Bot("examples/config.yaml")
+bot = Bot(config="config.yaml")
 
 allowed_users = {"@alice:matrix.org", "@bob:matrix.org"}
 
 
-@bot.command("secret")
-async def secret_command(ctx: Context):
+@bot.command(name="secret")
+async def secret_command(ctx: Context) -> None:
     await ctx.reply("🎉 Welcome to the secret club!")
 
 
@@ -14,8 +15,12 @@ async def secret_command(ctx: Context):
 async def is_allowed_user(ctx: Context) -> bool:
     if ctx.sender in allowed_users:
         return True
-    await ctx.reply("You do not have permission to use this command.")
     return False
 
 
+@secret_command.error(CheckError)
+async def permission_error_handler(ctx: Context, error: CheckError) -> None:
+    await ctx.reply(f"Access denied: {error}")
+
+
 bot.start()

matrix_python-1.0.4a0/examples/cooldown.py

@@ -0,0 +1,30 @@
+from matrix import Bot, Context, cooldown
+from matrix.errors import CooldownError
+
+bot = Bot(config="config.yaml")
+
+
+# Invoke by using !hello
+@cooldown(rate=2, period=10)
+@bot.command("hello")
+async def hello_command(ctx: Context) -> None:
+    await ctx.reply("Hello World.")
+
+
+@hello_command.error(CooldownError)
+async def hello_command_error_handler(ctx: Context, error: CooldownError) -> None:
+    await ctx.reply(f"⏳ Try again in {error.retry:.1f}s")
+
+
+# Invoke by using !cooldown_command
+@bot.command(cooldown=(1, 10))
+async def cooldown_command(ctx: Context) -> None:
+    await ctx.reply("This is limited to 1 uses per 10s per user.")
+
+
+@cooldown_command.error(CooldownError)
+async def cooldown_function(ctx: Context, error: CooldownError) -> None:
+    await ctx.reply(f"⏳ Try again in {error.retry:.1f}s")
+
+
+bot.start()

matrix_python-1.0.4a0/examples/error_handling.py

@@ -0,0 +1,33 @@
+from matrix import Bot, Context
+from matrix.errors import CommandNotFoundError, MissingArgumentError
+
+bot = Bot(config="config.yaml")
+
+
+@bot.error(CommandNotFoundError)
+async def global_error(error: CommandNotFoundError) -> None:
+    print(f"Global error handler {error}.")
+
+
+@bot.command("div")
+async def division(ctx: Context, a: int, b: int) -> None:
+    c = a / b
+    await ctx.reply(f"{a} / {b} = {c}")
+
+
+@division.error(ZeroDivisionError)
+async def div_error(ctx: Context, error: ZeroDivisionError) -> None:
+    await ctx.reply(f"Operation not allowed: {error}")
+
+
+@division.error(ValueError)
+async def val_error(ctx: Context, error: ValueError) -> None:
+    await ctx.reply(f"ValueError: {error}")
+
+
+@division.error(MissingArgumentError)
+async def command_error(ctx: Context, error: MissingArgumentError) -> None:
+    await ctx.reply(f"{error}")
+
+
+bot.start()

matrix_python-1.0.4a0/examples/ping.py

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

{matrix_python-1.0.3a0 → matrix_python-1.0.4a0}/examples/reaction.py

@@ -1,10 +1,11 @@
-from matrix import Bot
+from asyncio import Event
+from matrix import Bot, Room
 
-bot = Bot("examples/config.yaml")
+bot = Bot(config="config.yaml")
 
 
 @bot.event
-async def on_message(room, event):
+async def on_message(room: Room, event: Event) -> None:
     """
     This function listens for new messages in a room and reacts based
     on the message content.
@@ -22,7 +23,7 @@ async def on_message(room, event):
 
 
 @bot.event
-async def on_react(room, event):
+async def on_react(room: Room, event: Event) -> None:
     """
     This function listens for new member reaction to messages in a room,
     and reacts based on the reaction emoji.

{matrix_python-1.0.3a0 → matrix_python-1.0.4a0}/examples/scheduler.py

@@ -1,6 +1,6 @@
 from matrix import Bot, Context
 
-bot = Bot("examples/config.yaml")
+bot = Bot(config="config.yaml")
 
 room_id = "!your_room_id:matrix.org"  # Replace with your room ID
 
@@ -8,26 +8,25 @@ room = bot.get_room(room_id)
 
 
 @bot.command("ping")
-async def ping(ctx: Context):
-    print(f"{ctx.sender} invoked {ctx.body} in room {ctx.room_name}.")
+async def ping(ctx: Context) -> None:
     await ctx.reply("Pong!")
 
 
 @bot.schedule("* * * * *")
-async def scheduled_task():
-    print("This task runs every minute.")
+async def scheduled_task() -> None:
+    # This task runs every minute.
     await room.send(message="Scheduled ping!")
 
 
 @bot.schedule("0 * * * *")
-async def hourly_task():
-    print("This task runs every hour.")
+async def hourly_task() -> None:
+    # This task runs every hour.
     await room.send(message="This is your hourly update!")
 
 
 @bot.schedule("0 9 * * 1-5")
-async def weekday_morning_task():
-    print("This task runs every weekday at 9 AM.")
+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!")
 
 

{matrix_python-1.0.3a0 → matrix_python-1.0.4a0}/matrix/__init__.py

@@ -1,6 +1,6 @@
 """A simple, developer-friendly library to create powerful Matrix bots."""
 
-__version__ = "1.0.3-alpha"
+__version__ = "1.0.4-alpha"
 
 from .bot import Bot
 from .group import Group
@@ -9,6 +9,7 @@ from .context import Context
 from .command import Command
 from .help import HelpCommand
 from .checks import cooldown
+from .room import Room
 
 __all__ = [
     "Bot",
@@ -18,4 +19,5 @@ __all__ = [
     "Context",
     "HelpCommand",
     "cooldown",
+    "Room",
 ]

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

@@ -33,12 +33,12 @@ from .help import HelpCommand, DefaultHelpCommand
 from .scheduler import Scheduler
 
 from .errors import (
+    GroupAlreadyRegisteredError,
     AlreadyRegisteredError,
     CommandNotFoundError,
     CheckError,
 )
 
-
 Callback = Callable[..., Coroutine[Any, Any, Any]]
 GroupCallable = Callable[[Callable[..., Coroutine[Any, Any, Any]]], Group]
 ErrorCallback = Callable[[Exception], Coroutine]
@@ -192,7 +192,6 @@ class Bot:
         name: Optional[str] = None,
         *,
         description: Optional[str] = None,
-        prefix: Optional[str] = None,
         parent: Optional[str] = None,
         usage: Optional[str] = None,
         cooldown: Optional[tuple[int, float]] = None,
@@ -203,16 +202,13 @@ class Bot:
         The command name defaults to the function name unless
         explicitly provided.
 
-        :param name: The name of the command. If omitted, the function name is used.
-        :param description: A brief description of the command.
-        :param prefix: The command prefix. If omitted, the bot's default prefix is used.
-        :param parent: The parent command name for subcommands.
-        :param usage: A usage string describing command arguments.
-        :param cooldown: A tuple defining (max_calls, per_seconds) for rate limiting.
-        :raises TypeError: If the decorated function is not a coroutine.
-        :raises ValueError: If a command with the same name is registered.
-        :return: Decorator that registers the command handler.
-        :rtype: Callback
+        ## Example
+
+        ```python
+        @bot.command(description="Returns pong!")
+        async def ping(ctx):
+            await ctx.reply("Pong!")
+        ```
         """
 
         def wrapper(func: Callback) -> Command:
@@ -220,7 +216,7 @@ class Bot:
                 func,
                 name=name,
                 description=description,
-                prefix=prefix,
+                prefix=self.prefix,
                 parent=parent,
                 usage=usage,
                 cooldown=cooldown,
@@ -229,6 +225,52 @@ class Bot:
 
         return wrapper
 
+    def group(
+        self,
+        name: Optional[str] = None,
+        *,
+        description: Optional[str] = None,
+        parent: Optional[str] = None,
+        usage: Optional[str] = None,
+        cooldown: Optional[tuple[int, float]] = None,
+    ) -> GroupCallable:
+        """Decorator to register a coroutine function as a group handler.
+
+        The group name defaults to the function name unless
+        explicitly provided.
+
+        ## Example
+
+        ```python
+        @bot.group(description="Group of mathematical commands")
+        async def math(ctx):
+            await ctx.reply("You called !math")
+
+
+        @math.command()
+        async def add(ctx, a: int, b: int):
+            await ctx.reply(f"{a} + {b} = {a + b}")
+
+
+        @math.command()
+        async def subtract(ctx, a: int, b: int):
+            await ctx.reply(f"{a} - {b} = {a - b}")
+        """
+
+        def wrapper(func: Callback) -> Group:
+            group = Group(
+                func,
+                name=name,
+                description=description,
+                prefix=self.prefix,
+                parent=parent,
+                usage=usage,
+                cooldown=cooldown,
+            )
+            return self.register_group(group)
+
+        return wrapper
+
     def schedule(self, cron: str) -> Callable[..., Callback]:
         """
         Decorator to register a coroutine function as a scheduled task.
@@ -261,6 +303,14 @@ class Bot:
 
         return cmd
 
+    def register_group(self, group: Group) -> Group:
+        if group in self.commands:
+            raise GroupAlreadyRegisteredError(group)
+
+        self.commands[group.name] = group
+        self.log.debug("group '%s' registered", group)
+        return group
+
     def error(self, exception: Optional[type[Exception]] = None) -> Callable:
         """
         Decorator to register a custom error handler for commands.

{matrix_python-1.0.3a0 → matrix_python-1.0.4a0}/matrix/checks.py

@@ -14,7 +14,7 @@ def cooldown(rate: int, period: float) -> Callable:
     :type period: float
     """
 
-    def wrapper(cmd: Command) -> Command:
+    def wrapper(cmd: "Command") -> "Command":
         cmd.set_cooldown(rate, period)
         return cmd
 

{matrix_python-1.0.3a0 → matrix_python-1.0.4a0}/matrix/errors.py

@@ -3,7 +3,6 @@ import inspect
 
 if TYPE_CHECKING:
     from .command import Command  # pragma: no cover
-    from .error import Error  # pragam: no cover
     from .group import Group  # pragma: no cover
 
 Callback = Callable[..., Coroutine[Any, Any, Any]]

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

@@ -14,10 +14,28 @@ ErrorCallback = Callable[["Context", Exception], Coroutine[Any, Any, Any]]
 
 
 class Group(Command):
-    def __init__(self, callback: Callback, **kwargs: Any):
+    def __init__(
+        self,
+        callback: Callback,
+        *,
+        name: Optional[str] = None,
+        description: Optional[str] = None,
+        prefix: Optional[str] = None,
+        parent: Optional[str] = None,
+        usage: Optional[str] = None,
+        cooldown: Optional[tuple[int, float]] = None,
+    ):
         self.commands: Dict[str, Command] = {}
 
-        super().__init__(callback, **kwargs)
+        super().__init__(
+            callback,
+            name=name,
+            description=description,
+            prefix=prefix,
+            parent=parent,
+            usage=usage,
+            cooldown=cooldown,
+        )
 
     def _build_usage(self) -> str:
         return f"{self.prefix}{self.name} [subcommand]"

{matrix_python-1.0.3a0 → matrix_python-1.0.4a0}/matrix/help/pagination.py

@@ -1,6 +1,5 @@
 from typing import Optional, List, TypeVar, Generic
 
-
 T = TypeVar("T")
 
 

{matrix_python-1.0.3a0 → matrix_python-1.0.4a0}/matrix_python.egg-info/PKG-INFO

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

{matrix_python-1.0.3a0 → matrix_python-1.0.4a0}/matrix_python.egg-info/SOURCES.txt

@@ -9,10 +9,11 @@ pyproject.toml
 .github/workflows/publish.yml
 .github/workflows/scorecard.yml
 .github/workflows/tests.yml
+examples/README.md
 examples/checks.py
 examples/config.yaml
 examples/cooldown.py
-examples/error.py
+examples/error_handling.py
 examples/ping.py
 examples/reaction.py
 examples/scheduler.py
@@ -42,7 +43,6 @@ tests/test_command.py
 tests/test_config.py
 tests/test_context.py
 tests/test_group.py
-tests/test_help.py
 tests/test_message.py
 tests/test_room.py
 tests/help/test_default_help_command.py

{matrix_python-1.0.3a0 → matrix_python-1.0.4a0}/pyproject.toml

@@ -3,7 +3,7 @@ requires = ["setuptools>=64", "setuptools_scm>=8"]
 
 [project]
 name = "matrix-python"
-version = "1.0.3-alpha"
+version = "1.0.4-alpha"
 authors = [
     { name="Simon Roy" },
     { name=" Chris Dedman Rollet " }
@@ -41,4 +41,4 @@ dev = [
 
 [tool.setuptools]
 packages = ["matrix"]
-license-files = []
+license-files = []

matrix_python-1.0.3a0/examples/cooldown.py

@@ -1,31 +0,0 @@
-from matrix import Bot, Context, cooldown
-from matrix.errors import CooldownError
-
-bot = Bot("examples/config.yaml")
-
-
-@bot.command(cooldown=(2, 15))
-async def cooldown_command(ctx):
-    await ctx.reply("This is limited to 2 uses per 15s per user.")
-
-
-@cooldown_command.error(CooldownError)
-async def cooldown_error(ctx, error):
-    print(f"CooldownError invoked: Try again in {error.retry:.1f} seconds.")
-    await ctx.reply(f"⏳ Try again in {error.retry:.1f}s")
-
-
-@cooldown(2, 10)
-@bot.command("hi")
-async def hello(ctx: Context):
-    print(f"{ctx.sender} invoked {ctx.body} in room {ctx.room_name}.")
-    await ctx.reply("Hello World.")
-
-
-@hello.error(CooldownError)
-async def hello_error(ctx, error):
-    print(f"CooldownError invoked: Try again in {error.retry:.1f} seconds.")
-    await ctx.reply(f"⏳ Try again in {error.retry:.1f}s")
-
-
-bot.start()

matrix_python-1.0.3a0/examples/error.py

@@ -1,36 +0,0 @@
-from matrix import Bot, Context
-from matrix.errors import CommandNotFoundError, MissingArgumentError
-
-bot = Bot("examples/config.yaml")
-
-
-@bot.error(CommandNotFoundError)
-async def global_error(error):
-    print(f"Glable error handler {error}.")
-
-
-@bot.command("div")
-async def division(ctx: Context, a: int, b: int):
-    c = a / b
-    await ctx.reply(c)
-
-
-@division.error(ZeroDivisionError)
-async def div_error(ctx, error):
-    print(f"Operation Not Allowed: {error}")
-    await ctx.reply(f"Operation not allowed: {error}")
-
-
-@division.error(ValueError)
-async def val_error(ctx, error):
-    print(f"ValueError: {error}")
-    await ctx.reply(f"ValueError: {error}")
-
-
-@division.error(MissingArgumentError)
-async def command_error(ctx, error):
-    print(error)
-    await ctx.reply(error)
-
-
-bot.start()

matrix_python-1.0.3a0/examples/ping.py

@@ -1,12 +0,0 @@
-from matrix import Bot, Context
-
-bot = Bot("examples/config.yaml")
-
-
-@bot.command("ping")
-async def ping(ctx: Context):
-    print(f"{ctx.sender} invoked {ctx.body} in room {ctx.room_name}.")
-    await ctx.reply("Pong!")
-
-
-bot.start()