I blog so others can suffer too.Keep me posting
Spent the day goofing off with Mastodon.py
Let’s set up a Mastodon application with Python to read and post toots.
Python is the second best tool for any job in 2021, which makes it an excellent glue language. I’ve been centering my site workflow around it. That means the Mastodon.py library, which I have dabbled with once or twice before.
Because I’ve let the IndieWeb social aspects of this site go stale and one step to fixing that is restoring POSSE automation. The first part of that is making sure I remember how to automate posting to Mastodon.
Course, you’re going to need an account at a Mastodon instance. I have my account on one of many. You can find one suitable for your tastes at Mastodon instances.
If you don’t already know Mastodon, think of it as island versions of Twitter. Each instance has its own practices and policies depending on who runs it, so it’s very much a “hanging out at a friend’s house” experience. Lots more details, but much more than I feel like covering.
It’s fun. You should try it out maybe. You can even host your own instance if you’re hard-core into DIY.
I have 2FA enabled, so it turned out to be easier for me to set up the application in account preferences (under the “Development” section).
I entered an application name, added my Website for “Application website,” and selected the scopes that are important to me for today’s explorations.
readwrite:statusesThat’s enough to cover today’s play. I’m not creating my own full-fledged Mastodon client so I don’t need every permission.
import json
import os
import sys
from dataclasses import dataclass
from typing import Any, Callable, Dict
from mastodon import Mastodon
from rich.pretty import pprint
Spoiler alert: yes I’ll be using Rich and dataclasses along with Mastodon.py. Nothing fancy planned with Rich today. It’s just part of my regular toolkit.
The dataclasses library comes standard with Python these days, but you may need to install the others:
pip install --upgrade rich mastodon
The Mastodon instance developer panel gives me the details I need to connect. I set them as workspace environment variables with direnv out of habit, but you could just as easily hard-code them in Python or define in a config file of your own.
API_BASE = os.environ.get("API_BASE")
CLIENT_KEY = os.environ.get("CLIENT_KEY")
CLIENT_SECRET = os.environ.get("CLIENT_SECRET")
ACCESS_TOKEN = os.environ.get("ACCESS_TOKEN")
From my first few attempts writing this post, I know I’ll want a class to organize views for the connection.
@dataclass
class App:
"""Provides convenience methods for querying an instance and posting toots."""
mastodon: Mastodon
Once I have a connection, I don’t care about those application config details. Rather than storing them in the instance, I’ll use a class method to handle the work and return my new App with only the details I do care about.
class App:
@classmethod
def connect(
cls,
client_key: str = CLIENT_KEY,
api_base_url: str = API_BASE,
client_secret: str = CLIENT_SECRET,
access_token: str = ACCESS_TOKEN,
) -> "App":
"""Return an App connected to a specific Mastodon instance."""
mastodon = Mastodon(
client_id=client_key,
api_base_url=api_base_url,
client_secret=client_secret,
access_token=access_token,
)
return cls(mastodon=mastodon)
Basic setup’s done. Let’s create an App and see if it worked.
if __name__ == "__main__":
app = App.connect()
pprint(app)
App(mastodon=<mastodon.Mastodon.Mastodon object at 0x7ff14f1e8850>)
My code doesn’t look exactly like what I’ve shared here. I take advantage of Rich’s export features to simplify sharing program output.
import rich
# ...
if __name__ == "__main__":
rich.reconfigure(record=True, width=80)
# ...
rich.get_console().save_html("output.html", inline_styles=True)
The extra bits change two aspects of Rich’s default Console behavior:
save_text or save_html and I can add it here in my postAfter app does its thing, I export any output as formatted HTML, where I can edit as needed and insert here.
So anyways, we verified that our connection works. Let’s take a look at what that connection provides.
Mastodon.py provides methods specifically for reading instance details. For example, instance_health tells of if a quick health check succeeded.
app = App.connect()
if app.mastodon.instance_health():
rich.print("Connection instance is [green]healthy[/green]")
else:
rich.print("Connection instance is [red][b]not[/b] healthy![/red]")
sys.exit(1)
Connection instance is healthy
Most of the querying methods return a dictionary or a list of dictionaries. Mastodon.instance returns an instance dict.
I don’t feel like showing every item in that dictionary, though. Let’s pick a few to make a decent summary. Oh hey, and let’s cache that dictionary to disk so I’m not making a fresh API query every time I check this post while I’m writing it.
Be considerate about server resources for Mastodon. Most instances are run as personal projects. There’s no need for us to run up their AWS bill.
def stored(func: Callable) -> Dict[str, Any]:
def inner(*args, **kwargs):
filename = f"{func.__name__}.json"
rich.print(f"stored.inner for {func.__name__}")
if os.path.exists(filename):
with open(filename, "r") as f:
rich.print(f"Loading data from {filename}")
data = json.load(f)
return data
rich.print(f"Calling {func.__name__}")
data = func(*args, **kwargs)
with open(filename, "w") as f:
rich.print(f"Writing data to {filename}")
json.dump(data, f, indent=4, default=str)
return data
return inner
I can do proper memoization later. “Look for a file before you hit the server” is good enough for writing a blog post.
class App:
@stored
def instance(self) -> Dict[str, Any]:
"""Return a dictionary of information about the connected instance."""
return self.mastodon.instance()
def instance_summary(self) -> Dict[str, Any]:
"""Return a small dictionary of instance information."""
instance = self.instance()
fields = ["uri", "title", "short_description"]
data = {field: instance[field] for field in fields}
data["contact_account"] = instance["contact_account"]["display_name"]
return data
Time to look at that instance summary.
if __name__ == "__main__":
app = App.connect()
if app.mastodon.instance_health():
rich.print("Connection instance is [green]healthy[/green]")
else:
rich.print("Connection instance is [red][b]not[/b] healthy![/red]")
sys.exit(1)
pprint(app.instance_summary())
Connection instance is healthy stored.inner for instance Calling instance Writing data to instance.json { │ 'uri': 'hackers.town', │ 'title': 'hackers.town', │ 'short_description': "A bunch of technomancers in the fediverse. Keep it fairly clean please. This arcology is for all who wash up upon it's digital shore.", │ 'contact_account': 'The_Gibson' }
Mastodon’s timeline methods provide different views of recent post activity, both public and private. To simplify demonstration on this public blog post, I’ll stick to timeline_public.
class App:
@stored
def timeline_public(self) -> List[Dict[str, Any]]:
return self.mastodon.timeline_public()
The toot dict also contains far more information than I need, so let’s summarize those like with instances.
class App:
def timeline_summary(self) -> Dict[str, Any]:
timeline = self.timeline_public()
return [
{
"date": toot["created_at"],
"author": toot["account"]["display_name"],
"content": toot["content"],
}
for toot in timeline
]
Adding app.timeline_summary() to the main block:
if __name__ == "__main__":
app = App.connect()
if app.mastodon.instance_health():
rich.print("Connection instance is [green]healthy[/green]")
else:
rich.print("Connection instance is [red][b]not[/b] healthy![/red]")
sys.exit(1)
pprint(app.instance_summary())
pprint(app.timeline_summary(), max_string=80)
Connection instance is healthy stored.inner for instance Loading data from instance.json { │ 'uri': 'hackers.town', │ 'title': 'hackers.town', │ 'short_description': "A bunch of technomancers in the fediverse. Keep it fairly clean please. This arcology is for all who wash up upon it's digital shore.", │ 'contact_account': 'The_Gibson' } stored.inner for timeline_public Calling timeline_public Writing data to timeline_public.json [ .. skipping a few ... │ { │ │ 'date': '2021-08-15 22:24:35+00:00', │ │ 'author': 'Endless Screaming', │ │ 'content': '<p>AAAAAAAAAAAAAAAAAAAAH</p>' │ }, │ { │ │ 'date': '2021-08-15 22:24:43.531000+00:00', │ │ 'author': 'Lynne', │ │ 'content': '<p>This just touched a single topic that I’ve never heard being brought up anywh'+97 │ } ]
Nice. Looks like content is in HTML format. Need to remember that if I ever make a more interesting Mastodon client.
But I’m ready to start tooting.
[write-methods]:
Mastodon write methods let us add toots, polls, replies, reblogs, faves. All that good stuff.
Let’s stick with your basic toot for now.
class App:
def status_post(self, status: str, visibility: str = "direct") -> Dict[str, Any]:
"""Post a toot to our connection, private unless we say otherwise."""
return self.mastodon.status_post(status, visibility=visibility)
if __name__ == "__main__":
app = App.connect()
if app.mastodon.instance_health():
rich.print("Connection instance is [green]healthy[/green]")
else:
rich.print("Connection instance is [red][b]not[/b] healthy![/red]")
sys.exit(1)
status_text = "Ignore me, just messing with Mastodon.py"
app.status_post(status_text)
Okay my brain is fading. Should probably put away the keyboard soon.
Am I done?
Well, no. I still need to turn this into a proper command line application that looks for the newest published blog post and posts a toot about it. But that’s not going to happen in today’s post.
I had fun, and that’s the important part.