2022-11-30 23:39:08 +00:00
# admin.py - admin / moderation endpoints
2023-06-19 21:35:03 +00:00
from mastodon . versions import _DICT_VERSION_ADMIN_ACCOUNT , _DICT_VERSION_REPORT , _DICT_VERSION_HASHTAG , _DICT_VERSION_STATUS , _DICT_VERSION_CARD , \
2022-11-30 23:39:08 +00:00
_DICT_VERSION_ADMIN_DOMAIN_BLOCK , _DICT_VERSION_ADMIN_MEASURE , _DICT_VERSION_ADMIN_DIMENSION , _DICT_VERSION_ADMIN_RETENTION
2023-06-19 21:35:03 +00:00
from mastodon . errors import MastodonIllegalArgumentError
from mastodon . utility import api_version
2022-11-30 23:39:08 +00:00
2023-06-19 21:35:03 +00:00
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
2023-01-02 13:39:16 +00:00
2022-11-30 23:39:08 +00:00
class Mastodon ( Internals ) :
###
# Moderation API
###
@api_version ( " 2.9.1 " , " 4.0.0 " , _DICT_VERSION_ADMIN_ACCOUNT )
2023-06-19 21:35:03 +00:00
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 :
2022-11-30 23:39:08 +00:00
"""
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 > ` .
2023-06-19 21:35:03 +00:00
Pagination on this is a bit weird , so I would recommend not doing that and instead manually fetching .
2022-11-30 23:39:08 +00:00
"""
if max_id is not None :
2023-06-19 21:35:03 +00:00
max_id = self . __unpack_id ( max_id )
2022-11-30 23:39:08 +00:00
if min_id is not None :
2023-06-19 21:35:03 +00:00
min_id = self . __unpack_id ( min_id )
2022-11-30 23:39:08 +00:00
if since_id is not None :
2023-06-19 21:35:03 +00:00
since_id = self . __unpack_id ( since_id )
2022-11-30 23:39:08 +00:00
if role_ids is not None :
if not isinstance ( role_ids , list ) :
role_ids = [ role_ids ]
2022-12-03 21:04:26 +00:00
role_ids = [ self . __unpack_id ( x ) for x in role_ids ]
2022-11-30 23:39:08 +00:00
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 )
@api_version ( " 2.9.1 " , " 2.9.1 " , _DICT_VERSION_ADMIN_ACCOUNT )
2023-06-19 21:35:03 +00:00
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 ) :
2022-11-30 23:39:08 +00:00
"""
2023-01-02 13:39:16 +00:00
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 .
2022-11-30 23:39:08 +00:00
! ! ! ! ! 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 . ! ! ! ! !
2023-06-19 21:35:03 +00:00
Pagination on this is a bit weird , so I would recommend not doing that and instead manually fetching .
2022-11-30 23:39:08 +00:00
"""
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
)
@api_version ( " 2.9.1 " , " 2.9.1 " , _DICT_VERSION_ADMIN_ACCOUNT )
2023-06-19 21:35:03 +00:00
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 :
2022-11-30 23:39:08 +00:00
"""
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 > ` .
2023-06-19 21:35:03 +00:00
Pagination on this is a bit weird , so I would recommend not doing that and instead manually fetching .
2022-11-30 23:39:08 +00:00
"""
if max_id is not None :
2023-06-19 21:35:03 +00:00
max_id = self . __unpack_id ( max_id )
2022-11-30 23:39:08 +00:00
if min_id is not None :
2023-06-19 21:35:03 +00:00
min_id = self . __unpack_id ( min_id )
2022-11-30 23:39:08 +00:00
if since_id is not None :
2023-06-19 21:35:03 +00:00
since_id = self . __unpack_id ( since_id )
2022-11-30 23:39:08 +00:00
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 )
@api_version ( " 2.9.1 " , " 2.9.1 " , _DICT_VERSION_ADMIN_ACCOUNT )
2023-06-19 21:35:03 +00:00
def admin_account ( self , id : Union [ Account , AdminAccount , IdType ] ) - > AdminAccount :
2022-11-30 23:39:08 +00:00
"""
Fetches a single : ref : ` admin account dict < admin account dict > ` for the user with the given id .
"""
id = self . __unpack_id ( id )
2022-12-02 21:04:23 +00:00
return self . __api_request ( ' GET ' , f ' /api/v1/admin/accounts/ { id } ' )
2022-11-30 23:39:08 +00:00
@api_version ( " 2.9.1 " , " 2.9.1 " , _DICT_VERSION_ADMIN_ACCOUNT )
2023-06-19 21:35:03 +00:00
def admin_account_enable ( self , id : Union [ Account , AdminAccount , IdType ] ) - > AdminAccount :
2022-11-30 23:39:08 +00:00
"""
Reenables login for a local account for which login has been disabled .
2023-06-19 21:35:03 +00:00
The returned object reflects the updates to the account .
2022-11-30 23:39:08 +00:00
"""
id = self . __unpack_id ( id )
2022-12-02 21:04:23 +00:00
return self . __api_request ( ' POST ' , f ' /api/v1/admin/accounts/ { id } /enable ' )
2022-11-30 23:39:08 +00:00
@api_version ( " 2.9.1 " , " 2.9.1 " , _DICT_VERSION_ADMIN_ACCOUNT )
2023-06-19 21:35:03 +00:00
def admin_account_approve ( self , id : Union [ Account , AdminAccount , IdType ] ) - > AdminAccount :
2022-11-30 23:39:08 +00:00
"""
Approves a pending account .
2023-06-19 21:35:03 +00:00
The returned object reflects the updates to the account .
2022-11-30 23:39:08 +00:00
"""
id = self . __unpack_id ( id )
2022-12-02 21:04:23 +00:00
return self . __api_request ( ' POST ' , f ' /api/v1/admin/accounts/ { id } /approve ' )
2022-11-30 23:39:08 +00:00
@api_version ( " 2.9.1 " , " 2.9.1 " , _DICT_VERSION_ADMIN_ACCOUNT )
2023-06-19 21:35:03 +00:00
def admin_account_reject ( self , id : Union [ Account , AdminAccount , IdType ] ) - > AdminAccount :
2022-11-30 23:39:08 +00:00
"""
Rejects and deletes a pending account .
2023-06-19 21:35:03 +00:00
The returned object is that of the now - deleted account .
2022-11-30 23:39:08 +00:00
"""
id = self . __unpack_id ( id )
2022-12-02 21:04:23 +00:00
return self . __api_request ( ' POST ' , f ' /api/v1/admin/accounts/ { id } /reject ' )
2022-11-30 23:39:08 +00:00
@api_version ( " 2.9.1 " , " 2.9.1 " , _DICT_VERSION_ADMIN_ACCOUNT )
2023-06-19 21:35:03 +00:00
def admin_account_unsilence ( self , id : Union [ Account , AdminAccount , IdType ] ) - > AdminAccount :
2022-11-30 23:39:08 +00:00
"""
Unsilences an account .
2023-06-19 21:35:03 +00:00
The returned object reflects the updates to the account .
2022-11-30 23:39:08 +00:00
"""
id = self . __unpack_id ( id )
2022-12-02 21:04:23 +00:00
return self . __api_request ( ' POST ' , f ' /api/v1/admin/accounts/ { id } /unsilence ' )
2022-11-30 23:39:08 +00:00
@api_version ( " 2.9.1 " , " 2.9.1 " , _DICT_VERSION_ADMIN_ACCOUNT )
2023-06-19 21:35:03 +00:00
def admin_account_unsuspend ( self , id : Union [ Account , AdminAccount , IdType ] ) - > AdminAccount :
2022-11-30 23:39:08 +00:00
"""
Unsuspends an account .
2023-06-19 21:35:03 +00:00
The returned object reflects the updates to the account .
2022-11-30 23:39:08 +00:00
"""
id = self . __unpack_id ( id )
2022-12-02 21:04:23 +00:00
return self . __api_request ( ' POST ' , f ' /api/v1/admin/accounts/ { id } /unsuspend ' )
2022-11-30 23:39:08 +00:00
@api_version ( " 3.3.0 " , " 3.3.0 " , _DICT_VERSION_ADMIN_ACCOUNT )
2023-06-19 21:35:03 +00:00
def admin_account_delete ( self , id : Union [ Account , AdminAccount , IdType ] ) - > AdminAccount :
2022-11-30 23:39:08 +00:00
"""
Delete a local user account .
2023-06-19 21:35:03 +00:00
The returned object reflects the updates to the account .
2022-11-30 23:39:08 +00:00
"""
id = self . __unpack_id ( id )
2022-12-02 21:04:23 +00:00
return self . __api_request ( ' DELETE ' , f ' /api/v1/admin/accounts/ { id } ' )
2022-11-30 23:39:08 +00:00
@api_version ( " 3.3.0 " , " 3.3.0 " , _DICT_VERSION_ADMIN_ACCOUNT )
2023-06-19 21:35:03 +00:00
def admin_account_unsensitive ( self , id : Union [ Account , AdminAccount , IdType ] ) - > AdminAccount :
2022-11-30 23:39:08 +00:00
"""
Unmark an account as force - sensitive .
2023-06-19 21:35:03 +00:00
The returned object reflects the updates to the account .
2022-11-30 23:39:08 +00:00
"""
id = self . __unpack_id ( id )
2022-12-02 22:48:39 +00:00
return self . __api_request ( ' POST ' , f ' /api/v1/admin/accounts/ { id } /unsensitive ' )
2022-11-30 23:39:08 +00:00
@api_version ( " 2.9.1 " , " 2.9.1 " , " 2.9.1 " )
2023-06-19 21:35:03 +00:00
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 ) :
2022-11-30 23:39:08 +00:00
"""
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
2022-12-02 21:04:23 +00:00
self . __api_request ( ' POST ' , f ' /api/v1/admin/accounts/ { id } /action ' , params )
2022-11-30 23:39:08 +00:00
@api_version ( " 2.9.1 " , " 2.9.1 " , _DICT_VERSION_REPORT )
2023-06-23 20:16:44 +00:00
def admin_reports ( self , resolved : Optional [ bool ] = False , account_id : Optional [ Union [ Account , AdminAccount , IdType ] ] = None ,
2023-06-19 21:35:03 +00:00
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 ] :
2022-11-30 23:39:08 +00:00
"""
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 :
2023-06-19 21:35:03 +00:00
max_id = self . __unpack_id ( max_id )
2022-11-30 23:39:08 +00:00
if min_id is not None :
2023-06-19 21:35:03 +00:00
min_id = self . __unpack_id ( min_id )
2022-11-30 23:39:08 +00:00
if since_id is not None :
2023-06-19 21:35:03 +00:00
since_id = self . __unpack_id ( since_id )
2022-11-30 23:39:08 +00:00
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 )
@api_version ( " 2.9.1 " , " 2.9.1 " , _DICT_VERSION_REPORT )
2023-06-19 21:35:03 +00:00
def admin_report ( self , id : Union [ AdminReport , IdType ] ) - > AdminReport :
2022-11-30 23:39:08 +00:00
"""
Fetches the report with the given id .
"""
id = self . __unpack_id ( id )
2022-12-02 21:04:23 +00:00
return self . __api_request ( ' GET ' , f ' /api/v1/admin/reports/ { id } ' )
2022-11-30 23:39:08 +00:00
@api_version ( " 2.9.1 " , " 2.9.1 " , _DICT_VERSION_REPORT )
2023-06-19 21:35:03 +00:00
def admin_report_assign ( self , id : Union [ AdminReport , IdType ] ) - > AdminReport :
2022-11-30 23:39:08 +00:00
"""
Assigns the given report to the logged - in user .
2023-06-19 21:35:03 +00:00
The returned object reflects the updates to the report .
2022-11-30 23:39:08 +00:00
"""
id = self . __unpack_id ( id )
2022-12-02 21:04:23 +00:00
return self . __api_request ( ' POST ' , f ' /api/v1/admin/reports/ { id } /assign_to_self ' )
2022-11-30 23:39:08 +00:00
@api_version ( " 2.9.1 " , " 2.9.1 " , _DICT_VERSION_REPORT )
2023-06-19 21:35:03 +00:00
def admin_report_unassign ( self , id : Union [ AdminReport , IdType ] ) - > AdminReport :
2022-11-30 23:39:08 +00:00
"""
Unassigns the given report from the logged - in user .
2023-06-19 21:35:03 +00:00
The returned object reflects the updates to the report .
2022-11-30 23:39:08 +00:00
"""
id = self . __unpack_id ( id )
2022-12-02 21:04:23 +00:00
return self . __api_request ( ' POST ' , f ' /api/v1/admin/reports/ { id } /unassign ' )
2022-11-30 23:39:08 +00:00
@api_version ( " 2.9.1 " , " 2.9.1 " , _DICT_VERSION_REPORT )
2023-06-19 21:35:03 +00:00
def admin_report_reopen ( self , id : Union [ AdminReport , IdType ] ) - > AdminReport :
2022-11-30 23:39:08 +00:00
"""
Reopens a closed report .
2023-06-19 21:35:03 +00:00
The returned object reflects the updates to the report .
2022-11-30 23:39:08 +00:00
"""
id = self . __unpack_id ( id )
2022-12-02 21:04:23 +00:00
return self . __api_request ( ' POST ' , f ' /api/v1/admin/reports/ { id } /reopen ' )
2022-11-30 23:39:08 +00:00
@api_version ( " 2.9.1 " , " 2.9.1 " , _DICT_VERSION_REPORT )
2023-06-19 21:35:03 +00:00
def admin_report_resolve ( self , id : Union [ AdminReport , IdType ] ) - > AdminReport :
2022-11-30 23:39:08 +00:00
"""
Marks a report as resolved ( without taking any action ) .
2023-06-19 21:35:03 +00:00
The returned object reflects the updates to the report .
2022-11-30 23:39:08 +00:00
"""
id = self . __unpack_id ( id )
2022-12-02 21:04:23 +00:00
return self . __api_request ( ' POST ' , f ' /api/v1/admin/reports/ { id } /resolve ' )
2022-11-30 23:39:08 +00:00
@api_version ( " 3.5.0 " , " 3.5.0 " , _DICT_VERSION_HASHTAG )
2023-06-19 21:35:03 +00:00
def admin_trending_tags ( self , limit : Optional [ int ] = None ) - > NonPaginatableList [ Tag ] :
2022-11-30 23:39:08 +00:00
"""
Admin version of : ref : ` trending_tags ( ) < trending_tags ( ) > ` . Includes unapproved tags .
2023-06-19 21:35:03 +00:00
The returned list is sorted , descending , by the instance ' s trending algorithm.
2022-11-30 23:39:08 +00:00
"""
params = self . __generate_params ( locals ( ) )
return self . __api_request ( ' GET ' , ' /api/v1/admin/trends/tags ' , params )
@api_version ( " 3.5.0 " , " 3.5.0 " , _DICT_VERSION_STATUS )
2023-06-19 21:35:03 +00:00
def admin_trending_statuses ( self ) - > NonPaginatableList [ Status ] :
2022-11-30 23:39:08 +00:00
"""
Admin version of : ref : ` trending_statuses ( ) < trending_statuses ( ) > ` . Includes unapproved tags .
2023-06-19 21:35:03 +00:00
The returned list is sorted , descending , by the instance ' s trending algorithm.
2022-11-30 23:39:08 +00:00
"""
params = self . __generate_params ( locals ( ) )
return self . __api_request ( ' GET ' , ' /api/v1/admin/trends/statuses ' , params )
@api_version ( " 3.5.0 " , " 3.5.0 " , _DICT_VERSION_CARD )
2023-06-19 21:35:03 +00:00
def admin_trending_links ( self ) - > NonPaginatableList [ PreviewCard ] :
2022-11-30 23:39:08 +00:00
"""
Admin version of : ref : ` trending_links ( ) < trending_links ( ) > ` . Includes unapproved tags .
2023-06-19 21:35:03 +00:00
The returned list is sorted , descending , by the instance ' s trending algorithm.
2022-11-30 23:39:08 +00:00
"""
params = self . __generate_params ( locals ( ) )
return self . __api_request ( ' GET ' , ' /api/v1/admin/trends/links ' , params )
@api_version ( " 4.0.0 " , " 4.0.0 " , _DICT_VERSION_ADMIN_DOMAIN_BLOCK )
2023-06-19 21:35:03 +00:00
def admin_domain_blocks ( self , id : Optional [ IdType ] = None , max_id : Optional [ IdType ] = None , min_id : Optional [ IdType ] = None ,
2023-06-20 21:15:40 +00:00
since_id : Optional [ IdType ] = None , limit : Optional [ int ] = None ) - > Union [ AdminDomainBlock , PaginatableList [ AdminDomainBlock ] ] :
2022-11-30 23:39:08 +00:00
"""
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 .
"""
2023-04-23 17:34:01 +00:00
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 )
2022-11-30 23:39:08 +00:00
if id is not None :
id = self . __unpack_id ( id )
2022-12-02 21:04:23 +00:00
return self . __api_request ( ' GET ' , f ' /api/v1/admin/domain_blocks/ { id } ' )
2022-11-30 23:39:08 +00:00
else :
2023-01-02 13:39:16 +00:00
params = self . __generate_params ( locals ( ) , [ ' limit ' ] )
2022-11-30 23:39:08 +00:00
return self . __api_request ( ' GET ' , ' /api/v1/admin/domain_blocks/ ' , params )
2023-01-02 13:39:16 +00:00
2022-11-30 23:39:08 +00:00
@api_version ( " 4.0.0 " , " 4.0.0 " , _DICT_VERSION_ADMIN_DOMAIN_BLOCK )
2023-06-19 21:35:03 +00:00
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 :
2022-11-30 23:39:08 +00:00
"""
Perform a moderation action on a domain . Requires scope ` admin : write : domain_blocks ` .
Valid severities are :
2023-01-02 13:39:16 +00:00
* " 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.
2022-11-30 23:39:08 +00:00
* " 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 )
@api_version ( " 4.0.0 " , " 4.0.0 " , _DICT_VERSION_ADMIN_DOMAIN_BLOCK )
2023-06-19 21:35:03 +00:00
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 :
2022-11-30 23:39:08 +00:00
"""
Modify existing moderation action on a domain . Requires scope ` admin : write : domain_blocks ` .
Valid severities are :
2023-01-02 13:39:16 +00:00
* " 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.
2022-11-30 23:39:08 +00:00
* " 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 " ] )
2022-12-02 21:04:23 +00:00
return self . __api_request ( ' PUT ' , f ' /api/v1/admin/domain_blocks/ { id } ' , params )
2022-11-30 23:39:08 +00:00
@api_version ( " 4.0.0 " , " 4.0.0 " , _DICT_VERSION_ADMIN_DOMAIN_BLOCK )
2023-06-19 21:35:03 +00:00
def admin_delete_domain_block ( self , id = Union [ AdminDomainBlock , IdType ] ) :
2022-11-30 23:39:08 +00:00
"""
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 )
2022-12-02 21:04:23 +00:00
self . __api_request ( ' DELETE ' , f ' /api/v1/admin/domain_blocks/ { id } ' )
2022-11-30 23:39:08 +00:00
else :
raise AttributeError ( " You must provide an id of an existing domain block to remove it. " )
@api_version ( " 3.5.0 " , " 3.5.0 " , _DICT_VERSION_ADMIN_MEASURE )
2023-06-19 21:35:03 +00:00
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 ] :
2022-11-30 23:39:08 +00:00
"""
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 )
2023-01-02 13:39:16 +00:00
2022-11-30 23:39:08 +00:00
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 )
2023-01-02 13:39:16 +00:00
2022-11-30 23:39:08 +00:00
return self . __api_request ( ' POST ' , ' /api/v1/admin/measures ' , params , use_json = True )
@api_version ( " 3.5.0 " , " 3.5.0 " , _DICT_VERSION_ADMIN_DIMENSION )
2023-06-19 21:35:03 +00:00
def admin_dimensions ( self , start_at : datetime , end_at : datetime , limit : Optional [ int ] = None , languages : bool = False , sources : bool = False ,
2023-06-23 20:16:44 +00:00
servers : bool = False , space_usage : bool = False , software_versions : bool = False , tag_servers : Optional [ Union [ Tag , IdType ] ] = None ,
2023-06-19 21:35:03 +00:00
tag_languages : Optional [ Union [ Tag , IdType ] ] = None , instance_accounts : Optional [ str ] = None , instance_languages : Optional [ str ] = None ) - > NonPaginatableList [ AdminDimension ] :
2022-11-30 23:39:08 +00:00
"""
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 )
2023-01-02 13:39:16 +00:00
2022-11-30 23:39:08 +00:00
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 )
2023-01-02 13:39:16 +00:00
2022-11-30 23:39:08 +00:00
return self . __api_request ( ' POST ' , ' /api/v1/admin/dimensions ' , params , use_json = True )
@api_version ( " 3.5.0 " , " 3.5.0 " , _DICT_VERSION_ADMIN_RETENTION )
2024-02-11 13:18:53 +00:00
def admin_retention ( self , start_at : datetime , end_at : datetime , frequency : str = " day " ) - > NonPaginatableList [ AdminRetention ] :
2022-11-30 23:39:08 +00:00
"""
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
}
2023-01-02 13:39:16 +00:00
return self . __api_request ( ' POST ' , ' /api/v1/admin/retention ' , params )