Developer Interface¶
This page of the documentation will cover all methods and classes available to the developer.
Context manager¶
-
atoot.
client
(*args, **kwargs)¶ Context manager for using MastodonAPI object. Arguments are the same as for
atoot.MastodonAPI.create()
factory method.Usage:
async with atoot.client(instance, access_token=access_token) as c: # Retrieve your account information print(await c.verify_account_credentials()) # Create a status print(await c.create_status(status="Hello world!")) # Get 3 pages of a local timeline print(await c.get_n_pages(c.public_timeline(local=True), n=3))
Core Interface¶
-
classmethod
MastodonAPI.
create
(instance, client_id=None, client_secret=None, access_token=None, use_https=True, session=None)¶ Async factory method.
Parameters: - instance – domain name of an instance, i.e. ‘mastodon.social’
- client_id – (optional)
- client_secret – (optional)
- access_token – (optional)
- use_https – (optional) set False to use plain text http
- session – (optional) aiohttp.ClientSession instance
Returns: MastodonAPI instance.
Usage:
>>> c = await atoot.MastodonAPI.create("botsin.space", access_token="...") >>> print(await c.verify_account_credentials()) >>> await c.close()
-
MastodonAPI.
close
()¶ Close all network connections and shut down MastodonAPI
-
static
MastodonAPI.
create_app
(session, instance, use_https=True, scopes='read write follow', client_name='atoot', client_website=None)¶ Create a new application to obtain OAuth2 credentials.
Parameters: - session – aiohttp.ClientSession instance
- instance – domain name of an instance, i.e. ‘mastodon.social’
- use_https – (optional) set False to use plain text http
- scopes – (optional) application scope, default is ‘read write follow’
- client_name – (optional)
- client_website – (optional)
Returns: client_id and client_secret values.
Usage:
>>> async with aiohttp.ClientSession() as session: >>> client_id, client_secret = await atoot.MastodonAPI.create_app(session, >>> "botsin.space", client_name="test_bot", >>> client_website="https://example.com/") >>> print(client_id, client_secret)
-
static
MastodonAPI.
browser_login_url
(instance, client_id, use_https=True)¶ Returns a URL for manual log in via browser
Parameters: - instance – domain name of an instance, i.e. ‘mastodon.social’
- client_id –
- use_https – (optional) set False to use plain text http
-
static
MastodonAPI.
login
(session, instance, client_id, client_secret, use_https=True, username=None, password=None, oauth_code=None, scope='read write follow')¶ Login to the MastodonAPI instance.
Parameters: - session – aiohttp.ClientSession instance
- instance – domain name of an instance, i.e. ‘mastodon.social’
- client_id –
- client_secret –
- use_https – (optional) set False to use plain text http
- username – (optional) e-mail of your account
- password – (optional) password of your account
- oauth_code – (optional) code from a browser_login_url page
- scope – (optional) application scope, default is ‘read write follow’
Returns: OAuth access_code. Store this access_token for later use with authenticated client.
-
MastodonAPI.
revoke_token
(client_id, client_secret, token)¶ Revoke an access token to make it no longer valid for use.
-
MastodonAPI.
verify_app_credentials
()¶ Confirm that the app’s OAuth2 credentials work.
-
MastodonAPI.
register_account
(username, email, password, agreement, locale, reason=None, params={})¶ Creates a user and account records.
Returns: Returns an account access token for the app that initiated the request. The app should save this token for later, and should wait for the user to confirm their account by clicking a link in their email inbox.
Accounts¶
-
MastodonAPI.
verify_account_credentials
()¶ Test to make sure that the user token works.
Returns: user’s own Account with Source
-
MastodonAPI.
update_account_credentials
(discoverable=None, bot=None, display_name=None, note=None, avatar=None, header=None, locked=None, fields_attributes=None, params={})¶ Update the user’s display and preferences.
Parameters: - discoverable – (optional) Whether the account should be shown in the profile directory.
- bot – (optional) Whether the account has a bot flag.
- display_name – (optional) The display name to use for the profile.
- note – (optional) The account bio.
- avatar – (optional) Avatar image encoded using multipart/form-data
- header – (optional) Header image encoded using multipart/form-data
- locked – (optional) Whether manual approval of follow requests is required.
- fields_attributes – (optional) Profile metadata name and value. (By default, max 4 fields and 255 characters per property/value)
-
MastodonAPI.
account
(account)¶ View information about a profile.
Parameters: account – Account object or id string Returns: Account object
-
MastodonAPI.
account_statuses
(account)¶ Statuses posted to the given account.
Parameters: account – Account object or id string Returns: a list of statuses
-
MastodonAPI.
account_follow
(account)¶ Follow the given account.
-
MastodonAPI.
account_unfollow
(account)¶ Unfollow the given account.
-
MastodonAPI.
account_search
(query, limit=None, resolve=None, following=None)¶ Search for matching accounts by username or display name.
Parameters: - query – What to search for
- limit – Maximum number of results. Defaults to 40.
- resolve – Attempt WebFinger lookup. Defaults to false. Use this when query is an exact address.
- following – Only who the user is following. Defaults to false.
Returns: a list of Accounts
Statuses¶
-
MastodonAPI.
create_status
(params={}, status=None, media_ids=None, poll_options=[], poll_expires_in=None, poll_multiple=None, poll_hide_totals=None, in_reply_to_id=None, sensitive=False, spoiler_text=None, visibility='public', scheduled_at=None, language=None)¶ Posts a new status.
Parameters: - status – (optional) Text content of the status. If media_ids is provided, this becomes optional. Attaching a poll is optional while status is provided.
- media_ids – (optional) Array of Attachment ids to be attached as media. If provided, status becomes optional, and poll cannot be used.
- poll_options – (optional) Array of possible answers. If provided, media_ids cannot be used, and poll[expires_in] must be provided.
- poll_expires_in – (optional) Duration the poll should be open, in seconds. If provided, media_ids cannot be used, and poll[options] must be provided.
- poll_multiple (bool) – (optional) Allow multiple choices?
- poll_hide_totals (bool) – (optional) Hide vote counts until the poll ends?
- in_reply_to_id – (optional) ID of the status being replied to, if status is a reply
- sensitive (bool) – (optional) Mark status and attached media as sensitive?
- spoiler_text – (optional) Text to be shown as a warning or subject before the actual content. Statuses are generally collapsed behind this field.
- visibility – (optional) Visibility of the posted status. Enumerable oneOf public, unlisted, private, direct.
- scheduled_at – (optional) ISO 8601 Datetime at which to schedule a status. Providing this paramter will cause ScheduledStatus to be returned instead of Status. Must be at least 5 minutes in the future.
- language – (optional) ISO 639 language code for this status.
Returns: Status object. When scheduled_at is present, ScheduledStatus is returned instead.
-
MastodonAPI.
delete_status
(status)¶ Deletes a status.
Parameters: status – Status object or id string
-
MastodonAPI.
view_status
(status)¶ View information about a status.
-
MastodonAPI.
status_context
(status)¶ View statuses above and below this status in the thread.
-
MastodonAPI.
status_favourite
(status)¶ Add a status to your favourites list.
-
MastodonAPI.
status_unfavourite
(status)¶ Remove a status from your favourites list.
-
MastodonAPI.
status_boost
(status)¶ Reshare a status.
-
MastodonAPI.
status_unboost
(status)¶ Undo a reshare of a status.
Media¶
-
MastodonAPI.
upload_attachment
(fileobj, params={}, description=None, focal=None)¶ Creates an attachment to be used with a new status.
Parameters: - fileobj – file object, i.e. fileobj=open(‘image.jpg’, ‘rb’)
- description – A plain-text description of the media, for accessibility purposes.
- focal – Two floating points (x,y), comma-delimited, ranging from -1.0 to 1.0
-
MastodonAPI.
update_attachment
(attachment, fileobj=None, params={}, description=None, focal=None)¶ Update an Attachment, before it is attached to a status and posted.
Timelines¶
-
MastodonAPI.
public_timeline
(params={}, limit=None, local=None, only_media=None)¶ View statuses from the public timeline
Parameters: - limit – Maximum number of results to return. Defaults to 20.
- local – If true, return only local statuses. Defaults to false.
- only_media – If true, return only statuses with media attachments. Defaults to false.
Returns: List of Statuses
-
MastodonAPI.
hashtag_timeline
(hashtag, params={}, limit=None, local=None, only_media=None)¶ View public statuses containing the given hashtag.
Parameters: - hashtag – Content of a #hashtag, not including # symbol.
- limit – Maximum number of results to return. Defaults to 20.
- local – If true, return only local statuses. Defaults to false.
- only_media – If true, return only statuses with media attachments. Defaults to false.
Returns: List of Statuses
-
MastodonAPI.
home_timeline
(params={}, limit=None, local=None)¶ View statuses from followed users.
Parameters: - limit – Maximum number of results to return. Defaults to 20.
- local – If true, return only local statuses. Defaults to false.
Returns: List of Statuses
-
MastodonAPI.
list_timeline
(_list, params={}, limit=None)¶ View statuses in the given list timeline.
Parameters: - _list – Local ID of the list in the database.
- limit – Maximum number of results to return. Defaults to 20.
- local – If true, return only local statuses. Defaults to false.
Returns: List of Statuses
Notifications¶
-
MastodonAPI.
get_notifications
(params={}, limit=None, exclude_types=None, account=None)¶ Receive notifications for activity on your account or statuses.
Parameters: - limit – Maximum number of results to return (default 20)
- exclude_types – Array of types to exclude (follow, favourite, reblog, mention, poll)
- account – Return only notifications received from this account
Returns: List of notifications
-
MastodonAPI.
get_notification
(notification)¶ View information about a notification with a given ID.
Parameters: notification – Returns: Notification object
-
MastodonAPI.
clear_notifications
()¶ Clear all notifications from the server.
-
MastodonAPI.
clear_notification
(notification)¶ Clear a single notification from the server.
Streaming API¶
-
MastodonAPI.
streaming
(stream, list_filter=None, tag_filter=None)¶ Asynchronous context manager for using websocket streaming API
Params stream: one of the following: user, public, public:local, hashtag, hashtag:local, list, direct Returns: aiohttp.ClientWebSocketResponse object Usage:
async with client.streaming("user") as ws: async for msg in ws: print(msg.json())
Pagination¶
Every list of entities (i.e. list of Status objects) returned by the API can be used with the following pagination methods.
-
MastodonAPI.
get_next
(response)¶ Get next page of paginated results
Parameters: response – ResponseList Usage:
>>> page1 = await client.public_timeline() >>> if page1.next: >>> page2 = await client.get_next(page1)
-
MastodonAPI.
get_previous
(response)¶ Get previous page of paginated results (see MastodonAPI.get_next)
Parameters: response – ResponseList
-
MastodonAPI.
get_n_pages
(task, n=1)¶ A shortcut function to get up to N number of pages from a paginated task.
Parameters: - task – a coroutine which returns a paginated list of objects
- n – (optional) number of pages to get
Usage:
>>> statuses = await client.get_n_pages(client.public_timeline(), n=5)
-
MastodonAPI.
get_all
(task)¶ A shortcut function to get all results from a paginated task.
Parameters: task – a coroutine which returns a paginated list of objects Usage:
>>> notifs = await client.get_all(client.get_notifications())
Exceptions¶
-
exception
atoot.
MastodonError
¶ Base class for all mastodon exceptions
-
exception
atoot.
NetworkError
¶
-
exception
atoot.
ApiError
¶
-
exception
atoot.
ClientError
¶
-
exception
atoot.
ForbiddenError
¶
-
exception
atoot.
NotFoundError
¶
-
exception
atoot.
ConflictError
¶
-
exception
atoot.
GoneError
¶
-
exception
atoot.
UnprocessedError
¶
-
exception
atoot.
RatelimitError
¶
-
exception
atoot.
ServerError
¶