# admin.py - admin / moderation endpoints
from mastodon.versions import _DICT_VERSION_ADMIN_ACCOUNT, _DICT_VERSION_REPORT, _DICT_VERSION_HASHTAG, _DICT_VERSION_STATUS, _DICT_VERSION_CARD, \
_DICT_VERSION_ADMIN_DOMAIN_BLOCK, _DICT_VERSION_ADMIN_MEASURE, _DICT_VERSION_ADMIN_DIMENSION, _DICT_VERSION_ADMIN_RETENTION
from mastodon.errors import MastodonIllegalArgumentError
from mastodon.utility import api_version
from mastodon.internals import Mastodon as Internals
from typing import Optional, List, Union
from mastodon.types import IdType, PrimitiveIdType, Account, AdminAccount, AdminReport, PaginatableList, NonPaginatableList, Status, Tag,\
PreviewCard, AdminDomainBlock, AdminMeasure, AdminDimension, AdminRetention
from datetime import datetime
class Mastodon(Internals):
###
# Moderation API
###
[docs]
@api_version("2.9.1", "4.0.0", _DICT_VERSION_ADMIN_ACCOUNT)
def admin_accounts_v2(self, origin: Optional[str] = None, by_domain: Optional[str] = None, status: Optional[str] = None, username: Optional[str] = None,
display_name: Optional[str] = None, email: Optional[str] = None, ip: Optional[str] = None, permissions: Optional[str] = None,
invited_by: Union[Account, IdType] = None, role_ids: Optional[List[IdType]] = None, max_id: Optional[IdType] = None, min_id: Optional[IdType] = None,
since_id: Optional[IdType] = None, limit: Optional[int] = None) -> AdminAccount:
"""
Fetches a list of accounts that match given criteria. By default, local accounts are returned.
* Set `origin` to "local" or "remote" to get only local or remote accounts.
* Set `by_domain` to a domain to get only accounts from that domain.
* Set `status` to one of "active", "pending", "disabled", "silenced" or "suspended" to get only accounts with that moderation status (default: active)
* Set `username` to a string to get only accounts whose username contains this string.
* Set `display_name` to a string to get only accounts whose display name contains this string.
* Set `email` to an email to get only accounts with that email (this only works on local accounts).
* Set `ip` to an ip (as a string, standard v4/v6 notation) to get only accounts whose last active ip is that ip (this only works on local accounts).
* Set `permissions` to "staff" to only get accounts with staff permissions.
* Set `invited_by` to an account id to get only accounts invited by this user.
* Set `role_ids` to a list of role IDs to get only accounts with those roles.
Returns a list of :ref:`admin account dicts <admin account dicts>`.
Pagination on this is a bit weird, so I would recommend not doing that and instead manually fetching.
"""
if max_id is not None:
max_id = self.__unpack_id(max_id)
if min_id is not None:
min_id = self.__unpack_id(min_id)
if since_id is not None:
since_id = self.__unpack_id(since_id)
if role_ids is not None:
if not isinstance(role_ids, list):
role_ids = [role_ids]
role_ids = [self.__unpack_id(x) for x in role_ids]
if invited_by is not None:
invited_by = self.__unpack_id(invited_by)
if permissions is not None and not permissions in ["staff"]:
raise MastodonIllegalArgumentError("Permissions must be staff if passed")
if origin is not None and not origin in ["local", "remote"]:
raise MastodonIllegalArgumentError("Origin must be local or remote")
if status is not None and not status in ["active", "pending", "disabled", "silenced", "suspended"]:
raise MastodonIllegalArgumentError("Status must be local or active, pending, disabled, silenced or suspended")
if not by_domain is None:
by_domain = self.__deprotocolize(by_domain)
params = self.__generate_params(locals())
return self.__api_request('GET', '/api/v2/admin/accounts', params)
[docs]
@api_version("2.9.1", "2.9.1", _DICT_VERSION_ADMIN_ACCOUNT)
def admin_accounts(self, remote: bool = False, by_domain: Optional[str] = None, status: str = 'active', username: Optional[str] = None,
display_name: Optional[str] = None, email: Optional[str] = None, ip: Optional[str] = None, staff_only: bool = False,
max_id: Optional[IdType] = None, min_id: Optional[IdType] = None, since_id: Optional[IdType] = None,
limit: Optional[int] = None):
"""
Currently a synonym for admin_accounts_v1, now deprecated. You are strongly encouraged to use admin_accounts_v2 instead, since this one is kind of bad.
!!!!! This function may be switched to calling the v2 API in the future. This is your warning. If you want to keep using v1, use it explicitly. !!!!!
Pagination on this is a bit weird, so I would recommend not doing that and instead manually fetching.
"""
return self.admin_accounts_v1(
remote=remote,
by_domain=by_domain,
status=status,
username=username,
display_name=display_name,
email=email,
ip=ip,
staff_only=staff_only,
max_id=max_id,
min_id=min_id,
since_id=since_id
)
[docs]
@api_version("2.9.1", "2.9.1", _DICT_VERSION_ADMIN_ACCOUNT)
def admin_accounts_v1(self, remote: bool = False, by_domain: Optional[str] = None, status: str = 'active', username: Optional[str] = None,
display_name: Optional[str] = None, email: Optional[str] = None, ip: Optional[str] = None, staff_only: bool = False,
max_id: Optional[IdType] = None, min_id: Optional[IdType] = None, since_id: Optional[IdType] = None,
limit: Optional[int] = None) -> AdminAccount:
"""
Fetches a list of accounts that match given criteria. By default, local accounts are returned.
* Set `remote` to True to get remote accounts, otherwise local accounts are returned (default: local accounts)
* Set `by_domain` to a domain to get only accounts from that domain.
* Set `status` to one of "active", "pending", "disabled", "silenced" or "suspended" to get only accounts with that moderation status (default: active)
* Set `username` to a string to get only accounts whose username contains this string.
* Set `display_name` to a string to get only accounts whose display name contains this string.
* Set `email` to an email to get only accounts with that email (this only works on local accounts).
* Set `ip` to an ip (as a string, standard v4/v6 notation) to get only accounts whose last active ip is that ip (this only works on local accounts).
* Set `staff_only` to True to only get staff accounts (this only works on local accounts).
Note that setting the boolean parameters to False does not mean "give me users to which this does not apply" but
instead means "I do not care if users have this attribute".
Deprecated in Mastodon version 3.5.0.
Returns a list of :ref:`admin account dicts <admin account dicts>`.
Pagination on this is a bit weird, so I would recommend not doing that and instead manually fetching.
"""
if max_id is not None:
max_id = self.__unpack_id(max_id)
if min_id is not None:
min_id = self.__unpack_id(min_id)
if since_id is not None:
since_id = self.__unpack_id(since_id)
params = self.__generate_params(locals(), ['remote', 'status', 'staff_only'])
if remote:
params["remote"] = True
mod_statuses = ["active", "pending", "disabled", "silenced", "suspended"]
if not status in mod_statuses:
raise ValueError("Invalid moderation status requested.")
if staff_only:
params["staff"] = True
for mod_status in mod_statuses:
if status == mod_status:
params[status] = True
if not by_domain is None:
by_domain = self.__deprotocolize(by_domain)
return self.__api_request('GET', '/api/v1/admin/accounts', params)
[docs]
@api_version("2.9.1", "2.9.1", _DICT_VERSION_ADMIN_ACCOUNT)
def admin_account(self, id: Union[Account, AdminAccount, IdType]) -> AdminAccount:
"""
Fetches a single :ref:`admin account dict <admin account dict>` for the user with the given id.
"""
id = self.__unpack_id(id)
return self.__api_request('GET', f'/api/v1/admin/accounts/{id}')
[docs]
@api_version("2.9.1", "2.9.1", _DICT_VERSION_ADMIN_ACCOUNT)
def admin_account_enable(self, id: Union[Account, AdminAccount, IdType]) -> AdminAccount:
"""
Reenables login for a local account for which login has been disabled.
The returned object reflects the updates to the account.
"""
id = self.__unpack_id(id)
return self.__api_request('POST', f'/api/v1/admin/accounts/{id}/enable')
[docs]
@api_version("2.9.1", "2.9.1", _DICT_VERSION_ADMIN_ACCOUNT)
def admin_account_approve(self, id: Union[Account, AdminAccount, IdType]) -> AdminAccount:
"""
Approves a pending account.
The returned object reflects the updates to the account.
"""
id = self.__unpack_id(id)
return self.__api_request('POST', f'/api/v1/admin/accounts/{id}/approve')
[docs]
@api_version("2.9.1", "2.9.1", _DICT_VERSION_ADMIN_ACCOUNT)
def admin_account_reject(self, id: Union[Account, AdminAccount, IdType]) -> AdminAccount:
"""
Rejects and deletes a pending account.
The returned object is that of the now-deleted account.
"""
id = self.__unpack_id(id)
return self.__api_request('POST', f'/api/v1/admin/accounts/{id}/reject')
[docs]
@api_version("2.9.1", "2.9.1", _DICT_VERSION_ADMIN_ACCOUNT)
def admin_account_unsilence(self, id: Union[Account, AdminAccount, IdType]) -> AdminAccount:
"""
Unsilences an account.
The returned object reflects the updates to the account.
"""
id = self.__unpack_id(id)
return self.__api_request('POST', f'/api/v1/admin/accounts/{id}/unsilence')
[docs]
@api_version("2.9.1", "2.9.1", _DICT_VERSION_ADMIN_ACCOUNT)
def admin_account_unsuspend(self, id: Union[Account, AdminAccount, IdType]) -> AdminAccount:
"""
Unsuspends an account.
The returned object reflects the updates to the account.
"""
id = self.__unpack_id(id)
return self.__api_request('POST', f'/api/v1/admin/accounts/{id}/unsuspend')
@api_version("3.3.0", "3.3.0", _DICT_VERSION_ADMIN_ACCOUNT)
def admin_account_delete(self, id: Union[Account, AdminAccount, IdType]) -> AdminAccount:
"""
Delete a local user account.
The returned object reflects the updates to the account.
"""
id = self.__unpack_id(id)
return self.__api_request('DELETE', f'/api/v1/admin/accounts/{id}')
@api_version("3.3.0", "3.3.0", _DICT_VERSION_ADMIN_ACCOUNT)
def admin_account_unsensitive(self, id: Union[Account, AdminAccount, IdType]) -> AdminAccount:
"""
Unmark an account as force-sensitive.
The returned object reflects the updates to the account.
"""
id = self.__unpack_id(id)
return self.__api_request('POST', f'/api/v1/admin/accounts/{id}/unsensitive')
[docs]
@api_version("2.9.1", "2.9.1", "2.9.1")
def admin_account_moderate(self, id: Union[Account, AdminAccount, IdType], action: Optional[str] = None, report_id: Optional[Union[AdminReport, PrimitiveIdType]] = None,
warning_preset_id: Optional[PrimitiveIdType] = None, text: Optional[str] = None, send_email_notification: Optional[bool] = True):
"""
Perform a moderation action on an account.
Valid actions are:
* "disable" - for a local user, disable login.
* "silence" - hide the users posts from all public timelines.
* "suspend" - irreversibly delete all the user's posts, past and future.
* "sensitive" - forcce an accounts media visibility to always be sensitive.
If no action is specified, the user is only issued a warning.
Specify the id of a report as `report_id` to close the report with this moderation action as the resolution.
Specify `warning_preset_id` to use a warning preset as the notification text to the user, or `text` to specify text directly.
If both are specified, they are concatenated (preset first). Note that there is currently no API to retrieve or create
warning presets.
Set `send_email_notification` to False to not send the user an email notification informing them of the moderation action.
"""
if action is None:
action = "none"
if not send_email_notification:
send_email_notification = None
id = self.__unpack_id(id)
if report_id is not None:
report_id = self.__unpack_id(report_id)
params = self.__generate_params(locals(), ['id', 'action'])
params["type"] = action
self.__api_request('POST', f'/api/v1/admin/accounts/{id}/action', params)
[docs]
@api_version("2.9.1", "2.9.1", _DICT_VERSION_REPORT)
def admin_reports(self, resolved: Optional[bool] = False, account_id: Optional[Union[Account, AdminAccount, IdType]] = None,
target_account_id: Optional[Union[Account, AdminAccount, IdType]] = None, max_id: Optional[IdType] = None,
min_id: Optional[IdType] = None, since_id: Optional[IdType] = None, limit: Optional[int] = None) -> PaginatableList[AdminReport]:
"""
Fetches the list of reports.
Set `resolved` to True to search for resolved reports. `account_id` and `target_account_id`
can be used to get reports filed by or about a specific user.
Returns a list of :ref:`report dicts <report dicts>`.
"""
if max_id is not None:
max_id = self.__unpack_id(max_id)
if min_id is not None:
min_id = self.__unpack_id(min_id)
if since_id is not None:
since_id = self.__unpack_id(since_id)
if account_id is not None:
account_id = self.__unpack_id(account_id)
if target_account_id is not None:
target_account_id = self.__unpack_id(target_account_id)
if not resolved:
resolved = None
params = self.__generate_params(locals())
return self.__api_request('GET', '/api/v1/admin/reports', params)
[docs]
@api_version("2.9.1", "2.9.1", _DICT_VERSION_REPORT)
def admin_report(self, id: Union[AdminReport, IdType]) -> AdminReport:
"""
Fetches the report with the given id.
"""
id = self.__unpack_id(id)
return self.__api_request('GET', f'/api/v1/admin/reports/{id}')
[docs]
@api_version("2.9.1", "2.9.1", _DICT_VERSION_REPORT)
def admin_report_assign(self, id: Union[AdminReport, IdType]) -> AdminReport:
"""
Assigns the given report to the logged-in user.
The returned object reflects the updates to the report.
"""
id = self.__unpack_id(id)
return self.__api_request('POST', f'/api/v1/admin/reports/{id}/assign_to_self')
[docs]
@api_version("2.9.1", "2.9.1", _DICT_VERSION_REPORT)
def admin_report_unassign(self, id: Union[AdminReport, IdType]) -> AdminReport:
"""
Unassigns the given report from the logged-in user.
The returned object reflects the updates to the report.
"""
id = self.__unpack_id(id)
return self.__api_request('POST', f'/api/v1/admin/reports/{id}/unassign')
[docs]
@api_version("2.9.1", "2.9.1", _DICT_VERSION_REPORT)
def admin_report_reopen(self, id: Union[AdminReport, IdType]) -> AdminReport:
"""
Reopens a closed report.
The returned object reflects the updates to the report.
"""
id = self.__unpack_id(id)
return self.__api_request('POST', f'/api/v1/admin/reports/{id}/reopen')
[docs]
@api_version("2.9.1", "2.9.1", _DICT_VERSION_REPORT)
def admin_report_resolve(self, id: Union[AdminReport, IdType]) -> AdminReport:
"""
Marks a report as resolved (without taking any action).
The returned object reflects the updates to the report.
"""
id = self.__unpack_id(id)
return self.__api_request('POST', f'/api/v1/admin/reports/{id}/resolve')
[docs]
@api_version("3.5.0", "3.5.0", _DICT_VERSION_STATUS)
def admin_trending_statuses(self) -> NonPaginatableList[Status]:
"""
Admin version of :ref:`trending_statuses() <trending_statuses()>`. Includes unapproved tags.
The returned list is sorted, descending, by the instance's trending algorithm.
"""
params = self.__generate_params(locals())
return self.__api_request('GET', '/api/v1/admin/trends/statuses', params)
[docs]
@api_version("3.5.0", "3.5.0", _DICT_VERSION_CARD)
def admin_trending_links(self) -> NonPaginatableList[PreviewCard]:
"""
Admin version of :ref:`trending_links() <trending_links()>`. Includes unapproved tags.
The returned list is sorted, descending, by the instance's trending algorithm.
"""
params = self.__generate_params(locals())
return self.__api_request('GET', '/api/v1/admin/trends/links', params)
[docs]
@api_version("4.0.0", "4.0.0", _DICT_VERSION_ADMIN_DOMAIN_BLOCK)
def admin_domain_blocks(self, id: Optional[IdType] = None, max_id: Optional[IdType] = None, min_id: Optional[IdType] = None,
since_id: Optional[IdType] = None, limit: Optional[int] = None) -> Union[AdminDomainBlock, PaginatableList[AdminDomainBlock]]:
"""
Fetches a list of blocked domains. Requires scope `admin:read:domain_blocks`.
Provide an `id` to fetch a specific domain block based on its database id.
Returns a list of :ref:`admin domain block dicts <admin domain block dicts>`, raises a `MastodonAPIError` if the specified block does not exist.
"""
if max_id is not None:
max_id = self.__unpack_id(max_id)
if min_id is not None:
min_id = self.__unpack_id(min_id)
if since_id is not None:
since_id = self.__unpack_id(since_id)
if id is not None:
id = self.__unpack_id(id)
return self.__api_request('GET', f'/api/v1/admin/domain_blocks/{id}')
else:
params = self.__generate_params(locals(), ['limit'])
return self.__api_request('GET', '/api/v1/admin/domain_blocks/', params)
[docs]
@api_version("4.0.0", "4.0.0", _DICT_VERSION_ADMIN_DOMAIN_BLOCK)
def admin_create_domain_block(self, domain: str, severity: Optional[str] = None, reject_media: Optional[bool] = None,
reject_reports: Optional[bool] = None, private_comment: Optional[str] = None,
public_comment: Optional[str] = None, obfuscate: Optional[bool] = None) -> AdminDomainBlock:
"""
Perform a moderation action on a domain. Requires scope `admin:write:domain_blocks`.
Valid severities are:
* "silence" - hide all posts from federated timelines and do not show notifications to local users from the remote instance's users unless they are following the remote user.
* "suspend" - deny interactions with this instance going forward. This action is reversible.
* "limit" - generally used with reject_media=true to force reject media from an instance without silencing or suspending..
If no action is specified, the domain is only silenced.
`domain` is the domain to block. Note that using the top level domain will also imapct all subdomains. ie, example.com will also impact subdomain.example.com.
`reject_media` will not download remote media on to your local instance media storage.
`reject_reports` ignores all reports from the remote instance.
`private_comment` sets a private admin comment for the domain.
`public_comment` sets a publicly available comment for this domain, which will be available to local users and may be available to everyone depending on your settings.
`obfuscate` censors some part of the domain name. Useful if the domain name contains unwanted words like slurs.
Returns the new domain block as an :ref:`admin domain block dict <admin domain block dict>`.
"""
if domain is None:
raise AttributeError("Must provide a domain to block a domain")
params = self.__generate_params(locals())
return self.__api_request('POST', '/api/v1/admin/domain_blocks/', params)
[docs]
@api_version("4.0.0", "4.0.0", _DICT_VERSION_ADMIN_DOMAIN_BLOCK)
def admin_update_domain_block(self, id, severity: Optional[str] = None, reject_media: Optional[bool] = None, reject_reports: Optional[bool] = None,
private_comment: Optional[str] = None, public_comment: Optional[str] = None, obfuscate: Optional[bool] = None) -> AdminDomainBlock:
"""
Modify existing moderation action on a domain. Requires scope `admin:write:domain_blocks`.
Valid severities are:
* "silence" - hide all posts from federated timelines and do not show notifications to local users from the remote instance's users unless they are following the remote user.
* "suspend" - deny interactions with this instance going forward. This action is reversible.
* "limit" - generally used with reject_media=true to force reject media from an instance without silencing or suspending.
If no action is specified, the domain is only silenced.
`domain` is the domain to block. Note that using the top level domain will also imapct all subdomains. ie, example.com will also impact subdomain.example.com.
`reject_media` will not download remote media on to your local instance media storage.
`reject_reports` ignores all reports from the remote instance.
`private_comment` sets a private admin comment for the domain.
`public_comment` sets a publicly available comment for this domain, which will be available to local users and may be available to everyone depending on your settings.
`obfuscate` censors some part of the domain name. Useful if the domain name contains unwanted words like slurs.
Returns the modified domain block as an :ref:`admin domain block dict <admin domain block dict>`, raises a `MastodonAPIError` if the specified block does not exist.
"""
if id is None:
raise AttributeError("Must provide an id to modify the existing moderation actions on a given domain.")
id = self.__unpack_id(id)
params = self.__generate_params(locals(), ["id"])
return self.__api_request('PUT', f'/api/v1/admin/domain_blocks/{id}', params)
[docs]
@api_version("4.0.0", "4.0.0", _DICT_VERSION_ADMIN_DOMAIN_BLOCK)
def admin_delete_domain_block(self, id = Union[AdminDomainBlock, IdType]):
"""
Removes moderation action against a given domain. Requires scope `admin:write:domain_blocks`.
Provide an `id` to remove a specific domain block based on its database id.
Raises a `MastodonAPIError` if the specified block does not exist.
"""
if id is not None:
id = self.__unpack_id(id)
self.__api_request('DELETE', f'/api/v1/admin/domain_blocks/{id}')
else:
raise AttributeError("You must provide an id of an existing domain block to remove it.")
[docs]
@api_version("3.5.0", "3.5.0", _DICT_VERSION_ADMIN_MEASURE)
def admin_measures(self, start_at, end_at, active_users: bool = False, new_users: bool = False, interactions: bool = False, opened_reports: bool = False, resolved_reports: bool = False,
tag_accounts: Optional[Union[Tag, IdType]] = None, tag_uses: Optional[Union[Tag, IdType]] = None, tag_servers: Optional[Union[Tag, IdType]] = None,
instance_accounts: Optional[str] = None, instance_media_attachments: Optional[str] = None, instance_reports: Optional[str] = None,
instance_statuses: Optional[str] = None, instance_follows: Optional[str] = None, instance_followers: Optional[str] = None) -> NonPaginatableList[AdminMeasure]:
"""
Retrieves numerical instance information for the time period (at day granularity) between `start_at` and `end_at`.
* `active_users`: Pass true to retrieve the number of active users on your instance within the time period
* `new_users`: Pass true to retrieve the number of users who joined your instance within the time period
* `interactions`: Pass true to retrieve the number of interactions (favourites, boosts, replies) on local statuses within the time period
* `opened_reports`: Pass true to retrieve the number of reports filed within the time period
* `resolved_reports` = Pass true to retrieve the number of reports resolved within the time period
* `tag_accounts`: Pass a tag ID to get the number of accounts which used that tag in at least one status within the time period
* `tag_uses`: Pass a tag ID to get the number of statuses which used that tag within the time period
* `tag_servers`: Pass a tag ID to to get the number of remote origin servers for statuses which used that tag within the time period
* `instance_accounts`: Pass a domain to get the number of accounts originating from that remote domain within the time period
* `instance_media_attachments`: Pass a domain to get the amount of space used by media attachments from that remote domain within the time period
* `instance_reports`: Pass a domain to get the number of reports filed against accounts from that remote domain within the time period
* `instance_statuses`: Pass a domain to get the number of statuses originating from that remote domain within the time period
* `instance_follows`: Pass a domain to get the number of accounts from a remote domain followed by that local user within the time period
* `instance_followers`: Pass a domain to get the number of local accounts followed by accounts from that remote domain within the time period
This API call is relatively expensive - watch your servers load if you want to get a lot of statistical data. Especially the instance_statuses stats
might take a long time to compute and, in fact, time out.
There is currently no way to get tag IDs implemented in Mastodon.py, because the Mastodon public API does not implement one. This will be fixed in a future
release.
Returns a list of :ref:`admin measure dicts <admin measure dicts>`.
"""
params_init = locals()
keys = []
for key in ["active_users", "new_users", "interactions", "opened_reports", "resolved_reports"]:
if params_init[key] == True:
keys.append(key)
params = {}
for key in ["tag_accounts", "tag_uses", "tag_servers"]:
if params_init[key] is not None:
keys.append(key)
params[key] = {"id": self.__unpack_id(params_init[key])}
for key in ["instance_accounts", "instance_media_attachments", "instance_reports", "instance_statuses", "instance_follows", "instance_followers"]:
if params_init[key] is not None:
keys.append(key)
params[key] = {"domain": Mastodon.__deprotocolize(params_init[key]).split("/")[0]}
if len(keys) == 0:
raise MastodonIllegalArgumentError("Must request at least one metric.")
params["keys"] = keys
params["start_at"] = self.__consistent_isoformat_utc(start_at)
params["end_at"] = self.__consistent_isoformat_utc(end_at)
return self.__api_request('POST', '/api/v1/admin/measures', params, use_json=True)
[docs]
@api_version("3.5.0", "3.5.0", _DICT_VERSION_ADMIN_DIMENSION)
def admin_dimensions(self, start_at: datetime, end_at: datetime, limit: Optional[int] = None, languages: bool = False, sources: bool = False,
servers: bool = False, space_usage: bool = False, software_versions: bool = False, tag_servers: Optional[Union[Tag, IdType]] = None,
tag_languages: Optional[Union[Tag, IdType]] = None, instance_accounts: Optional[str] = None, instance_languages: Optional[str] = None) -> NonPaginatableList[AdminDimension]:
"""
Retrieves primarily categorical instance information for the time period (at day granularity) between `start_at` and `end_at`.
* `languages`: Pass true to get the most-used languages on this server
* `sources`: Pass true to get the most-used client apps on this server
* `servers`: Pass true to get the remote servers with the most statuses
* `space_usage`: Pass true to get the how much space is used by different components your software stack
* `software_versions`: Pass true to get the version numbers for your software stack
* `tag_servers`: Pass a tag ID to get the most-common servers for statuses including a trending tag
* `tag_languages`: Pass a tag ID to get the most-used languages for statuses including a trending tag
* `instance_accounts`: Pass a domain to get the most-followed accounts from a remote server
* `instance_languages`: Pass a domain to get the most-used languages from a remote server
Pass `limit` to set how many results you want on queries where that makes sense.
This API call is relatively expensive - watch your servers load if you want to get a lot of statistical data.
There is currently no way to get tag IDs implemented in Mastodon.py, because the Mastodon public API does not implement one. This will be fixed in a future
release.
Returns a list of :ref:`admin dimension dicts <admin dimension dicts>`.
"""
params_init = locals()
keys = []
for key in ["languages", "sources", "servers", "space_usage", "software_versions"]:
if params_init[key] == True:
keys.append(key)
params = {}
for key in ["tag_servers", "tag_languages"]:
if params_init[key] is not None:
keys.append(key)
params[key] = {"id": self.__unpack_id(params_init[key])}
for key in ["instance_accounts", "instance_languages"]:
if params_init[key] is not None:
keys.append(key)
params[key] = {"domain": Mastodon.__deprotocolize(params_init[key]).split("/")[0]}
if len(keys) == 0:
raise MastodonIllegalArgumentError("Must request at least one dimension.")
params["keys"] = keys
if limit is not None:
params["limit"] = limit
params["start_at"] = self.__consistent_isoformat_utc(start_at)
params["end_at"] = self.__consistent_isoformat_utc(end_at)
return self.__api_request('POST', '/api/v1/admin/dimensions', params, use_json=True)
[docs]
@api_version("3.5.0", "3.5.0", _DICT_VERSION_ADMIN_RETENTION)
def admin_retention(self, start_at: datetime, end_at: datetime, frequency: str = "day") -> NonPaginatableList[AdminRetention]:
"""
Gets user retention statistics (at `frequency` - "day" or "month" - granularity) between `start_at` and `end_at`.
"""
if not frequency in ["day", "month"]:
raise MastodonIllegalArgumentError("Frequency must be day or month")
params = {
"start_at": self.__consistent_isoformat_utc(start_at),
"end_at": self.__consistent_isoformat_utc(end_at),
"frequency": frequency
}
return self.__api_request('POST', '/api/v1/admin/retention', params)