def list_media(self,
userid: str,
limit: int = 100,
_from: int = 0,
order_by: int = None,
_dir: str = "f") -> Contents:
"""list all media sent by the user
https://github.com/matrix-org/synapse/blob/develop/docs/admin_api/user_admin_api.md#list-media-of-a-user
Args:
userid (str): the user you want to query
limit (int, optional): equivalent to "limit". Defaults to 100.
_from (int, optional): equivalent to "from". Defaults to 0.
order_by (int, optional): equivalent to "order_by". Defaults to None. # noqa: E501
_dir (str, optional): equivalent to "dir". Defaults to "f".
Returns:
Contents: list of media # noqa: E501
"""
userid = self.validate_username(userid)
optional_str = ""
if order_by is not None:
optional_str += f"&order_by={order_by}"
resp = self.connection.request(
"GET",
self.admin_patterns(
f"/users/{userid}/media?"
f"limit={limit}&from={_from}"
f"&dir={_dir}{optional_str}", 1))
data = resp.json()
if resp.status_code == 200:
if "next_token" not in data:
next_token = 0
else:
next_token = data["next_token"]
return Contents(data["media"], data["total"], next_token)
else:
if self.suppress_exception:
return False, data
else:
raise SynapseException(data["errcode"], data["error"])
def federation_list(self,
_from: int = 0,
limit: int = 100,
orderby: str = None,
_dir: str = "f",
destination: str = None) -> Contents:
"""List infomation of retrying timing for all remote servers
https://github.com/matrix-org/synapse/blob/develop/docs/usage/administration/admin_api/federation.md#federation-api
https://github.com/matrix-org/synapse/blob/develop/docs/usage/administration/admin_api/federation.md#list-of-destinations
https://github.com/matrix-org/synapse/blob/develop/docs/usage/administration/admin_api/federation.md#destination-details-api
Args:
_from (int, optional): equivalent to "from". Defaults to 0.
limit (int, optional): equivalent to "limit". Defaults to 100.
order_by (int, optional): equivalent to "order_by". Defaults to None. # noqa: E501
_dir (str, optional): equivalent to "dir". Defaults to "f".
destination (str, optional): show only the specified remote server. Defaults to None (no specification).
Returns:
Contents: list of timing information of current destination
"""
if isinstance(destination, str):
return self._federation_list(destination)
params = {"from": _from, "limit": limit, "dir": _dir}
if orderby is not None:
params["order_by"] = orderby
resp = self.connection.request("GET",
self.admin_patterns(
"/federation/destinations", 1),
params=params)
data = resp.json()
if resp.status_code == 200:
return Contents(data["destinations"], data["total"],
data.get("next_token", None))
else:
if self.suppress_exception:
return False, data["errcode"], data["error"]
else:
raise SynapseException(data["errcode"], data["error"])
def delete_local_media_by_condition(
self,
timestamp: int = Utility.get_current_time(),
size_gt: int = 0,
keep_profiles: bool = True,
server_name: str = None) -> Contents:
"""Delete local media with condition
https://github.com/matrix-org/synapse/blob/develop/docs/admin_api/media_admin_api.md#delete-local-media-by-date-or-size
Args:
timestamp (int, optional): delete media sent before this timestamp. Defaults to Utility.get_current_time() (current time). # noqa: E501
size_gt (int, optional): delete media in which their size are greater than this size in bytes. Defaults to None.
keep_profiles (bool, optional): whether to keep profiles media or not. Defaults to True.
server_name (str, optional): the source of the media. Defaults to your local server name (None).
Returns:
Contents: a list of deleted media
"""
if server_name is None:
server_name = self.server_addr
optional_str = ""
if keep_profiles:
optional_str += "&keep_profiles=true"
if size_gt < 0:
raise ValueError("Argument 'size_gt' must be a positive integer")
if not isinstance(timestamp, int):
raise TypeError("Argument 'timestamp' must be an integer")
resp = self.connection.request(
"POST",
self.admin_patterns(
f"/media/{server_name}/delete?before_ts="
f"{timestamp}&size_gt={size_gt}{optional_str}", 1),
json={},
)
data = resp.json()
return Contents(data["deleted_media"], data["total"])
def delete_media_by_user(self,
userid: str,
limit: int = 100,
_from: int = 0,
order_by: int = None,
_dir: str = "f") -> Contents:
"""Delete local media uploaded by a specific user
https://github.com/matrix-org/synapse/blob/develop/docs/admin_api/user_admin_api.md#delete-media-uploaded-by-a-user
https://github.com/matrix-org/synapse/blob/develop/docs/admin_api/user_admin_api.md#list-media-uploaded-by-a-user
Args:
userid (str): the user you want to delete their uploaded media
limit (int, optional): equivalent to "limit". Defaults to 100.
_from (int, optional): equivalent to "from". Defaults to 0.
order_by (int, optional): equivalent to "order_by". Defaults to None. # noqa: E501
_dir (str, optional): equivalent to "dir". Defaults to "f".
Returns:
Contents: list of media deleted
"""
userid = self.validate_username(userid)
optional_str = ""
if order_by is not None:
optional_str += f"&order_by={order_by}"
resp = self.connection.request(
"DELETE",
self.admin_patterns(
f"/users/{userid}/media?"
f"limit={limit}&from={_from}"
f"&dir={_dir}{optional_str}", 1))
data = resp.json()
if resp.status_code == 200:
return Contents(data["deleted_media"], data["total"])
else:
if self.suppress_exception:
return False, data
else:
raise SynapseException(data["errcode"], data["error"])
def pushers(self, userid: str) -> Contents:
"""list pushers of a user
https://github.com/matrix-org/synapse/blob/develop/docs/admin_api/user_admin_api.md#list-all-pushers
Args:
userid (str): the user you want to query
Returns:
Contents: list of pushers
"""
userid = self.validate_username(userid)
resp = self.connection.request(
"GET", self.admin_patterns(f"/users/{userid}/pushers", 1))
data = resp.json()
if resp.status_code == 200:
return Contents(data["pushers"], data["total"])
else:
if self.suppress_exception:
return False, data
else:
raise SynapseException(data["errcode"], data["error"])
def joined_room(self, userid: str) -> Contents:
"""Query the room a user joined
https://github.com/matrix-org/synapse/blob/develop/docs/admin_api/user_admin_api.md#list-room-memberships-of-a-user
Args:
userid (str): the user you want to query
Returns:
Contents: list of joined_room
"""
userid = self.validate_username(userid)
resp = self.connection.request(
"GET", self.admin_patterns(f"/users/{userid}/joined_rooms", 1))
data = resp.json()
if resp.status_code == 200:
return Contents(data["joined_rooms"], data["total"])
else:
if self.suppress_exception:
return False, data
else:
raise SynapseException(data["errcode"], data["error"])
def federation_room(self,
destination: str,
_from: int = 0,
limit: int = 100,
_dir: str = "f") -> Contents:
"""Fetch roms federated with remote destination
https://github.com/matrix-org/synapse/blob/develop/docs/usage/administration/admin_api/federation.md#destination-rooms
Args:
destination (str): the remote destination
_from (int, optional): equivalent to "from". Defaults to 0.
limit (int, optional): equivalent to "limit". Defaults to 100.
_dir (str, optional): equivalent to "dir". Defaults to "f".
Returns:
Contents: A list of federated room
"""
resp = self.connection.request(
"GET",
self.admin_patterns(
f"/federation/destinations/{destination}/rooms", 1),
params={
"from": _from,
"limit": limit,
"dir": _dir
})
data = resp.json()
if resp.status_code == 200:
return Contents(data["rooms"], data["total"],
data.get("next_token", None))
else:
if self.suppress_exception:
return False, data["errcode"], data["error"]
else:
raise SynapseException(data["errcode"], data["error"])
def list_members(self, roomid: str) -> Contents:
"""List all members in the room
https://github.com/matrix-org/synapse/blob/develop/docs/admin_api/rooms.md#room-members-api
Args:
roomid (str): the room you want to query
Returns:
Contents: a list of members
"""
roomid = self.validate_room(roomid)
resp = self.connection.request(
"GET",
self.admin_patterns(f"/rooms/{roomid}/members", 1),
)
data = resp.json()
if resp.status_code == 200:
return Contents(data["members"], data["total"])
else:
if self.suppress_exception:
return False, data
else:
raise SynapseException(data["errcode"], data["error"])
def statistics(self,
_from: int = None,
limit: int = None,
orderby: str = None,
from_ts: int = None,
until_ts: int = None,
search: str = None,
forward: bool = False) -> Contents:
"""Query the media usage statistics
https://github.com/matrix-org/synapse/blob/develop/docs/admin_api/statistics.md#users-media-usage-statistics
Args:
_from (int, optional): equivalent to "from". Defaults to None.
limit (int, optional): equivalent to "limit". Defaults to None.
orderby (str, optional): equivalent to "order_by". Defaults to None.
from_ts (int, optional): equivalent to "from_ts". Defaults to None.
until_ts (int, optional): equivalent to "until_ts". Defaults to None.
search (str, optional): equivalent to "search_term". Defaults to None.
forward (bool, optional): equivalent to "dir". True to forward False to backward Defaults to False. # noqa: E501
Returns:
Contents: list of media usage per user
"""
if forward:
optional_str = "dir=f"
else:
optional_str = "dir=b"
if _from is not None:
optional_str += f"&from={_from}"
if limit is not None:
optional_str += f"&limit={limit}"
if orderby is not None:
if not isinstance(orderby, str):
raise TypeError("Argument 'orderby' should be a "
f"str but not {type(orderby)}")
elif orderby not in Media.order:
raise ValueError(
"Argument 'orderby' must be included in Media.order, "
"for details please read documentation.")
optional_str += f"&orderby={orderby}"
if from_ts:
optional_str += f"&from_ts={from_ts}"
if until_ts:
optional_str += f"&until_ts={until_ts}"
if search:
optional_str += f"&search_term={search}"
resp = self.connection.request(
"GET",
self.admin_patterns(f"/statistics/users/media?{optional_str}", 1),
)
data = resp.json()
return Contents(data["users"], data["total"],
data.get("next_token", None))
def test_base_contents():
contens = Contents([1, 2, 3, 4], 4, 5)
assert contens.total == 4
assert contens.next == 5
with pytest.raises(TypeError):
contens = Contents("Invalid")