Merge pull request #686 from matrix-org/markjh/doc_strings

Use google style doc strings.

setup.cfg

@@ -17,3 +17,6 @@ ignore =
 [flake8]
 max-line-length = 90
 ignore = W503 ; W503 requires that binary operators be at the end, not start, of lines. Erik doesn't like it.
+
+[pep8]
+max-line-length = 90

synapse/handlers/_base.py

@@ -41,8 +41,9 @@ class BaseHandler(object):
     """
     Common base class for the event handlers.
 
-    :type store: synapse.storage.events.StateStore
+    Attributes:
-    :type state_handler: synapse.state.StateHandler
+        store (synapse.storage.events.StateStore):
+        state_handler (synapse.state.StateHandler):
     """
 
     def __init__(self, hs):
@@ -65,11 +66,12 @@ class BaseHandler(object):
         """ Returns dict of user_id -> list of events that user is allowed to
         see.
 
-        :param (str, bool) user_tuples: (user id, is_peeking) for each
+        Args:
-            user to be checked. is_peeking should be true if:
+            user_tuples (str, bool): (user id, is_peeking) for each user to be
-              * the user is not currently a member of the room, and:
+                checked. is_peeking should be true if:
-              * the user has not been a member of the room since the given
+                * the user is not currently a member of the room, and:
-                events
+                * the user has not been a member of the room since the
+                given events
         """
         forgotten = yield defer.gatherResults([
             self.store.who_forgot_in_room(
@@ -165,13 +167,16 @@ class BaseHandler(object):
         """
         Check which events a user is allowed to see
 
-        :param str user_id: user id to be checked
+        Args:
-        :param [synapse.events.EventBase] events: list of events to be checked
+            user_id(str): user id to be checked
-        :param bool is_peeking should be True if:
+            events([synapse.events.EventBase]): list of events to be checked
+            is_peeking(bool): should be True if:
               * the user is not currently a member of the room, and:
               * the user has not been a member of the room since the given
                 events
-        :rtype [synapse.events.EventBase]
+
+        Returns:
+            [synapse.events.EventBase]
         """
         types = (
             (EventTypes.RoomHistoryVisibility, ""),

synapse/handlers/auth.py

@@ -163,9 +163,13 @@ class AuthHandler(BaseHandler):
     def get_session_id(self, clientdict):
         """
         Gets the session ID for a client given the client dictionary
-        :param clientdict: The dictionary sent by the client in the request
+
-        :return: The string session ID the client sent. If the client did not
+        Args:
-                 send a session ID, returns None.
+            clientdict: The dictionary sent by the client in the request
+
+        Returns:
+            str|None: The string session ID the client sent. If the client did
+                not send a session ID, returns None.
         """
         sid = None
         if clientdict and 'auth' in clientdict:
@@ -179,9 +183,11 @@ class AuthHandler(BaseHandler):
         Store a key-value pair into the sessions data associated with this
         request. This data is stored server-side and cannot be modified by
         the client.
-        :param session_id: (string) The ID of this session as returned from check_auth
+
-        :param key: (string) The key to store the data under
+        Args:
-        :param value: (any) The data to store
+            session_id (string): The ID of this session as returned from check_auth
+            key (string): The key to store the data under
+            value (any): The data to store
         """
         sess = self._get_session_info(session_id)
         sess.setdefault('serverdict', {})[key] = value
@@ -190,9 +196,11 @@ class AuthHandler(BaseHandler):
     def get_session_data(self, session_id, key, default=None):
         """
         Retrieve data stored with set_session_data
-        :param session_id: (string) The ID of this session as returned from check_auth
+
-        :param key: (string) The key to store the data under
+        Args:
-        :param default: (any) Value to return if the key has not been set
+            session_id (string): The ID of this session as returned from check_auth
+            key (string): The key to store the data under
+            default (any): Value to return if the key has not been set
         """
         sess = self._get_session_info(session_id)
         return sess.setdefault('serverdict', {}).get(key, default)

synapse/handlers/federation.py

@@ -1703,13 +1703,15 @@ class FederationHandler(BaseHandler):
     def _check_signature(self, event, auth_events):
         """
         Checks that the signature in the event is consistent with its invite.
-        :param event (Event): The m.room.member event to check
-        :param auth_events (dict<(event type, state_key), event>)
 
-        :raises
+        Args:
-            AuthError if signature didn't match any keys, or key has been
+            event (Event): The m.room.member event to check
+            auth_events (dict<(event type, state_key), event>):
+
+        Raises:
+            AuthError: if signature didn't match any keys, or key has been
                 revoked,
-            SynapseError if a transient error meant a key couldn't be checked
+            SynapseError: if a transient error meant a key couldn't be checked
                 for revocation.
         """
         signed = event.content["third_party_invite"]["signed"]
@@ -1751,12 +1753,13 @@ class FederationHandler(BaseHandler):
         """
         Checks whether public_key has been revoked.
 
-        :param public_key (str): base-64 encoded public key.
+        Args:
-        :param url (str): Key revocation URL.
+            public_key (str): base-64 encoded public key.
+            url (str): Key revocation URL.
 
-        :raises
+        Raises:
-            AuthError if they key has been revoked.
+            AuthError: if they key has been revoked.
-            SynapseError if a transient error meant a key couldn't be checked
+            SynapseError: if a transient error meant a key couldn't be checked
                 for revocation.
         """
         try:

synapse/handlers/room_member.py

@@ -411,7 +411,7 @@ class RoomMemberHandler(BaseHandler):
             address (str): The third party identifier (e.g. "foo@example.com").
 
         Returns:
-            (str) the matrix ID of the 3pid, or None if it is not recognized.
+            str: the matrix ID of the 3pid, or None if it is not recognized.
         """
         try:
             data = yield self.hs.get_simple_http_client().get_json(
@@ -545,29 +545,29 @@ class RoomMemberHandler(BaseHandler):
         """
         Asks an identity server for a third party invite.
 
-        :param id_server (str): hostname + optional port for the identity server.
+        Args:
-        :param medium (str): The literal string "email".
+            id_server (str): hostname + optional port for the identity server.
-        :param address (str): The third party address being invited.
+            medium (str): The literal string "email".
-        :param room_id (str): The ID of the room to which the user is invited.
+            address (str): The third party address being invited.
-        :param inviter_user_id (str): The user ID of the inviter.
+            room_id (str): The ID of the room to which the user is invited.
-        :param room_alias (str): An alias for the room, for cosmetic
+            inviter_user_id (str): The user ID of the inviter.
-            notifications.
+            room_alias (str): An alias for the room, for cosmetic notifications.
-        :param room_avatar_url (str): The URL of the room's avatar, for cosmetic
+            room_avatar_url (str): The URL of the room's avatar, for cosmetic
-            notifications.
+                notifications.
-        :param room_join_rules (str): The join rules of the email
+            room_join_rules (str): The join rules of the email (e.g. "public").
-            (e.g. "public").
+            room_name (str): The m.room.name of the room.
-        :param room_name (str): The m.room.name of the room.
+            inviter_display_name (str): The current display name of the
-        :param inviter_display_name (str): The current display name of the
+                inviter.
-            inviter.
+            inviter_avatar_url (str): The URL of the inviter's avatar.
-        :param inviter_avatar_url (str): The URL of the inviter's avatar.
 
-        :return: A deferred tuple containing:
+        Returns:
-            token (str): The token which must be signed to prove authenticity.
+            A deferred tuple containing:
-            public_keys ([{"public_key": str, "key_validity_url": str}]):
+                token (str): The token which must be signed to prove authenticity.
-                public_key is a base64-encoded ed25519 public key.
+                public_keys ([{"public_key": str, "key_validity_url": str}]):
-            fallback_public_key: One element from public_keys.
+                    public_key is a base64-encoded ed25519 public key.
-            display_name (str): A user-friendly name to represent the invited
+                fallback_public_key: One element from public_keys.
-                user.
+                display_name (str): A user-friendly name to represent the invited
+                    user.
         """
 
         is_url = "%s%s/_matrix/identity/api/v1/store-invite" % (

synapse/handlers/sync.py

@@ -663,7 +663,8 @@ class SyncHandler(BaseHandler):
     def load_filtered_recents(self, room_id, sync_config, now_token,
                               since_token=None, recents=None, newly_joined_room=False):
         """
-        :returns a Deferred TimelineBatch
+        Returns:
+            a Deferred TimelineBatch
         """
         with Measure(self.clock, "load_filtered_recents"):
             filtering_factor = 2
@@ -830,8 +831,11 @@ class SyncHandler(BaseHandler):
         """
         Get the room state after the given event
 
-        :param synapse.events.EventBase event: event of interest
+        Args:
-        :return: A Deferred map from ((type, state_key)->Event)
+            event(synapse.events.EventBase): event of interest
+
+        Returns:
+            A Deferred map from ((type, state_key)->Event)
         """
         state = yield self.store.get_state_for_event(event.event_id)
         if event.is_state():
@@ -842,9 +846,13 @@ class SyncHandler(BaseHandler):
     @defer.inlineCallbacks
     def get_state_at(self, room_id, stream_position):
         """ Get the room state at a particular stream position
-        :param str room_id: room for which to get state
+
-        :param StreamToken stream_position: point at which to get state
+        Args:
-        :returns: A Deferred map from ((type, state_key)->Event)
+            room_id(str): room for which to get state
+            stream_position(StreamToken): point at which to get state
+
+        Returns:
+            A Deferred map from ((type, state_key)->Event)
         """
         last_events, token = yield self.store.get_recent_events_for_room(
             room_id, end_token=stream_position.room_key, limit=1,
@@ -865,15 +873,18 @@ class SyncHandler(BaseHandler):
         """ Works out the differnce in state between the start of the timeline
         and the previous sync.
 
-        :param str room_id
+        Args:
-        :param TimelineBatch batch: The timeline batch for the room that will
+            room_id(str):
-            be sent to the user.
+            batch(synapse.handlers.sync.TimelineBatch): The timeline batch for
-        :param sync_config
+                the room that will be sent to the user.
-        :param str since_token: Token of the end of the previous batch. May be None.
+            sync_config(synapse.handlers.sync.SyncConfig):
-        :param str now_token: Token of the end of the current batch.
+            since_token(str|None): Token of the end of the previous batch. May
-        :param bool full_state: Whether to force returning the full state.
+                be None.
+            now_token(str): Token of the end of the current batch.
+            full_state(bool): Whether to force returning the full state.
 
-        :returns A new event dictionary
+        Returns:
+             A deferred new event dictionary
         """
         # TODO(mjark) Check if the state events were received by the server
         # after the previous sync, since we need to include those state
@@ -945,11 +956,13 @@ class SyncHandler(BaseHandler):
         Check if the user has just joined the given room (so should
         be given the full state)
 
-        :param sync_config:
+        Args:
-        :param dict[(str,str), synapse.events.FrozenEvent] state_delta: the
+            sync_config(synapse.handlers.sync.SyncConfig):
-           difference in state since the last sync
+            state_delta(dict[(str,str), synapse.events.FrozenEvent]): the
+                difference in state since the last sync
 
-        :returns A deferred Tuple (state_delta, limited)
+        Returns:
+             A deferred Tuple (state_delta, limited)
         """
         join_event = state_delta.get((
             EventTypes.Member, sync_config.user.to_string()), None)

synapse/http/servlet.py

@@ -26,14 +26,19 @@ logger = logging.getLogger(__name__)
 def parse_integer(request, name, default=None, required=False):
     """Parse an integer parameter from the request string
 
-    :param request: the twisted HTTP request.
+    Args:
-    :param name (str): the name of the query parameter.
+        request: the twisted HTTP request.
-    :param default: value to use if the parameter is absent, defaults to None.
+        name (str): the name of the query parameter.
-    :param required (bool): whether to raise a 400 SynapseError if the
+        default (int|None): value to use if the parameter is absent, defaults
-        parameter is absent, defaults to False.
+            to None.
-    :return: An int value or the default.
+        required (bool): whether to raise a 400 SynapseError if the
-    :raises
+            parameter is absent, defaults to False.
-        SynapseError if the parameter is absent and required, or if the
+
+    Returns:
+        int|None: An int value or the default.
+
+    Raises:
+        SynapseError: if the parameter is absent and required, or if the
             parameter is present and not an integer.
     """
     if name in request.args:
@@ -53,14 +58,19 @@ def parse_integer(request, name, default=None, required=False):
 def parse_boolean(request, name, default=None, required=False):
     """Parse a boolean parameter from the request query string
 
-    :param request: the twisted HTTP request.
+    Args:
-    :param name (str): the name of the query parameter.
+        request: the twisted HTTP request.
-    :param default: value to use if the parameter is absent, defaults to None.
+        name (str): the name of the query parameter.
-    :param required (bool): whether to raise a 400 SynapseError if the
+        default (bool|None): value to use if the parameter is absent, defaults
-        parameter is absent, defaults to False.
+            to None.
-    :return: A bool value or the default.
+        required (bool): whether to raise a 400 SynapseError if the
-    :raises
+            parameter is absent, defaults to False.
-        SynapseError if the parameter is absent and required, or if the
+
+    Returns:
+        bool|None: A bool value or the default.
+
+    Raises:
+        SynapseError: if the parameter is absent and required, or if the
             parameter is present and not one of "true" or "false".
     """
 
@@ -88,15 +98,20 @@ def parse_string(request, name, default=None, required=False,
                  allowed_values=None, param_type="string"):
     """Parse a string parameter from the request query string.
 
-    :param request: the twisted HTTP request.
+    Args:
-    :param name (str): the name of the query parameter.
+        request: the twisted HTTP request.
-    :param default: value to use if the parameter is absent, defaults to None.
+        name (str): the name of the query parameter.
-    :param required (bool): whether to raise a 400 SynapseError if the
+        default (str|None): value to use if the parameter is absent, defaults
-        parameter is absent, defaults to False.
+            to None.
-    :param allowed_values (list): List of allowed values for the string,
+        required (bool): whether to raise a 400 SynapseError if the
-        or None if any value is allowed, defaults to None
+            parameter is absent, defaults to False.
-    :return: A string value or the default.
+        allowed_values (list[str]): List of allowed values for the string,
-    :raises
+            or None if any value is allowed, defaults to None
+
+    Returns:
+        str|None: A string value or the default.
+
+    Raises:
         SynapseError if the parameter is absent and required, or if the
             parameter is present, must be one of a list of allowed values and
             is not one of those allowed values.
@@ -122,9 +137,13 @@ def parse_string(request, name, default=None, required=False,
 def parse_json_value_from_request(request):
     """Parse a JSON value from the body of a twisted HTTP request.
 
-    :param request: the twisted HTTP request.
+    Args:
-    :returns: The JSON value.
+        request: the twisted HTTP request.
-    :raises
+
+    Returns:
+        The JSON value.
+
+    Raises:
         SynapseError if the request body couldn't be decoded as JSON.
     """
     try:
@@ -143,8 +162,10 @@ def parse_json_value_from_request(request):
 def parse_json_object_from_request(request):
     """Parse a JSON object from the body of a twisted HTTP request.
 
-    :param request: the twisted HTTP request.
+    Args:
-    :raises
+        request: the twisted HTTP request.
+
+    Raises:
         SynapseError if the request body couldn't be decoded as JSON or
             if it wasn't a JSON object.
     """

synapse/notifier.py

@@ -503,13 +503,14 @@ class Notifier(object):
     def wait_for_replication(self, callback, timeout):
         """Wait for an event to happen.
 
-        :param callback:
+        Args:
-            Gets called whenever an event happens. If this returns a truthy
+            callback: Gets called whenever an event happens. If this returns a
-            value then ``wait_for_replication`` returns, otherwise it waits
+                truthy value then ``wait_for_replication`` returns, otherwise
-            for another event.
+                it waits for another event.
-        :param int timeout:
+            timeout: How many milliseconds to wait for callback return a truthy
-            How many milliseconds to wait for callback return a truthy value.
+                value.
-        :returns:
+
+        Returns:
             A deferred that resolves with the value returned by the callback.
         """
         listener = _NotificationListener(None)

synapse/push/baserules.py

@@ -19,9 +19,11 @@ import copy
 def list_with_base_rules(rawrules):
     """Combine the list of rules set by the user with the default push rules
 
-    :param list rawrules: The rules the user has modified or set.
+    Args:
-    :returns: A new list with the rules set by the user combined with the
+        rawrules(list): The rules the user has modified or set.
-        defaults.
+
+    Returns:
+        A new list with the rules set by the user combined with the defaults.
     """
     ruleslist = []
 

synapse/rest/client/v2_alpha/sync.py

@@ -199,15 +199,17 @@ class SyncRestServlet(RestServlet):
         """
         Encode the joined rooms in a sync result
 
-        :param list[synapse.handlers.sync.JoinedSyncResult] rooms: list of sync
+        Args:
-            results for rooms this user is joined to
+            rooms(list[synapse.handlers.sync.JoinedSyncResult]): list of sync
-        :param int time_now: current time - used as a baseline for age
+                results for rooms this user is joined to
-            calculations
+            time_now(int): current time - used as a baseline for age
-        :param int token_id: ID of the user's auth token - used for namespacing
+                calculations
-            of transaction IDs
+            token_id(int): ID of the user's auth token - used for namespacing
+                of transaction IDs
 
-        :return: the joined rooms list, in our response format
+        Returns:
-        :rtype: dict[str, dict[str, object]]
+            dict[str, dict[str, object]]: the joined rooms list, in our
+                response format
         """
         joined = {}
         for room in rooms:
@@ -221,15 +223,17 @@ class SyncRestServlet(RestServlet):
         """
         Encode the invited rooms in a sync result
 
-        :param list[synapse.handlers.sync.InvitedSyncResult] rooms: list of
+        Args:
-             sync results for rooms this user is joined to
+            rooms(list[synapse.handlers.sync.InvitedSyncResult]): list of
-        :param int time_now: current time - used as a baseline for age
+                sync results for rooms this user is joined to
-            calculations
+            time_now(int): current time - used as a baseline for age
-        :param int token_id: ID of the user's auth token - used for namespacing
+                calculations
+            token_id(int): ID of the user's auth token - used for namespacing
             of transaction IDs
 
-        :return: the invited rooms list, in our response format
+        Returns:
-        :rtype: dict[str, dict[str, object]]
+            dict[str, dict[str, object]]: the invited rooms list, in our
+                response format
         """
         invited = {}
         for room in rooms:
@@ -251,15 +255,17 @@ class SyncRestServlet(RestServlet):
         """
         Encode the archived rooms in a sync result
 
-        :param list[synapse.handlers.sync.ArchivedSyncResult] rooms: list of
+        Args:
-             sync results for rooms this user is joined to
+            rooms (list[synapse.handlers.sync.ArchivedSyncResult]): list of
-        :param int time_now: current time - used as a baseline for age
+                sync results for rooms this user is joined to
-            calculations
+            time_now(int): current time - used as a baseline for age
-        :param int token_id: ID of the user's auth token - used for namespacing
+                calculations
-            of transaction IDs
+            token_id(int): ID of the user's auth token - used for namespacing
+                of transaction IDs
 
-        :return: the invited rooms list, in our response format
+        Returns:
-        :rtype: dict[str, dict[str, object]]
+            dict[str, dict[str, object]]: The invited rooms list, in our
+                response format
         """
         joined = {}
         for room in rooms:
@@ -272,17 +278,18 @@ class SyncRestServlet(RestServlet):
     @staticmethod
     def encode_room(room, time_now, token_id, joined=True):
         """
-        :param JoinedSyncResult|ArchivedSyncResult room: sync result for a
+        Args:
-            single room
+            room (JoinedSyncResult|ArchivedSyncResult): sync result for a
-        :param int time_now: current time - used as a baseline for age
+                single room
-            calculations
+            time_now (int): current time - used as a baseline for age
-        :param int token_id: ID of the user's auth token - used for namespacing
+                calculations
-            of transaction IDs
+            token_id (int): ID of the user's auth token - used for namespacing
-        :param joined: True if the user is joined to this room - will mean
+                of transaction IDs
-            we handle ephemeral events
+            joined (bool): True if the user is joined to this room - will mean
+                we handle ephemeral events
 
-        :return: the room, encoded in our response format
+        Returns:
-        :rtype: dict[str, object]
+            dict[str, object]: the room, encoded in our response format
         """
         def serialize(event):
             # TODO(mjark): Respect formatting requirements in the filter.

synapse/state.py

@@ -86,7 +86,8 @@ class StateHandler(object):
         If `event_type` is specified, then the method returns only the one
         event (or None) with that `event_type` and `state_key`.
 
-        :returns map from (type, state_key) to event
+        Returns:
+            map from (type, state_key) to event
         """
         event_ids = yield self.store.get_latest_event_ids_in_room(room_id)
 
@@ -176,10 +177,11 @@ class StateHandler(object):
         """ Given a list of event_ids this method fetches the state at each
         event, resolves conflicts between them and returns them.
 
-        :returns a Deferred tuple of (`state_group`, `state`, `prev_state`).
+        Returns:
-        `state_group` is the name of a state group if one and only one is
+            a Deferred tuple of (`state_group`, `state`, `prev_state`).
-        involved. `state` is a map from (type, state_key) to event, and
+            `state_group` is the name of a state group if one and only one is
-        `prev_state` is a list of event ids.
+            involved. `state` is a map from (type, state_key) to event, and
+            `prev_state` is a list of event ids.
         """
         logger.debug("resolve_state_groups event_ids %s", event_ids)
 
@@ -251,9 +253,10 @@ class StateHandler(object):
 
     def _resolve_events(self, state_sets, event_type=None, state_key=""):
         """
-        :returns a tuple (new_state, prev_states). new_state is a map
+        Returns
-        from (type, state_key) to event. prev_states is a list of event_ids.
+            (dict[(str, str), synapse.events.FrozenEvent], list[str]): a tuple
-        :rtype: (dict[(str, str), synapse.events.FrozenEvent], list[str])
+            (new_state, prev_states). new_state is a map from (type, state_key)
+            to event. prev_states is a list of event_ids.
         """
         with Measure(self.clock, "state._resolve_events"):
             state = {}

synapse/storage/event_push_actions.py

@@ -26,8 +26,9 @@ logger = logging.getLogger(__name__)
 class EventPushActionsStore(SQLBaseStore):
     def _set_push_actions_for_event_and_users_txn(self, txn, event, tuples):
         """
-        :param event: the event set actions for
+        Args:
-        :param tuples: list of tuples of (user_id, actions)
+            event: the event set actions for
+            tuples: list of tuples of (user_id, actions)
         """
         values = []
         for uid, actions in tuples:

synapse/storage/registration.py

@@ -458,12 +458,15 @@ class RegistrationStore(SQLBaseStore):
         """
         Gets the 3pid's guest access token if exists, else saves access_token.
 
-        :param medium (str): Medium of the 3pid. Must be "email".
+        Args:
-        :param address (str): 3pid address.
+            medium (str): Medium of the 3pid. Must be "email".
-        :param access_token (str): The access token to persist if none is
+            address (str): 3pid address.
-            already persisted.
+            access_token (str): The access token to persist if none is
-        :param inviter_user_id (str): User ID of the inviter.
+                already persisted.
-        :return (deferred str): Whichever access token is persisted at the end
+            inviter_user_id (str): User ID of the inviter.
+
+        Returns:
+            deferred str: Whichever access token is persisted at the end
             of this function call.
         """
         def insert(txn):

synapse/storage/state.py

@@ -249,11 +249,14 @@ class StateStore(SQLBaseStore):
         """
         Get the state dict corresponding to a particular event
 
-        :param str event_id: event whose state should be returned
+        Args:
-        :param list[(str, str)]|None types: List of (type, state_key) tuples
+            event_id(str): event whose state should be returned
-            which are used to filter the state fetched. May be None, which
+            types(list[(str, str)]|None): List of (type, state_key) tuples
-            matches any key
+                which are used to filter the state fetched. May be None, which
-        :return: a deferred dict from (type, state_key) -> state_event
+                matches any key
+
+        Returns:
+            A deferred dict from (type, state_key) -> state_event
         """
         state_map = yield self.get_state_for_events([event_id], types)
         defer.returnValue(state_map[event_id])