🐘 tweepy-mastodon: Mastodon API library with Tweepy interface for Python

⚠ This library is under development! Only partial features are implemented.

An attempt to provide Mastodon API library with Tweepy-like interface, to help developers to migrate their good bot/service built with Tweepy to Mastodon easily.

Implemented API

Example usage

Please prepare your Mastodon API credentials from the developer settings page (example URL: https://mastodon.social/settings/applications).

import datetime

import tweepy_mastodon as tweepy

api_base_url = 'mastodon.social'
mastodon_client_id = 'xxxxxxx'
mastodon_client_secret = 'xxxxxxx'
mastodon_access_token = 'xxxxxxx'

auth = tweepy.OAuth1UserHandler(
    consumer_key=mastodon_client_id,
    consumer_secret=mastodon_client_secret,
    api_base_url=api_base_url
)
auth.set_access_token(mastodon_access_token)
api = tweepy.API(auth)

me = api.verify_credentials()

assert me.screen_name == 'shuuji3'
assert me.display_name == 'TAKAHASHI Shuuji 🌈✨'
assert me.url == 'https://shuuji3.xyz'
assert me.profile_background_image_url == 'https://files.mastodon.social/accounts/headers/000/936/436/original/4d6989a698953e80.jpg'
assert me.created_at == datetime.datetime(2019, 10, 8, 0, 0, tzinfo=datetime.timezone.utc)
assert me.avatar == 'https://files.mastodon.social/accounts/avatars/000/936/436/original/4854d6cf9e12cb8f.png'

assert me.favorited == False
assert me.retweeted == False
assert me.status.source == '<a href="https://elk.zone" rel="nofollow">Elk</a>'

user = api.get_user(user_id=1)
assert user.id_str == '1'
assert user.screen_name == 'Gargron'
assert user.name == 'Eugen Rochko'

user = api.get_user(screen_name='npr@mstdn.social')
assert user.id == 1201325
assert user.screen_name == 'NPR@mstdn.social'
assert user.name == 'NPR :verified:'

user_statuses = api.user_timeline(user_id=1, since_id=0, count=10)
assert len(user_statuses) == 10

status_id = 109813536848077879 # ref. https://mastodon.social/@shuuji3/109813536848077879
status = api.get_status(id=status_id)
assert status.user.screen_name == 'shuuji3'
assert 'Hello from tweepy-mastodon!' in status.text

status = api.create_favorite(id=status_id)
assert status.favorited

Installation

The easiest way to install the latest version from PyPI is by using pip:

pip install tweepy-mastodon

You can also use Git to clone the repository from GitHub to install the latest development version:

git clone https://github.com/shuuji3/tweepy-mastodon.git
cd tweepy-mastodon
pip install .

Alternatively, install directly from the GitHub repository:

pip install git+https://github.com/shuuji3/tweepy-mastodon.git

Python 3.7 - 3.11 are supported.

Links

• tweepy-mastodon Documentation (TODO: update)
• Tweepy Documentation
• halcy/Mastodon.py: Python wrapper for the Mastodon API
• Twitter API Documentation