newsfile

Add a `self` parameter to each method signature in the module api
documentation. This makes them easier to copy-paste, and more accurately
conveys that Synapse expects them to be methods, rather than static
functions.

changelog.d/19112.doc

@@ -0,0 +1 @@
+Add a `self` parameter to each method in the ModuleApi documentation to make them easier to copy-paste.

docs/modules/account_data_callbacks.md

@@ -14,6 +14,7 @@ _First introduced in Synapse v1.57.0_
 
 ```python
 async def on_account_data_updated(
+    self,
     user_id: str,
     room_id: Optional[str],
     account_data_type: str,

docs/modules/account_validity_callbacks.md

@@ -12,7 +12,10 @@ The available account validity callbacks are:
 _First introduced in Synapse v1.39.0_
 
 ```python
-async def is_user_expired(user: str) -> Optional[bool]
+async def is_user_expired(
+    self,
+    user: str,
+) -> Optional[bool]
 ```
 
 Called when processing any authenticated request (except for logout requests). The module
@@ -34,7 +37,10 @@ any of the subsequent implementations of this callback.
 _First introduced in Synapse v1.39.0_
 
 ```python
-async def on_user_registration(user: str) -> None
+async def on_user_registration(
+    self,
+    user: str,
+) -> None
 ```
 
 Called after successfully registering a user, in case the module needs to perform extra
@@ -48,7 +54,12 @@ If multiple modules implement this callback, Synapse runs them all in order.
 _First introduced in Synapse v1.98.0_
 
 ```python
-async def on_user_login(user_id: str, auth_provider_type: str, auth_provider_id: str) -> None
+async def on_user_login(
+    self,
+    user_id: str,
+    auth_provider_type: str,
+    auth_provider_id: str,
+) -> None
 ```
 
 Called after successfully login or registration of a user for cases when module needs to perform extra operations after auth.

docs/modules/add_extra_fields_to_client_events_unsigned.md

@@ -18,6 +18,7 @@ The callback should be of the form
 
 ```python
 async def add_field_to_unsigned(
+    self,
     event: EventBase,
 ) -> JsonDict:
 ```

docs/modules/background_update_controller_callbacks.md

@@ -20,7 +20,12 @@ The available background update controller callbacks are:
 _First introduced in Synapse v1.49.0_
 
 ```python
-def on_update(update_name: str, database_name: str, one_shot: bool) -> AsyncContextManager[int]
+def on_update(
+    self,
+    update_name: str,
+    database_name: str,
+    one_shot: bool,
+) -> AsyncContextManager[int]
 ```
 
 Called when about to do an iteration of a background update. The module is given the name
@@ -46,7 +51,11 @@ This callback is required when registering any other background update controlle
 _First introduced in Synapse v1.49.0_
 
 ```python
-async def default_batch_size(update_name: str, database_name: str) -> int
+async def default_batch_size(
+    self,
+    update_name: str,
+    database_name: str,
+) -> int
 ```
 
 Called before the first iteration of a background update, with the name of the update and
@@ -60,7 +69,11 @@ If this callback is not defined, Synapse will use a default value of 100.
 _First introduced in Synapse v1.49.0_
 
 ```python
-async def min_batch_size(update_name: str, database_name: str) -> int
+async def min_batch_size(
+    self,
+    update_name: str,
+    database_name: str,
+) -> int
 ```
 
 Called before running a new batch for a background update, with the name of the update and

docs/modules/media_repository_callbacks.md

@@ -11,7 +11,10 @@ The available media repository callbacks are:
 _First introduced in Synapse v1.132.0_
 
 ```python
-async def get_media_config_for_user(user_id: str) -> Optional[JsonDict]
+async def get_media_config_for_user(
+    self,
+    user_id: str,
+) -> Optional[JsonDict]
 ```
 
 **<span style="color:red">
@@ -41,7 +44,11 @@ If no module returns a non-`None` value then the default media config will be re
 _First introduced in Synapse v1.132.0_
 
 ```python
-async def is_user_allowed_to_upload_media_of_size(user_id: str, size: int) -> bool
+async def is_user_allowed_to_upload_media_of_size(
+    self,
+    user_id: str,
+    size: int,
+) -> bool
 ```
 
 **<span style="color:red">
@@ -70,7 +77,11 @@ implementations of this callback.
 _First introduced in Synapse v1.139.0_
 
 ```python
-async def get_media_upload_limits_for_user(user_id: str, size: int) -> Optional[List[synapse.module_api.MediaUploadLimit]]
+async def get_media_upload_limits_for_user(
+    self,
+    user_id: str,
+    size: int,
+) -> Optional[List[synapse.module_api.MediaUploadLimit]]
 ```
 
 **<span style="color:red">
@@ -105,7 +116,13 @@ will be used.
 _First introduced in Synapse v1.139.0_
 
 ```python
