tessl/pypi-mastodon-py
Python wrapper for the Mastodon API providing comprehensive access to social media functionality
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
accounts.mddocs/
Account Management
User account operations including profile management, following/blocking relationships, and account discovery. Provides comprehensive tools for managing social connections and user interactions on Mastodon.
Capabilities
Account Information
Retrieve detailed information about user accounts, including profiles, statistics, and verification status.
def account(self, id: int) -> dict:
"""
Get account information by ID.
Args:
id: Account ID
Returns:
Dictionary containing account details (username, display_name, followers_count, etc.)
"""
def accounts(self, ids: list) -> list:
"""
Get multiple accounts by IDs (Mastodon 4.3.0+).
Args:
ids: List of account IDs
Returns:
List of account dictionaries
"""
def account_verify_credentials(self) -> dict:
"""
Get information about the authenticated user's own account.
Returns:
Dictionary containing own account details with additional private fields
"""
def me(self) -> dict:
"""
Alias for account_verify_credentials().
Returns:
Dictionary containing own account details
"""
def account_lookup(self, acct: str) -> dict:
"""
Look up account by webfinger address (username@domain).
Args:
acct: Account address in format username@domain.tld
Returns:
Dictionary containing account information
"""Account Content & Relationships
Access account-related content including statuses, followers, following lists, and relationship status.
def account_statuses(
self,
id: int,
only_media: bool = False,
pinned: bool = False,
exclude_replies: bool = False,
exclude_reblogs: bool = False,
tagged: str = None,
max_id: int = None,
min_id: int = None,
since_id: int = None,
limit: int = 20
) -> list:
"""
Get statuses posted by an account.
Args:
id: Account ID
only_media: Only return statuses with media attachments
pinned: Only return pinned statuses
exclude_replies: Skip reply statuses
exclude_reblogs: Skip reblogged statuses
tagged: Only return statuses tagged with this hashtag
max_id: Return results older than this ID
min_id: Return results newer than this ID
since_id: Return results newer than this ID
limit: Maximum number of results (default 20, max 40)
Returns:
List of status dictionaries
"""
def account_following(
self,
id: int,
max_id: int = None,
min_id: int = None,
since_id: int = None,
limit: int = 40
) -> list:
"""
Get accounts followed by the specified account.
Args:
id: Account ID
max_id: Return results older than this ID
min_id: Return results newer than this ID
since_id: Return results newer than this ID
limit: Maximum number of results (default 40, max 80)
Returns:
List of account dictionaries
"""
def account_followers(
self,
id: int,
max_id: int = None,
min_id: int = None,
since_id: int = None,
limit: int = 40
) -> list:
"""
Get accounts following the specified account.
Args:
id: Account ID
max_id: Return results older than this ID
min_id: Return results newer than this ID
since_id: Return results newer than this ID
limit: Maximum number of results (default 40, max 80)
Returns:
List of account dictionaries
"""
def account_relationships(self, id: list) -> list:
"""
Get relationship status with one or more accounts.
Args:
id: Account ID or list of account IDs
Returns:
List of relationship dictionaries containing following, followed_by, blocking, etc.
"""
def account_lists(self, id: int) -> list:
"""
Get lists containing the specified account.
Args:
id: Account ID
Returns:
List of list dictionaries
"""
def account_familiar_followers(self, id: list) -> list:
"""
Get familiar followers for accounts (mutual connections).
Args:
id: Account ID or list of account IDs
Returns:
List of familiar follower information
"""Account Actions
Follow, unfollow, block, mute, and perform other relationship actions with accounts.
def account_follow(
self,
id: int,
reblogs: bool = True,
notify: bool = False
) -> dict:
"""
Follow an account.
Args:
id: Account ID to follow
reblogs: Show reblogs from this account in timeline
notify: Get notifications when this account posts
Returns:
Relationship dictionary with updated status
"""
def account_unfollow(self, id: int) -> dict:
"""
Unfollow an account.
Args:
id: Account ID to unfollow
Returns:
Relationship dictionary with updated status
"""
def account_remove_from_followers(self, id: int) -> dict:
"""
Remove an account from your followers (soft block).
Args:
id: Account ID to remove
Returns:
Relationship dictionary with updated status
"""
def account_block(self, id: int) -> dict:
"""
Block an account.
Args:
id: Account ID to block
Returns:
Relationship dictionary with updated status
"""
def account_unblock(self, id: int) -> dict:
"""
Unblock an account.
Args:
id: Account ID to unblock
Returns:
Relationship dictionary with updated status
"""
def account_mute(
self,
id: int,
notifications: bool = True,
duration: int = None
) -> dict:
"""
Mute an account.
Args:
id: Account ID to mute
notifications: Also mute notifications from this account
duration: Duration in seconds (0 = indefinite)
Returns:
Relationship dictionary with updated status
"""
def account_unmute(self, id: int) -> dict:
"""
Unmute an account.
Args:
id: Account ID to unmute
Returns:
Relationship dictionary with updated status
"""Profile Management
Update and manage your own profile information including display name, bio, avatar, and custom fields.
def account_update_credentials(
self,
display_name: str = None,
note: str = None,
avatar: str = None,
avatar_mime_type: str = None,
header: str = None,
header_mime_type: str = None,
locked: bool = None,
bot: bool = None,
discoverable: bool = None,
fields_attributes: list = None,
source: dict = None,
indexable: bool = None
) -> dict:
"""
Update profile information for the authenticated account.
Args:
display_name: Display name for profile
note: Profile bio/description (HTML allowed)
avatar: Avatar image file path or file-like object
avatar_mime_type: MIME type of avatar image
header: Header image file path or file-like object
header_mime_type: MIME type of header image
locked: Require approval for new followers
bot: Mark account as automated/bot account
discoverable: Allow account to be discovered in directory
fields_attributes: List of profile field dictionaries with 'name' and 'value'
source: Source settings (privacy, sensitive, language)
indexable: Allow indexing by search engines
Returns:
Updated account dictionary
"""
def account_delete_avatar(self) -> dict:
"""
Delete the profile avatar image (Mastodon 4.2.0+).
Returns:
Updated account dictionary
"""
def account_delete_header(self) -> dict:
"""
Delete the profile header image (Mastodon 4.2.0+).
Returns:
Updated account dictionary
"""Account Endorsements & Notes
Endorse accounts and manage private notes on user profiles.
def account_pin(self, id: int) -> dict:
"""
Endorse (pin) an account to your profile.
Args:
id: Account ID to endorse
Returns:
Relationship dictionary with endorsement status
"""
def account_endorse(self, id: int) -> dict:
"""
Alias for account_pin().
Args:
id: Account ID to endorse
Returns:
Relationship dictionary with endorsement status
"""
def account_unpin(self, id: int) -> dict:
"""
Remove endorsement (unpin) from an account.
Args:
id: Account ID to remove endorsement from
Returns:
Relationship dictionary with updated status
"""
def account_unendorse(self, id: int) -> dict:
"""
Alias for account_unpin().
Args:
id: Account ID to remove endorsement from
Returns:
Relationship dictionary with updated status
"""
def account_note_set(self, id: int, comment: str) -> dict:
"""
Set a private note on an account (visible only to you).
Args:
id: Account ID
comment: Private note text
Returns:
Relationship dictionary with note information
"""Account Discovery
Search for accounts and get featured hashtags associated with user profiles.
def account_search(
self,
q: str,
limit: int = 40,
following: bool = False,
resolve: bool = False
) -> list:
"""
Search for accounts by username or display name.
Args:
q: Search query
limit: Maximum number of results (default 40, max 80)
following: Only search among accounts you follow
resolve: Attempt to resolve non-local accounts
Returns:
List of matching account dictionaries
"""
def account_featured_tags(self, id: int) -> list:
"""
Get featured hashtags for an account.
Args:
id: Account ID
Returns:
List of featured hashtag dictionaries
"""Account Creation
Create new accounts programmatically (requires appropriate permissions).
def create_account(
self,
username: str,
password: str,
email: str,
agreement: bool,
locale: str = "en",
reason: str = None,
fields: list = None,
invitation_code: str = None
) -> dict:
"""
Create a new user account.
Args:
username: Desired username
password: Account password
email: Email address
agreement: User agrees to terms of service
locale: User's preferred locale
reason: Reason for account creation (if required)
fields: Initial profile fields
invitation_code: Invitation code (if required)
Returns:
Dictionary containing account creation result and token
"""
def email_resend_confirmation(self) -> dict:
"""
Resend email confirmation for the authenticated account.
Returns:
Empty dictionary on success
"""Usage Examples
Basic Account Operations
from mastodon import Mastodon
mastodon = Mastodon(
access_token='your_token',
api_base_url='https://mastodon.social'
)
# Get your own account info
me = mastodon.account_verify_credentials()
print(f"Logged in as {me['acct']} with {me['followers_count']} followers")
# Look up and follow another account
account = mastodon.account_lookup("gargron@mastodon.social")
relationship = mastodon.account_follow(account['id'])
print(f"Now following {account['acct']}: {relationship['following']}")
# Get their recent posts
statuses = mastodon.account_statuses(account['id'], limit=5)
for status in statuses:
print(f"- {status['content'][:50]}...")Profile Management
# Update your profile
updated_account = mastodon.account_update_credentials(
display_name="My New Display Name",
note="This is my updated bio with #hashtags",
fields_attributes=[
{"name": "Website", "value": "https://example.com"},
{"name": "Pronouns", "value": "they/them"}
],
bot=False,
discoverable=True
)
# Upload a new avatar
with open('avatar.jpg', 'rb') as avatar_file:
mastodon.account_update_credentials(
avatar=avatar_file,
avatar_mime_type='image/jpeg'
)Relationship Management
# Get your followers and following
followers = mastodon.account_followers(me['id'])
following = mastodon.account_following(me['id'])
print(f"You have {len(followers)} followers and follow {len(following)} accounts")
# Check relationship status with multiple accounts
account_ids = [followers[0]['id'], following[0]['id']]
relationships = mastodon.account_relationships(account_ids)
for rel in relationships:
print(f"Account {rel['id']}: following={rel['following']}, followed_by={rel['followed_by']}")
# Mute an account temporarily (24 hours)
mastodon.account_mute(account_ids[0], duration=86400)Account Discovery
# Search for accounts
search_results = mastodon.account_search("python", limit=10)
for account in search_results:
print(f"{account['acct']}: {account['display_name']}")
# Get familiar followers (mutual connections)
familiar = mastodon.account_familiar_followers([account['id'] for account in search_results[:3]])
for item in familiar:
print(f"Mutual followers with {item['id']}: {len(item['accounts'])}")Types
# Account object structure
Account = {
'id': str, # Account ID
'username': str, # Username without domain
'acct': str, # Full account name (username@domain)
'display_name': str, # Display name
'locked': bool, # Requires follow approval
'bot': bool, # Is bot account
'discoverable': bool, # Appears in directory
'group': bool, # Is group account
'created_at': str, # Account creation date
'note': str, # Profile bio (HTML)
'url': str, # Profile URL
'avatar': str, # Avatar image URL
'avatar_static': str, # Static avatar URL
'header': str, # Header image URL
'header_static': str, # Static header URL
'followers_count': int, # Number of followers
'following_count': int, # Number of following
'statuses_count': int, # Number of statuses
'last_status_at': str, # Date of last status
'fields': list, # Profile fields
'emojis': list, # Custom emojis used
}
# Relationship object structure
Relationship = {
'id': str, # Account ID
'following': bool, # You follow this account
'followed_by': bool, # This account follows you
'blocking': bool, # You block this account
'blocked_by': bool, # This account blocks you
'muting': bool, # You mute this account
'muting_notifications': bool, # You mute notifications
'requested': bool, # Follow request pending
'domain_blocking': bool, # You block their domain
'showing_reblogs': bool, # You see their reblogs
'endorsed': bool, # You endorse this account
'notifying': bool, # You get notifications
'note': str, # Your private note
}Install with Tessl CLI
npx tessl i tessl/pypi-mastodon-py@2.1.1