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.

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())

Exceptions

exception atoot.MastodonError

Base class for all mastodon exceptions

exception atoot.NetworkError
exception atoot.ApiError
exception atoot.ClientError
exception atoot.UnauthorizedError
exception atoot.ForbiddenError
exception atoot.NotFoundError
exception atoot.ConflictError
exception atoot.GoneError
exception atoot.UnprocessedError
exception atoot.RatelimitError
exception atoot.ServerError
exception atoot.UnavailableError