matrix-python 1.4.12a0__tar.gz → 1.5.0a0__tar.gz

matrix_python-1.5.0a0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: PenguinBoi12
+type: Bug
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Additional context**
+Add any other context about the problem here.

matrix_python-1.5.0a0/.github/ISSUE_TEMPLATE/feature--good-first.md

@@ -0,0 +1,29 @@
+---
+name: 'Feature: Good First'
+about: 'This template is for good first issues '
+title: ''
+labels: good first issue
+assignees: ''
+type: Feature
+
+---
+
+Explain clearly what we want to add and why it's useful to add it. Give context when necessary.
+
+### Proposed API
+This is a proposed API. It does not necessarily mean it's the final API but it's a good place to start.
+
+```python
+Some code here
+```
+
+**Example**
+```python
+An example of usage of the feature
+```
+
+### Before opening a PR
+- Write unit tests
+- Run `mypy matrix/`
+- Run `pytest tests/`
+- Run `black .`

matrix_python-1.5.0a0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,21 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+type: Feature
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

{matrix_python-1.4.12a0 → matrix_python-1.5.0a0}/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2021 Sebastián Ramírez
+Copyright (c) 2025 Code Society Lab
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THE SOFTWARE.

{matrix_python-1.4.12a0/matrix_python.egg-info → matrix_python-1.5.0a0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: matrix-python
-Version: 1.4.12a0
+Version: 1.5.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>
 License: The MIT License (MIT)
         
-        Copyright (c) 2021 Sebastián Ramírez
+        Copyright (c) 2025 Code Society Lab
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
@@ -25,6 +25,7 @@ License: The MIT License (MIT)
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
         THE SOFTWARE.
+        
 Project-URL: Homepage, https://codesociety.xyz
 Project-URL: Source, https://github.com/Code-Society-Lab/matrixpy
 Project-URL: Issues, https://github.com/Code-Society-Lab/matrixpy/issues
@@ -34,15 +35,15 @@ Requires-Dist: matrix-nio==0.25.2
 Requires-Dist: logger
 Requires-Dist: PyYAML==6.0.3
 Requires-Dist: markdown==3.10.2
-Requires-Dist: APScheduler==3.11.2
+Requires-Dist: APScheduler==3.11.3
 Requires-Dist: envyaml==1.10.211231
 Provides-Extra: dev
-Requires-Dist: pytest==9.0.3; extra == "dev"
-Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
-Requires-Dist: black==26.3.1; extra == "dev"
-Requires-Dist: mypy==1.20.1; extra == "dev"
-Requires-Dist: types-PyYAML==6.0.12.20260408; extra == "dev"
-Requires-Dist: types-Markdown==3.10.2.20260408; extra == "dev"
+Requires-Dist: pytest==9.1.1; extra == "dev"
+Requires-Dist: pytest-asyncio==1.4.0; extra == "dev"
+Requires-Dist: black==26.5.1; extra == "dev"
+Requires-Dist: mypy==2.1.0; extra == "dev"
+Requires-Dist: types-PyYAML==6.0.12.20260518; extra == "dev"
+Requires-Dist: types-Markdown==3.10.2.20260518; extra == "dev"
 Provides-Extra: doc
 Requires-Dist: mkdocs==1.6.1; extra == "doc"
 Requires-Dist: mkdocs-material==9.7.6; extra == "doc"

matrix_python-1.5.0a0/docs/docs/reference/space.md

@@ -0,0 +1,15 @@
+# Space
+
+`Space` extends `Room` to represent a Matrix Space. It is returned by `Bot.get_space()` and `Bot.get_spaces()` instead of a plain `Room` whenever the room type is `m.space`.
+
+```python
+from matrix import Bot
+
+bot = Bot()
+
+space = bot.get_space("!space123:matrix.org")
+if space:
+    print(space.name)
+```
+
+::: matrix.space.Space

{matrix_python-1.4.12a0 → matrix_python-1.5.0a0}/docs/mkdocs.yml

@@ -109,6 +109,7 @@ nav:
       - Protocols: reference/protocols.md
       - Registry: reference/registry.md
       - Room: reference/room.md
+      - Space: reference/space.md
       - Scheduler: reference/scheduler.md
       - Types: reference/types.md
   - Examples:

{matrix_python-1.4.12a0 → matrix_python-1.5.0a0}/matrix/__init__.py

@@ -15,6 +15,7 @@ from .command import Command
 from .help import HelpCommand
 from .checks import cooldown
 from .room import Room
+from .space import Space
 from .message import Message
 from .extension import Extension
 
@@ -28,6 +29,7 @@ __all__ = [
     "HelpCommand",
     "cooldown",
     "Room",
+    "Space",
     "Message",
     "Extension",
 ]

{matrix_python-1.4.12a0 → matrix_python-1.5.0a0}/matrix/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.4.12a0'
-__version_tuple__ = version_tuple = (1, 4, 12, 'a0')
+__version__ = version = '1.5.0a0'
+__version_tuple__ = version_tuple = (1, 5, 0, 'a0')
 
-__commit_id__ = commit_id = 'gf7df60d6d'
+__commit_id__ = commit_id = 'g91a8b536b'

matrix_python-1.5.0a0/matrix/api.py

@@ -0,0 +1,35 @@
+from typing import Awaitable, TypeVar
+
+from nio import ErrorResponse, Response
+
+from matrix.errors import MatrixError
+
+T = TypeVar("T", bound=Response)
+
+
+async def matrix_call(coro: Awaitable[T], /, *, error_message: str) -> T:
+    """Await `coro`, translating any failure into a `MatrixError`.
+
+    matrix-nio's `AsyncClient` methods don't raise on API-level errors; they
+    return an `ErrorResponse` instead of raising. This wraps a single call so
+    both transport-level exceptions and nio `ErrorResponse` results become a
+    `MatrixError` carrying `error_message`.
+
+    ## Example
+
+    ```python
+    response = await matrix_call(
+        self.client.room_kick(room_id=self.room_id, user_id=user_id),
+        error_message="Failed to kick user",
+    )
+    ```
+    """
+    try:
+        response = await coro
+    except Exception as e:
+        raise MatrixError(f"{error_message}: {e}") from e
+
+    if isinstance(response, ErrorResponse):
+        raise MatrixError(f"{error_message}: {response}")
+
+    return response

{matrix_python-1.4.12a0 → matrix_python-1.5.0a0}/matrix/bot.py

@@ -7,7 +7,8 @@ from typing import Optional, Any
 
 from nio import AsyncClient, Event, MatrixRoom
 
-from .room import Room
+from .room import Room, make_room
+from .space import Space
 from .group import Group
 from .config import Config
 from .context import Context
@@ -21,6 +22,7 @@ from .errors import (
     CheckError,
     RoomNotFoundError,
 )
+from .api import matrix_call
 
 
 class Bot(Registry):
@@ -87,19 +89,79 @@ class Bot(Registry):
 
         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.
+        Returns a typed subclass if the room type is registered (e.g. `Space` for m.space rooms).
 
         ## 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 make_room(matrix_room, self.client)
         return None
 
+    def get_rooms(self) -> list[Room]:
+        """Retrieve a list of all rooms the bot is aware of.
+
+        This method returns a list of `Room` objects for all rooms currently
+        known to the client. This includes both regular rooms and spaces;
+        spaces are returned as `Space` instances.
+
+        ## Example
+
+        ```python
+        rooms = bot.get_rooms()
+
+        for room in rooms:
+            print(room.name)
+        ```
+        """
+        rooms = []
+
+        for matrix_room in self.client.rooms.values():
+            rooms.append(make_room(matrix_room, self.client))
+
+        return rooms
+
+    def get_space(self, space_id: str) -> Space | None:
+        """Retrieve a `Space` instance by its Matrix room ID.
+
+        Returns the `Space` object corresponding to `space_id` if it exists in
+        the client's known rooms and is a space. Returns `None` otherwise.
+
+        ## Example
+
+        ```python
+        space = bot.get_space("!space123:matrix.org")
+
+        if space:
+            print(space.name)
+        ```
+        """
+        room = self.get_room(space_id)
+        return room if isinstance(room, Space) else None
+
+    def get_spaces(self) -> list[Space]:
+        """Retrieve a list of all spaces the bot is aware of.
+
+        This method returns a list of `Space` objects for all rooms currently
+        known to the client that are identified as spaces.
+
+        ## Example
+
+        ```python
+        spaces = bot.get_spaces()
+
+        for space in spaces:
+            print(space.name)
+        ```
+        """
+        return [room for room in self.get_rooms() if isinstance(room, Space)]
+
     def load_extension(self, extension: Extension) -> None:
         self.log.debug(f"Loading extension: '{extension.name}'")
 
@@ -267,7 +329,10 @@ class Bot(Registry):
         if self.config.token:
             self.client.access_token = self.config.token
         else:
-            login_resp = await self.client.login(self.config.password)
+            login_resp = await matrix_call(
+                self.client.login(self.config.password),
+                error_message="Failed to log in",
+            )
             self.log.info("logged in: %s", login_resp)
 
         sync_task = asyncio.create_task(self.client.sync_forever(timeout=30_000))

{matrix_python-1.4.12a0 → matrix_python-1.5.0a0}/matrix/message.py

@@ -5,6 +5,7 @@ from nio import AsyncClient, Event
 from matrix.types import Reaction
 from matrix.content import ReactionContent, EditContent
 from matrix.errors import MatrixError
+from matrix.api import matrix_call
 
 if TYPE_CHECKING:
     from .room import Room  # pragma: no cover
@@ -116,14 +117,14 @@ class Message:
         """
         content = ReactionContent(event_id=self.event_id, emoji=emoji)
 
-        try:
-            await self.client.room_send(
+        await matrix_call(
+            self.client.room_send(
                 room_id=self.room.room_id,
                 message_type="m.reaction",
                 content=content.build(),
-            )
-        except Exception as e:
-            raise MatrixError(f"Failed to add reaction: {e}")
+            ),
+            error_message="Failed to add reaction",
+        )
 
     async def edit(self, new_body: str) -> None:
         """Updates the message content to the new text.
@@ -139,19 +140,21 @@ class Message:
         """
         content = EditContent(new_body, original_event_id=self.event_id)
 
-        try:
-            await self.client.room_send(
+        await matrix_call(
+            self.client.room_send(
                 room_id=self.room.room_id,
                 message_type="m.room.message",
                 content=content.build(),
-            )
-            self._body = new_body
-        except Exception as e:
-            raise MatrixError(f"Failed to edit message: {e}")
+            ),
+            error_message="Failed to edit message",
+        )
+        self._body = new_body
 
-    async def delete(self) -> None:
+    async def delete(self, reason: str | None = None) -> None:
         """Removes the message content from the room. This action cannot be undone.
 
+        Optionally provide a reason that will be visible to room moderators.
+
         ## Example
 
         ```python
@@ -159,12 +162,16 @@ class Message:
         async def oops(ctx: Context):
             msg = await ctx.reply("Secret info!")
             await msg.delete()
+
+        # Delete with a reason
+        await message.delete(reason="Violated room rules")
         ```
         """
-        try:
-            await self.client.room_redact(
+        await matrix_call(
+            self.client.room_redact(
                 room_id=self.room.room_id,
                 event_id=self.event_id,
-            )
-        except Exception as e:
-            raise MatrixError(f"Failed to delete message: {e}")
+                reason=reason,
+            ),
+            error_message="Failed to delete message",
+        )

{matrix_python-1.4.12a0 → matrix_python-1.5.0a0}/matrix/room.py

@@ -2,7 +2,7 @@ from typing import Any
 
 from nio import AsyncClient, MatrixRoom, Event
 
-from matrix.errors import MatrixError
+from matrix.api import matrix_call
 from matrix.message import Message
 from matrix.content import (
     BaseMessageContent,
@@ -17,10 +17,26 @@ from matrix.content import (
 )
 from matrix.types import File, Image, Audio, Video
 
+_registry: dict[str, type["Room"]] = {}
+
+
+def make_room(matrix_room: MatrixRoom, client: AsyncClient) -> "Room":
+    room_cls = _registry.get(str(matrix_room.room_type), Room)
+    return room_cls(matrix_room, client)
+
 
 class Room:
     """Represents a Matrix room and provides methods to interact with it."""
 
+    def __init_subclass__(cls, room_type: str | None = None, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        if room_type:
+            if room_type in _registry:
+                raise ValueError(
+                    f"Room type '{room_type}' is already registered by {_registry[room_type].__name__}"
+                )
+            _registry[room_type] = cls
+
     def __init__(self, matrix_room: MatrixRoom, client: AsyncClient) -> None:
         self._matrix_room: MatrixRoom = matrix_room
         self._client: AsyncClient = client
@@ -313,21 +329,21 @@ class Room:
 
     async def _send_payload(self, payload: BaseMessageContent) -> Message:
         """Send a BaseMessageContent payload and return a Message object."""
-        try:
-            resp = await self.client.room_send(
+        resp = await matrix_call(
+            self.client.room_send(
                 room_id=self.room_id,
                 message_type="m.room.message",
                 content=payload.build(),
-            )
-            event = await self.fetch_event(resp.event_id)
+            ),
+            error_message="Failed to send message",
+        )
+        event = await self.fetch_event(resp.event_id)
 
-            return Message(
-                room=self,
-                event=event,
-                client=self.client,
-            )
-        except Exception as e:
-            raise MatrixError(f"Failed to send message: {e}")
+        return Message(
+            room=self,
+            event=event,
+            client=self.client,
+        )
 
     async def fetch_event(self, event_id: str) -> Event:
         """Fetch a Matrix event by its ID.
@@ -338,14 +354,11 @@ class Room:
             print(event.sender)
         ```
         """
-        try:
-            response = await self.client.room_get_event(
-                room_id=self.room_id,
-                event_id=event_id,
-            )
-            return response.event
-        except Exception as e:
-            raise MatrixError(f"Failed to get event: {e}")
+        response = await matrix_call(
+            self.client.room_get_event(room_id=self.room_id, event_id=event_id),
+            error_message="Failed to get event",
+        )
+        return response.event
 
     async def fetch_message(self, event_id: str) -> Message:
         """Fetch a Message by its event ID.
@@ -363,6 +376,29 @@ class Room:
             client=self.client,
         )
 
+    async def mark_as_read(self, event_id: str) -> None:
+        """Send a read receipt for the given event.
+
+        Signals to other clients that the bot has read up to this event. Useful
+        for bots that process messages silently without sending a reply.
+
+        ## Example
+
+        ```python
+        @bot.event
+        async def on_message(room: Room, event: Event):
+            await room.mark_as_read(event.event_id)
+        ```
+        """
+        await matrix_call(
+            self.client.room_read_markers(
+                room_id=self.room_id,
+                fully_read_event=event_id,
+                read_event=event_id,
+            ),
+            error_message="Failed to mark as read",
+        )
+
     async def invite_user(self, user_id: str) -> None:
         """Invite a user to the room.
 
@@ -376,10 +412,10 @@ class Room:
         await room.invite_user("@alice:example.com")
         ```
         """
-        try:
-            await self.client.room_invite(room_id=self.room_id, user_id=user_id)
-        except Exception as e:
-            raise MatrixError(f"Failed to invite user: {e}")
+        await matrix_call(
+            self.client.room_invite(room_id=self.room_id, user_id=user_id),
+            error_message="Failed to invite user",
+        )
 
     async def ban_user(self, user_id: str, reason: str | None = None) -> None:
         """Ban a user from the room.
@@ -397,12 +433,10 @@ class Room:
         await room.ban_user("@spammer:example.com", reason="Spam and harassment")
         ```
         """
-        try:
-            await self.client.room_ban(
-                room_id=self.room_id, user_id=user_id, reason=reason
-            )
-        except Exception as e:
-            raise MatrixError(f"Failed to ban user: {e}")
+        await matrix_call(
+            self.client.room_ban(room_id=self.room_id, user_id=user_id, reason=reason),
+            error_message="Failed to ban user",
+        )
 
     async def unban_user(self, user_id: str) -> None:
         """Unban a user from the room.
@@ -417,10 +451,10 @@ class Room:
         await room.unban_user("@alice:example.com")
         ```
         """
-        try:
-            await self.client.room_unban(room_id=self.room_id, user_id=user_id)
-        except Exception as e:
-            raise MatrixError(f"Failed to unban user: {e}")
+        await matrix_call(
+            self.client.room_unban(room_id=self.room_id, user_id=user_id),
+            error_message="Failed to unban user",
+        )
 
     async def kick_user(self, user_id: str, reason: str | None = None) -> None:
         """Kick a user from the room.
@@ -439,9 +473,26 @@ class Room:
         await room.kick_user("@troublemaker:example.com", reason="Violating room rules")
         ```
         """
-        try:
-            await self.client.room_kick(
-                room_id=self.room_id, user_id=user_id, reason=reason
-            )
-        except Exception as e:
-            raise MatrixError(f"Failed to kick user: {e}")
+        await matrix_call(
+            self.client.room_kick(room_id=self.room_id, user_id=user_id, reason=reason),
+            error_message="Failed to kick user",
+        )
+
+    async def get_members(self) -> list[str]:
+        """Fetch the list of user IDs currently joined to the room.
+
+        This queries the Matrix server directly for the current membership,
+        which may include members not yet reflected in local room state.
+
+        ## Example
+
+        ```python
+        members = await room.get_members()
+        print(f"{len(members)} members: {', '.join(members)}")
+        ```
+        """
+        response = await matrix_call(
+            self.client.joined_members(self.room_id),
+            error_message="Failed to get members",
+        )
+        return [member.user_id for member in response.members]

matrix_python-1.5.0a0/matrix/space.py

@@ -0,0 +1,45 @@
+from typing import Self
+from matrix.room import Room, make_room
+
+
+class Space(Room, room_type="m.space"):
+    def get_children(self, depth: int = 1) -> list[Room | Self]:
+        """Return the child rooms and spaces of this space that the bot has joined.
+
+        Children the bot has not joined are silently omitted. Use `depth` to
+        recursively collect children of sub-spaces. `depth=1` returns direct
+        children only (default).
+
+        ## Example
+
+        ```python
+        space = bot.get_space("!space123:matrix.org")
+
+        for child in space.get_children():
+            print(child.name)
+
+        for child in space.get_children(depth=3):
+            print(child.name)
+        ```
+        """
+        children: list[Room | Self] = []
+
+        if depth < 0:
+            raise ValueError(f"depth must be a non-negative integer, got {depth}")
+
+        if depth == 0:
+            return []
+
+        for room_id in self.children:
+            matrix_room = self._client.rooms.get(room_id)
+
+            if not matrix_room:
+                continue
+
+            child = make_room(matrix_room, self._client)
+            children.append(child)
+
+            if isinstance(child, Space) and depth > 1:
+                children.extend(child.get_children(depth - 1))
+
+        return children