mirror of
https://mau.dev/maunium/synapse.git
synced 2024-12-15 01:33:52 +01:00
Merge pull request #686 from matrix-org/markjh/doc_strings
Use google style doc strings.
This commit is contained in:
commit
89e6839a48
14 changed files with 238 additions and 165 deletions
|
@ -17,3 +17,6 @@ ignore =
|
||||||
[flake8]
|
[flake8]
|
||||||
max-line-length = 90
|
max-line-length = 90
|
||||||
ignore = W503 ; W503 requires that binary operators be at the end, not start, of lines. Erik doesn't like it.
|
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
|
||||||
|
|
|
@ -41,8 +41,9 @@ class BaseHandler(object):
|
||||||
"""
|
"""
|
||||||
Common base class for the event handlers.
|
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):
|
def __init__(self, hs):
|
||||||
|
@ -65,11 +66,12 @@ class BaseHandler(object):
|
||||||
""" Returns dict of user_id -> list of events that user is allowed to
|
""" Returns dict of user_id -> list of events that user is allowed to
|
||||||
see.
|
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([
|
forgotten = yield defer.gatherResults([
|
||||||
self.store.who_forgot_in_room(
|
self.store.who_forgot_in_room(
|
||||||
|
@ -165,13 +167,16 @@ class BaseHandler(object):
|
||||||
"""
|
"""
|
||||||
Check which events a user is allowed to see
|
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 is not currently a member of the room, and:
|
||||||
* the user has not been a member of the room since the given
|
* the user has not been a member of the room since the given
|
||||||
events
|
events
|
||||||
:rtype [synapse.events.EventBase]
|
|
||||||
|
Returns:
|
||||||
|
[synapse.events.EventBase]
|
||||||
"""
|
"""
|
||||||
types = (
|
types = (
|
||||||
(EventTypes.RoomHistoryVisibility, ""),
|
(EventTypes.RoomHistoryVisibility, ""),
|
||||||
|
|
|
@ -163,9 +163,13 @@ class AuthHandler(BaseHandler):
|
||||||
def get_session_id(self, clientdict):
|
def get_session_id(self, clientdict):
|
||||||
"""
|
"""
|
||||||
Gets the session ID for a client given the client dictionary
|
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
|
sid = None
|
||||||
if clientdict and 'auth' in clientdict:
|
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
|
Store a key-value pair into the sessions data associated with this
|
||||||
request. This data is stored server-side and cannot be modified by
|
request. This data is stored server-side and cannot be modified by
|
||||||
the client.
|
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 = self._get_session_info(session_id)
|
||||||
sess.setdefault('serverdict', {})[key] = value
|
sess.setdefault('serverdict', {})[key] = value
|
||||||
|
@ -190,9 +196,11 @@ class AuthHandler(BaseHandler):
|
||||||
def get_session_data(self, session_id, key, default=None):
|
def get_session_data(self, session_id, key, default=None):
|
||||||
"""
|
"""
|
||||||
Retrieve data stored with set_session_data
|
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)
|
sess = self._get_session_info(session_id)
|
||||||
return sess.setdefault('serverdict', {}).get(key, default)
|
return sess.setdefault('serverdict', {}).get(key, default)
|
||||||
|
|
|
@ -1703,13 +1703,15 @@ class FederationHandler(BaseHandler):
|
||||||
def _check_signature(self, event, auth_events):
|
def _check_signature(self, event, auth_events):
|
||||||
"""
|
"""
|
||||||
Checks that the signature in the event is consistent with its invite.
|
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,
|
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.
|
for revocation.
|
||||||
"""
|
"""
|
||||||
signed = event.content["third_party_invite"]["signed"]
|
signed = event.content["third_party_invite"]["signed"]
|
||||||
|
@ -1751,12 +1753,13 @@ class FederationHandler(BaseHandler):
|
||||||
"""
|
"""
|
||||||
Checks whether public_key has been revoked.
|
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.
|
for revocation.
|
||||||
"""
|
"""
|
||||||
try:
|
try:
|
||||||
|
|
|
@ -411,7 +411,7 @@ class RoomMemberHandler(BaseHandler):
|
||||||
address (str): The third party identifier (e.g. "foo@example.com").
|
address (str): The third party identifier (e.g. "foo@example.com").
|
||||||
|
|
||||||
Returns:
|
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:
|
try:
|
||||||
data = yield self.hs.get_simple_http_client().get_json(
|
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.
|
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" % (
|
is_url = "%s%s/_matrix/identity/api/v1/store-invite" % (
|
||||||
|
|
|
@ -663,7 +663,8 @@ class SyncHandler(BaseHandler):
|
||||||
def load_filtered_recents(self, room_id, sync_config, now_token,
|
def load_filtered_recents(self, room_id, sync_config, now_token,
|
||||||
since_token=None, recents=None, newly_joined_room=False):
|
since_token=None, recents=None, newly_joined_room=False):
|
||||||
"""
|
"""
|
||||||
:returns a Deferred TimelineBatch
|
Returns:
|
||||||
|
a Deferred TimelineBatch
|
||||||
"""
|
"""
|
||||||
with Measure(self.clock, "load_filtered_recents"):
|
with Measure(self.clock, "load_filtered_recents"):
|
||||||
filtering_factor = 2
|
filtering_factor = 2
|
||||||
|
@ -830,8 +831,11 @@ class SyncHandler(BaseHandler):
|
||||||
"""
|
"""
|
||||||
Get the room state after the given event
|
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)
|
state = yield self.store.get_state_for_event(event.event_id)
|
||||||
if event.is_state():
|
if event.is_state():
|
||||||
|
@ -842,9 +846,13 @@ class SyncHandler(BaseHandler):
|
||||||
@defer.inlineCallbacks
|
@defer.inlineCallbacks
|
||||||
def get_state_at(self, room_id, stream_position):
|
def get_state_at(self, room_id, stream_position):
|
||||||
""" Get the room state at a particular 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(
|
last_events, token = yield self.store.get_recent_events_for_room(
|
||||||
room_id, end_token=stream_position.room_key, limit=1,
|
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
|
""" Works out the differnce in state between the start of the timeline
|
||||||
and the previous sync.
|
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
|
# TODO(mjark) Check if the state events were received by the server
|
||||||
# after the previous sync, since we need to include those state
|
# 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
|
Check if the user has just joined the given room (so should
|
||||||
be given the full state)
|
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((
|
join_event = state_delta.get((
|
||||||
EventTypes.Member, sync_config.user.to_string()), None)
|
EventTypes.Member, sync_config.user.to_string()), None)
|
||||||
|
|
|
@ -26,14 +26,19 @@ logger = logging.getLogger(__name__)
|
||||||
def parse_integer(request, name, default=None, required=False):
|
def parse_integer(request, name, default=None, required=False):
|
||||||
"""Parse an integer parameter from the request string
|
"""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.
|
parameter is present and not an integer.
|
||||||
"""
|
"""
|
||||||
if name in request.args:
|
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):
|
def parse_boolean(request, name, default=None, required=False):
|
||||||
"""Parse a boolean parameter from the request query string
|
"""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".
|
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"):
|
allowed_values=None, param_type="string"):
|
||||||
"""Parse a string parameter from the request query 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
|
SynapseError if the parameter is absent and required, or if the
|
||||||
parameter is present, must be one of a list of allowed values and
|
parameter is present, must be one of a list of allowed values and
|
||||||
is not one of those allowed values.
|
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):
|
def parse_json_value_from_request(request):
|
||||||
"""Parse a JSON value from the body of a twisted HTTP 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.
|
SynapseError if the request body couldn't be decoded as JSON.
|
||||||
"""
|
"""
|
||||||
try:
|
try:
|
||||||
|
@ -143,8 +162,10 @@ def parse_json_value_from_request(request):
|
||||||
def parse_json_object_from_request(request):
|
def parse_json_object_from_request(request):
|
||||||
"""Parse a JSON object from the body of a twisted HTTP 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
|
SynapseError if the request body couldn't be decoded as JSON or
|
||||||
if it wasn't a JSON object.
|
if it wasn't a JSON object.
|
||||||
"""
|
"""
|
||||||
|
|
|
@ -503,13 +503,14 @@ class Notifier(object):
|
||||||
def wait_for_replication(self, callback, timeout):
|
def wait_for_replication(self, callback, timeout):
|
||||||
"""Wait for an event to happen.
|
"""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.
|
A deferred that resolves with the value returned by the callback.
|
||||||
"""
|
"""
|
||||||
listener = _NotificationListener(None)
|
listener = _NotificationListener(None)
|
||||||
|
|
|
@ -19,9 +19,11 @@ import copy
|
||||||
def list_with_base_rules(rawrules):
|
def list_with_base_rules(rawrules):
|
||||||
"""Combine the list of rules set by the user with the default push rules
|
"""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 = []
|
ruleslist = []
|
||||||
|
|
||||||
|
|
|
@ -199,15 +199,17 @@ class SyncRestServlet(RestServlet):
|
||||||
"""
|
"""
|
||||||
Encode the joined rooms in a sync result
|
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 = {}
|
joined = {}
|
||||||
for room in rooms:
|
for room in rooms:
|
||||||
|
@ -221,15 +223,17 @@ class SyncRestServlet(RestServlet):
|
||||||
"""
|
"""
|
||||||
Encode the invited rooms in a sync result
|
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
|
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 = {}
|
invited = {}
|
||||||
for room in rooms:
|
for room in rooms:
|
||||||
|
@ -251,15 +255,17 @@ class SyncRestServlet(RestServlet):
|
||||||
"""
|
"""
|
||||||
Encode the archived rooms in a sync result
|
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 = {}
|
joined = {}
|
||||||
for room in rooms:
|
for room in rooms:
|
||||||
|
@ -272,17 +278,18 @@ class SyncRestServlet(RestServlet):
|
||||||
@staticmethod
|
@staticmethod
|
||||||
def encode_room(room, time_now, token_id, joined=True):
|
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):
|
def serialize(event):
|
||||||
# TODO(mjark): Respect formatting requirements in the filter.
|
# TODO(mjark): Respect formatting requirements in the filter.
|
||||||
|
|
|
@ -86,7 +86,8 @@ class StateHandler(object):
|
||||||
If `event_type` is specified, then the method returns only the one
|
If `event_type` is specified, then the method returns only the one
|
||||||
event (or None) with that `event_type` and `state_key`.
|
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)
|
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
|
""" Given a list of event_ids this method fetches the state at each
|
||||||
event, resolves conflicts between them and returns them.
|
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)
|
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=""):
|
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"):
|
with Measure(self.clock, "state._resolve_events"):
|
||||||
state = {}
|
state = {}
|
||||||
|
|
|
@ -26,8 +26,9 @@ logger = logging.getLogger(__name__)
|
||||||
class EventPushActionsStore(SQLBaseStore):
|
class EventPushActionsStore(SQLBaseStore):
|
||||||
def _set_push_actions_for_event_and_users_txn(self, txn, event, tuples):
|
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 = []
|
values = []
|
||||||
for uid, actions in tuples:
|
for uid, actions in tuples:
|
||||||
|
|
|
@ -458,12 +458,15 @@ class RegistrationStore(SQLBaseStore):
|
||||||
"""
|
"""
|
||||||
Gets the 3pid's guest access token if exists, else saves access_token.
|
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.
|
of this function call.
|
||||||
"""
|
"""
|
||||||
def insert(txn):
|
def insert(txn):
|
||||||
|
|
|
@ -249,11 +249,14 @@ class StateStore(SQLBaseStore):
|
||||||
"""
|
"""
|
||||||
Get the state dict corresponding to a particular event
|
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)
|
state_map = yield self.get_state_for_events([event_id], types)
|
||||||
defer.returnValue(state_map[event_id])
|
defer.returnValue(state_map[event_id])
|
||||||
|
|
Loading…
Reference in a new issue