Mastodon.py

from mastodon import Mastodon

# Register app - only once!
'''
Mastodon.create_app(
     'pytooterapp',
      to_file = 'pytooter_clientcred.txt'
)
'''

# Log in - either every time, or use persisted
'''
mastodon = Mastodon(client_id = 'pytooter_clientcred.txt')
mastodon.log_in(
    'pytooter',
    'incrediblygoodpassword',
    to_file = 'pytooter_usercred.txt'
)
'''

# Create actual instance
mastodon = Mastodon(
    client_id = 'pytooter_clientcred.txt',
    access_token = 'pytooter_usercred.txt'
)
mastodon.toot('Tooting from python!')

Mastodon is an ostatus based twitter-like federated social network node. It has an API that allows you to interact with its every aspect. This is a simple python wrapper for that api, provided as a single python module. By default, it talks to the Mastodon flagship instance, but it can be set to talk to any node running Mastodon.

For complete documentation on what every function returns, check the Mastodon API docs, or just play around a bit.

App registration and user authentication

Before you can use the mastodon API, you have to register your application (which gets you a client key and client secret) and then log in (which gets you an access token). These functions allow you to do those things. For convenience, once you have a client id, secret and access token, you can simply pass them to the constructor of the class, too!

Note that while it is perfectly reasonable to log back in whenever your app starts, registering a new application on every startup is not, so don’t do that - instead, register an application once, and then persist your client id and secret. Convenience methods for this are provided.

static Mastodon.create_app(client_name, scopes=['read', 'write', 'follow'], redirect_uris=None, to_file=None, api_base_url='https://mastodon.social')

Creates a new app with given client_name and scopes (read, write, follow)

Specify redirect_uris if you want users to be redirected to a certain page after authenticating. Specify to_file to persist your apps info to a file so you can use them in the constructor. Specify api_base_url if you want to register an app on an instance different from the flagship one.

Returns client_id and client_secret.

Mastodon.__init__(client_id, client_secret=None, access_token=None, api_base_url='https://mastodon.social')

Creates a new API wrapper instance based on the given client_secret and client_id. If you give a client_id and it is not a file, you must also give a secret.

You can also directly specify an access_token, directly or as a file.

Specify api_base_url if you wish to talk to an instance other than the flagship one. If a file is given as client_id, read client ID and secret from that file

Mastodon.log_in(username, password, scopes=['read', 'write', 'follow'], to_file=None)

Logs in and sets access_token to what was returned. Can persist access token to file.

Will throw an exception if username / password are wrong, scopes are not valid or granted scopes differ from requested.

Returns the access_token, as well.

Reading data: Timelines

This function allows you to access the timelines a logged in user could see, as well as hashtag timelines and the public timeline.

Mastodon.timeline(timeline='home', max_id=None, since_id=None, limit=None)

Returns statuses, most recent ones first. Timeline can be home, mentions, public or tag/:hashtag

Reading data: Statuses

These functions allow you to get information about single statuses.

Mastodon.status(id)

Returns a status.

Mastodon.status_context(id)

Returns ancestors and descendants of the status.

Mastodon.status_reblogged_by(id)

Returns a list of users that have reblogged a status.

Mastodon.status_favourited_by(id)

Returns a list of users that have favourited a status.

Reading data: Accounts

These functions allow you to get information about accounts and their relationships.

Mastodon.account(id)

Returns account.

Mastodon.account_verify_credentials()

Returns authenticated user’s account.

Mastodon.account_statuses(id, max_id=None, since_id=None, limit=None)

Returns statuses by user. Same options as timeline are permitted.

Mastodon.account_following(id)

Returns users the given user is following.

Mastodon.account_followers(id)

Returns users the given user is followed by.

Mastodon.account_relationships(id)

Returns relationships (following, followed_by, blocking) of the logged in user to a given account. id can be a list.

Mastodon.account_suggestions()

Returns accounts that the system suggests the authenticated user to follow.

Mastodon.account_search(q, limit=None)

Returns matching accounts. Will lookup an account remotely if the search term is in the username@domain format and not yet in the database.

Writing data: Statuses

These functions allow you to post statuses to Mastodon and to interact with already posted statuses.

Mastodon.status_post(status, in_reply_to_id=None, media_ids=None)

Posts a status. Can optionally be in reply to another status and contain up to four pieces of media (Uploaded via media_post()).

Returns the new status.

Mastodon.toot(status)

Synonym for status_post that only takes the status text as input.

Mastodon.status_delete(id)

Deletes a status

Mastodon.status_reblog(id)

Reblogs a status.

Returns a new status that wraps around the reblogged one.

Mastodon.status_unreblog(id)

Un-reblogs a status.

Returns the status that used to be reblogged.

Mastodon.status_favourite(id)

Favourites a status.

Returns the favourited status.

Mastodon.status_unfavourite(id)

Favourites a status.

Returns the un-favourited status.

Writing data: Accounts

These functions allow you to interact with other accounts: To (un)follow and (un)block.

Mastodon.account_follow(id)

Follows a user.

Returns the updated relationship to the user.

Mastodon.account_unfollow(id)

Unfollows a user.

Returns the updated relationship to the user.

Mastodon.account_block(id)

Blocks a user.

Returns the updated relationship to the user.

Mastodon.account_unblock(id)

Unblocks a user.

Returns the updated relationship to the user.

Writing data: Media

This function allows you to upload media to Mastodon. The returned media IDs (Up to 4 at the same time) can then be used with post_status to attach media to statuses.

Mastodon.media_post(media_file, mime_type=None)

Posts an image. media_file can either be image data or a file name. If image data is passed directly, the mime type has to be specified manually, otherwise, it is determined from the file name.

Returns the ID of the media that can then be used in status_post().

Throws a ValueError if the mime type of the passed data or file can not be determined properly.