-async def on_media_upload_limit_exceeded(user_id: str, limit: synapse.module_api.MediaUploadLimit, sent_bytes: int, attempted_bytes: int) -> None
+async def on_media_upload_limit_exceeded(
+    self,
+    user_id: str,
+    limit: synapse.module_api.MediaUploadLimit,
+    sent_bytes: int,
+    attempted_bytes: int,
+) -> None
 ```
 
 **<span style="color:red">

docs/modules/password_auth_provider_callbacks.md

@@ -20,6 +20,7 @@ callbacks, which should be of the following form:
 
 ```python
 async def check_auth(
+    self,
     user: str,
     login_type: str,
     login_dict: "synapse.module_api.JsonDict",
@@ -64,6 +65,7 @@ _First introduced in Synapse v1.46.0_
 
 ```python
 async def check_3pid_auth(
+    self,
     medium: str, 
     address: str,
     password: str,
@@ -97,9 +99,10 @@ _First introduced in Synapse v1.46.0_
 
 ```python
 async def on_logged_out(
+    self,
     user_id: str,
     device_id: Optional[str],
-    access_token: str
+    access_token: str,
 ) -> None
 ``` 
 Called during a logout request for a user. It is passed the qualified user ID, the ID of the
@@ -117,6 +120,7 @@ _First introduced in Synapse v1.52.0_
 
 ```python
 async def get_username_for_registration(
+    self,
     uia_results: Dict[str, Any],
     params: Dict[str, Any],
 ) -> Optional[str]
@@ -178,6 +182,7 @@ _First introduced in Synapse v1.54.0_
 
 ```python
 async def get_displayname_for_registration(
+    self,
     uia_results: Dict[str, Any],
     params: Dict[str, Any],
 ) -> Optional[str]
@@ -205,7 +210,12 @@ the username will be used (e.g. `alice` if the user being registered is `@alice:
 _First introduced in Synapse v1.53.0_
 
 ```python
-async def is_3pid_allowed(self, medium: str, address: str, registration: bool) -> bool
+async def is_3pid_allowed(
+    self,
+    medium: str,
+    address: str,
+    registration: bool,
+) -> bool
 ```
 
 Called when attempting to bind a third-party identifier (i.e. an email address or a phone

docs/modules/presence_router_callbacks.md

@@ -22,6 +22,7 @@ _First introduced in Synapse v1.42.0_
 
 ```python 
 async def get_users_for_states(
+    self,
     state_updates: Iterable["synapse.api.UserPresenceState"],
 ) -> Dict[str, Set["synapse.api.UserPresenceState"]]
 ```
@@ -44,7 +45,8 @@ _First introduced in Synapse v1.42.0_
 
 ```python
 async def get_interested_users(
-    user_id: str
+    self,
+    user_id: str,
 ) -> Union[Set[str], "synapse.module_api.PRESENCE_ALL_USERS"]
 ```
 **Requires** `get_users_for_states` to also be registered

docs/modules/ratelimit_callbacks.md

@@ -11,7 +11,11 @@ The available ratelimit callbacks are:
 _First introduced in Synapse v1.132.0_
 
 ```python
-async def get_ratelimit_override_for_user(user: str, limiter_name: str) -> Optional[synapse.module_api.RatelimitOverride]
+async def get_ratelimit_override_for_user(
+    self,
+    user: str,
+    limiter_name: str,
+) -> Optional[synapse.module_api.RatelimitOverride]
 ```
 
 **<span style="color:red">

docs/modules/spam_checker_callbacks.md

@@ -15,7 +15,10 @@ _First introduced in Synapse v1.37.0_
 _Changed in Synapse v1.60.0: `synapse.module_api.NOT_SPAM` and `synapse.module_api.errors.Codes` can be returned by this callback. Returning a boolean or a string is now deprecated._ 
 
 ```python
-async def check_event_for_spam(event: "synapse.module_api.EventBase") -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", str, bool]
+async def check_event_for_spam(
+    self,
+    event: "synapse.module_api.EventBase",
+) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", str, bool]
 ```
 
 Called when receiving an event from a client or via federation. The callback must return one of:
@@ -41,7 +44,12 @@ _First introduced in Synapse v1.37.0_
 _Changed in Synapse v1.61.0: `synapse.module_api.NOT_SPAM` and `synapse.module_api.errors.Codes` can be returned by this callback. Returning a boolean is now deprecated._ 
 
 ```python
-async def user_may_join_room(user: str, room: str, is_invited: bool) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", bool]
+async def user_may_join_room(
+    self,
+    user: str,
+    room: str,
+    is_invited: bool,
+) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", bool]
 ```
 
 Called when a user is trying to join a room. The user is represented by their Matrix user ID (e.g.
@@ -73,7 +81,12 @@ _First introduced in Synapse v1.37.0_
 _Changed in Synapse v1.62.0: `synapse.module_api.NOT_SPAM` and `synapse.module_api.errors.Codes` can be returned by this callback. Returning a boolean is now deprecated._ 
 
 ```python
-async def user_may_invite(inviter: str, invitee: str, room_id: str) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", bool]
+async def user_may_invite(
+    self,
+    inviter: str,
+    invitee: str,
+    room_id: str,
+) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", bool]
 ```
 
 Called when processing an invitation, both when one is created locally or when
@@ -104,7 +117,10 @@ this callback.
 _First introduced in Synapse v1.133.0_
 
 ```python
-async def federated_user_may_invite(event: "synapse.events.EventBase") -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", bool]
+async def federated_user_may_invite(
+    self,
+    event: "synapse.events.EventBase",
+) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", bool]
 ```
 
 Called when processing an invitation received over federation. Unlike `user_may_invite`,
@@ -135,6 +151,7 @@ _Changed in Synapse v1.62.0: `synapse.module_api.NOT_SPAM` and `synapse.module_a
 
 ```python
 async def user_may_send_3pid_invite(
+    self,
     inviter: str,
     medium: str,
     address: str,
@@ -192,7 +209,11 @@ _Changed in Synapse v1.62.0: `synapse.module_api.NOT_SPAM` and `synapse.module_a
 _Changed in Synapse v1.132.0: Added the `room_config` argument. Callbacks that only expect a single `user_id` argument are still supported._
 
 ```python
-async def user_may_create_room(user_id: str, room_config: synapse.module_api.JsonDict) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", bool]
+async def user_may_create_room(
+    self,
+    user_id: str,
+    room_config: synapse.module_api.JsonDict,
+) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", bool]
 ```
 
 Called when processing a room creation or room upgrade request.
@@ -229,7 +250,11 @@ _First introduced in Synapse v1.37.0_
 _Changed in Synapse v1.62.0: `synapse.module_api.NOT_SPAM` and `synapse.module_api.errors.Codes` can be returned by this callback. Returning a boolean is now deprecated._ 
 
 ```python
-async def user_may_create_room_alias(user_id: str, room_alias: "synapse.module_api.RoomAlias") -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", bool]
+async def user_may_create_room_alias(
+    self,
+    user_id: str,
+    room_alias: "synapse.module_api.RoomAlias",
+) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", bool]
 ```
 
 Called when trying to associate an alias with an existing room.
@@ -258,7 +283,11 @@ _First introduced in Synapse v1.37.0_
 _Changed in Synapse v1.62.0: `synapse.module_api.NOT_SPAM` and `synapse.module_api.errors.Codes` can be returned by this callback. Returning a boolean is now deprecated._ 
 
 ```python
-async def user_may_publish_room(user_id: str, room_id: str) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", bool]
+async def user_may_publish_room(
+    self,
+    user_id: str,
+    room_id: str,
+) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", bool]
 ```
 
 Called when trying to publish a room to the homeserver's public rooms directory.
@@ -284,7 +313,14 @@ this callback.
 _First introduced in Synapse v1.132.0_
 
 ```python
-async def user_may_send_state_event(user_id: str, room_id: str, event_type: str, state_key: str, content: JsonDict) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes"]
+async def user_may_send_state_event(
+    self,
+    user_id: str,
+    room_id: str,
+    event_type: str,
+    state_key: str,
+    content: JsonDict,
+) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes"]
 ```
 
 **<span style="color:red">
@@ -320,7 +356,11 @@ this callback.
 _First introduced in Synapse v1.37.0_
 
 ```python
-async def check_username_for_spam(user_profile: synapse.module_api.UserProfile, requester_id: str) -> bool
+async def check_username_for_spam(
+    self,
+    user_profile: synapse.module_api.UserProfile,
+    requester_id: str,
+) -> bool
 ```
 
 Called when computing search results in the user directory. The module must return a
@@ -352,6 +392,7 @@ _First introduced in Synapse v1.37.0_
 
 ```python
 async def check_registration_for_spam(
+    self,
     email_threepid: Optional[dict],
     username: Optional[str],
     request_info: Collection[Tuple[str, str]],
@@ -387,6 +428,7 @@ _Changed in Synapse v1.62.0: `synapse.module_api.NOT_SPAM` and `synapse.module_a
 
 ```python
 async def check_media_file_for_spam(
+    self,
     file_wrapper: "synapse.media.media_storage.ReadableFileWrapper",
     file_info: "synapse.media._base.FileInfo",
 ) -> Union["synapse.module_api.NOT_SPAM", "synapse.module_api.errors.Codes", bool]
@@ -415,7 +457,10 @@ this callback.
 _First introduced in Synapse v1.60.0_
 
 ```python
-async def should_drop_federated_event(event: "synapse.events.EventBase") -> bool
+async def should_drop_federated_event(
+    self,
+    event: "synapse.events.EventBase",
+) -> bool
 ```
 
 Called when checking whether a remote server can federate an event with us. **Returning
@@ -437,6 +482,7 @@ _First introduced in Synapse v1.87.0_
 
 ```python
 async def check_login_for_spam(
+    self,
     user_id: str,
     device_id: Optional[str],
     initial_display_name: Optional[str],

docs/modules/third_party_rules_callbacks.md

@@ -14,6 +14,7 @@ _First introduced in Synapse v1.39.0_
 
 ```python
 async def check_event_allowed(
+    self,
     event: "synapse.events.EventBase",
     state_events: "synapse.types.StateMap",
 ) -> Tuple[bool, Optional[dict]]
@@ -65,6 +66,7 @@ _First introduced in Synapse v1.39.0_
 
 ```python
 async def on_create_room(
+    self,
     requester: "synapse.types.Requester",
     request_content: dict,
     is_requester_admin: bool,
@@ -92,6 +94,7 @@ _First introduced in Synapse v1.39.0_
 
 ```python
 async def check_threepid_can_be_invited(
+    self,
     medium: str,
     address: str,
     state_events: "synapse.types.StateMap",
@@ -112,6 +115,7 @@ _First introduced in Synapse v1.39.0_
 
 ```python
 async def check_visibility_can_be_modified(
+    self,
     room_id: str,
     state_events: "synapse.types.StateMap",
     new_visibility: str,
@@ -133,6 +137,7 @@ _First introduced in Synapse v1.47.0_
 
 ```python
 async def on_new_event(
+    self,
     event: "synapse.events.EventBase",
     state_events: "synapse.types.StateMap",
 ) -> None:
@@ -161,7 +166,9 @@ _First introduced in Synapse v1.55.0_
 
 ```python
 async def check_can_shutdown_room(
-    user_id: str, room_id: str,
+    self,
+    user_id: str,
+    room_id: str,
 ) -> bool:
 ```
 
@@ -180,7 +187,9 @@ _First introduced in Synapse v1.55.0_
 
 ```python
 async def check_can_deactivate_user(
-    user_id: str, by_admin: bool,
+    self,
+    user_id: str,
+    by_admin: bool,
 ) -> bool:
 ```
 
@@ -204,6 +213,7 @@ _First introduced in Synapse v1.54.0_
 
 ```python
 async def on_profile_update(
+    self,
     user_id: str,
     new_profile: "synapse.module_api.ProfileInfo",
     by_admin: bool,
@@ -239,7 +249,10 @@ _First introduced in Synapse v1.54.0_
 
 ```python
 async def on_user_deactivation_status_changed(
-    user_id: str, deactivated: bool, by_admin: bool
+    self,
+    user_id: str,
+    deactivated: bool,
+    by_admin: bool,
 ) -> None:
 ```
 
@@ -264,7 +277,12 @@ features the same functionality. The only difference is in name.
 </span>**
 
 ```python
-async def on_threepid_bind(user_id: str, medium: str, address: str) -> None:
+async def on_threepid_bind(
+    self,
+    user_id: str,
+    medium: str,
+    address: str,
+) -> None:
 ```
 
 Called after creating an association between a local user and a third-party identifier
@@ -282,7 +300,12 @@ If multiple modules implement this callback, Synapse runs them all in order.
 _First introduced in Synapse v1.79.0_
 
 ```python
-async def on_add_user_third_party_identifier(user_id: str, medium: str, address: str) -> None:
+async def on_add_user_third_party_identifier(
+    self,
+    user_id: str,
+    medium: str,
+    address: str,
+) -> None:
 ```
 
 Called after successfully creating an association between a user and a third-party identifier
@@ -301,7 +324,12 @@ If multiple modules implement this callback, Synapse runs them all in order.
 _First introduced in Synapse v1.79.0_
 
 ```python
-async def on_remove_user_third_party_identifier(user_id: str, medium: str, address: str) -> None:
+async def on_remove_user_third_party_identifier(
+    self,
+    user_id: str,
+    medium: str,
+    address: str,
+) -> None:
 ```
 
 Called after successfully removing an association between a user and a third-party identifier

docs/modules/writing_a_module.md

@@ -48,7 +48,11 @@ Modules can register web resources onto Synapse's web server using the following
 API method:
 
 ```python
-def ModuleApi.register_web_resource(path: str, resource: IResource) -> None
+def ModuleApi.register_web_resource(
+    self,
+    path: str,
+    resource: IResource,
+) -> None
 ```
 
 The path is the full absolute path to register the resource at. For example, if you