Skip to main content

A nano implementation of the AT Protocol for Python.

Project description

nanoatp

PyPI GitHub License GitHub last commit   EN | JA | ES | ZH

A nano implementation of the AT Protocol for Python.

Demo

  • A bot built with nanoatp that summarizes the top 30 most popular arXiv papers on Reddit and Hacker News in the last 30 days and posts them to Bluesky.

Getting started

  • First, install the package.
pip install nanoatp
  • Set your credentials as environment variables. Or you can pass them to BskyAgent.login().
export ATP_IDENTIFIER="foo.bsky.social"
export ATP_PASSWORD="password"
  • Then in your application,
from nanoatp import BskyAgent, RichText

agent = BskyAgent("https://bsky.social")
agent.login()

# post a simple text
record = {"text": "Hello World!"}
response = agent.post(record)
print(response)

# create a RichText
rt = RichText("Hello @nanoatp.bsky.social, check out this link: https://huggingface.co/")
rt.detectFacets(agent)
print(rt.facets)

# upload an image
image = agent.uploadImage("example.png")

# post a RichText with an image
embed = {"$type": "app.bsky.embed.images#main", "images": [image]}
record = {"text": rt.text, "facets": rt.facets, "embed": embed}
response = agent.post(record)
print(response)

# upload an external link (create a link card with title, description and thumbnail)
uri = rt.facets[1]["features"][0]["uri"]  # https://huggingface.co/
external = agent.uploadExternal(uri)

# post a RichText with an external link
embed = {"$type": "app.bsky.embed.external#main", "external": external}
record = {"text": rt.text, "facets": rt.facets, "embed": embed}
response = agent.post(record)
print(response)

See examples for more.

Usage

Session management

Log into a server using these APIs. You'll need an active session for most methods.

from nanoatp import BskyAgent

agent = BskyAgent("https://bsky.social")

# if you don't specify credentials,
# ATP_IDENTIFIER and ATP_PASSWORD environment variables will be used
agent.login("alice@mail.com", "hunter2")

API calls

The agent includes methods for many common operations, including:

# Feeds and content
agent.getPost(repo, rkey, cid)
agent.post(record)
agent.deletePost(postUri)
agent.uploadBlob(data, encoding)
agent.uploadImage(path, alt, encoding)  # wrapper for uploadBlob
agent.uploadExternal(url)  # wrapper for uploadBlob

# Identity
agent.resolveHandle(handle)

# Session management
agent.login(identifier, password)

Rich text

Some records (ie posts) use the app.bsky.richtext lexicon. At the moment richtext is only used for links and mentions, but it will be extended over time to include bold, italic, and so on.

ℹ️ Currently the implementation is very naive. I have not tested it with UTF-16 text.

from nanoatp import BskyAgent, RichText

agent = BskyAgent()
agent.login()

rt = RichText("Hello @nanoatp.bsky.social, check out this link: https://example.com")
rt.detectFacets(agent)
record = {"text": rt.text, "facets": rt.facets}
agent.post(record)

Advanced

Advanced API calls

The methods above are convenience wrappers. It covers most but not all available methods.

The AT Protocol identifies methods and records with reverse-DNS names. You can use them on the agent as well:

res1 = agent._repo_createRecord(
    agent.session["did"],  # repo
    "app.bsky.feed.post",  # collection
    {
        "$type": "app.bsky.feed.post",
        "text": "Hello, world!",
        "createdAt": datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z")
    }
)

Development

export ATP_IDENTIFIER="foo.bsky.social"
export ATP_PASSWORD="password"
poetry install
poetry run pytest -s     # run pytest once
poetry run -- ptw -- -s  # watch for changes and run pytest

TODO:

  • split BskyAgent and AtpAgent code
  • implement a proper RichText parser with UTF-16 (currently it's very naive)
  • type definitions
  • structured tests
  • more APIs

License

MIT License. See LICENSE for details.

Author

S. Ota

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nanoatp-0.4.1.tar.gz (7.0 kB view details)

Uploaded Source

Built Distribution

nanoatp-0.4.1-py3-none-any.whl (8.2 kB view details)

Uploaded Python 3

File details

Details for the file nanoatp-0.4.1.tar.gz.

File metadata

  • Download URL: nanoatp-0.4.1.tar.gz
  • Upload date:
  • Size: 7.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.5.1 CPython/3.10.12 Darwin/22.6.0

File hashes

Hashes for nanoatp-0.4.1.tar.gz
Algorithm Hash digest
SHA256 dc4543733a036e721fdde705ec5464a7d30e632dd9538b0f4b2625043c1982a6
MD5 dbda4ee456acce4f7b257b5b5ebfcefc
BLAKE2b-256 43e2c67f4368fc53163d3cbe779ea575d3a1365b025d112876f3ed6fc3a456df

See more details on using hashes here.

File details

Details for the file nanoatp-0.4.1-py3-none-any.whl.

File metadata

  • Download URL: nanoatp-0.4.1-py3-none-any.whl
  • Upload date:
  • Size: 8.2 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.5.1 CPython/3.10.12 Darwin/22.6.0

File hashes

Hashes for nanoatp-0.4.1-py3-none-any.whl
Algorithm Hash digest
SHA256 d772a133137a5ed7a19d3da1e03636f2b3681e7aed64bb62b079c5e0615eb74c
MD5 627a9a8d35dbee764482e1834f3d7710
BLAKE2b-256 a41a8265c09c53a6c63870fa97e78b1cac18d83d7b135a8bd876b386064f42d2

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page