granary package

Reference documentation.

as1

Utilities for ActivityStreams 1 objects.

• https://activitystrea.ms/specs/json/schema/activity-schema.html

• http://activitystrea.ms/specs/json/1.0/

object_type(obj)[source]

Returns the object type, or the verb if it’s an activity object.

Details: http://activitystrea.ms/specs/json/1.0/#activity-object

Parameters:

obj (dict) – decoded JSON ActivityStreams object

Returns:

ActivityStreams object type

Return type:

str

get_object(obj, field='object')[source]

Extracts and returns a field value as an object.

If the field value is a string, returns an object with it as the id, eg {'id': val}. If the field value is a list, returns the first element.

Parameters:

• obj (dict) – decoded JSON ActivityStreams object

• field (str)

Return type:

dict

get_objects(obj, field='object')[source]

Extracts and returns a field’s values as objects.

If a field value is a string, generates an object with it as the id, eg {'id': val}.

Parameters:

• obj (dict) – decoded JSON ActivityStreams object

• field (str)

Return type:

sequence of dict

get_owner(obj)[source]

Returns an object’s author or actor.

Prefers author, then actor. If that’s an object, returns its id, if available. If neither field exists, but obj.objectType is in ACTOR_TYPES, returns its own id, if available.

For posts, updates, and deletes, falls back to the inner object’s owner if the outer activity has no actor.

Parameters:

obj (dict) – decoded JSON ActivityStreams object

Return type:

str

get_url(obj)[source]

Returns the url field’s first text value, or ''.

Somewhat duplicates microformats2.get_text().

get_ids(obj, field)[source]

Extracts and returns a given field’s values as ids.

Parameters:

• obj (dict) – decoded JSON ActivityStreams object

• field (str)

Returns string values as is. For dict values, returns their inner id or url field value, in that order of precedence.

get_id(obj, field)[source]

Extracts and returns a given field’s id value.

Parameters:

• obj (dict) – decoded JSON ActivityStreams object

• field (str)

Returns a string value as is. For dict values, returns its inner id.

merge_by_id(obj, field, new)[source]

Merges new items by id into a field in an existing AS1 object, in place.

Merges new items by id into the given field. If it exists, it must be a list. Requires all existing and new items in the field to have ids.

Parameters:

• obj (dict) – AS1 object

• field (str) – name of field to merge new items into

• new (sequence of dict) – new values to merge in

is_public(obj, unlisted=True)[source]

Returns True if the object is public, False if private, None if unknown.

…according to the Audience Targeting extension: http://activitystrea.ms/specs/json/targeting/1.0/

Expects values generated by this library: objectType group, alias @public, @unlisted, or @private.

Also, important point: this defaults to True, ie public. Bridgy depends on that and prunes the to field from stored activities in Response objects (in bridgy/util.prune_activity). If the default here ever changes, be sure to update Bridgy’s code.

Parameters:

• obj (dict) – AS1 activity or object

• unlisted (bool) – whether @unlisted counts as public or not

Return type:

bool

recipient_if_dm(obj, actor=None)[source]

If obj is a DM, returns the recipient actor’s id.

DMs are note``s addressed to a single recipient, ie ``to has one value and cc, bcc, and bto have none.

If obj isn’t a DM, returns None.

Those fields are based on the Audience Targeting extension: http://activitystrea.ms/specs/json/targeting/1.0/

Parameters:

• obj (dict) – AS1 activity or object

• actor (dict) – optional AS1 actor who sent this object. Its followers collection is used to identify followers-only posts.

Return type:

bool

is_dm(obj, actor=None)[source]

Returns True if the object is a DM, ie addressed to a single recipient.

See recipient_if_dm() for details.

is_audience(val)[source]

Returns True if val is a “special” AS1 or AS2 audience, eg “public.”

See the AS1 Audience Targeting extension and AS2 spec: * http://activitystrea.ms/specs/json/targeting/1.0/ * https://www.w3.org/TR/activitystreams-vocabulary/#dfn-audience

add_rsvps_to_event(event, rsvps)[source]

Adds RSVP objects to an event’s attending fields, in place.

Parameters:

• event (dict) – ActivityStreams event object

• rsvps (sequence of dict) – ActivityStreams RSVP activity objects

get_rsvps_from_event(event)[source]

Returns RSVP objects for an event’s attending fields.

Parameters:

event (dict) – ActivityStreams event object

Returns:

ActivityStreams RSVP activity objects

Return type:

sequence of dict

activity_changed(before, after, inReplyTo=True, log=False)[source]

Returns whether two activities or objects differ meaningfully.

Only compares a few fields: objectType, verb, displayName`, ``content, summary, location, and image. Notably does not compare author, published, or updated.

Parameters:

• before (dict) – ActivityStreams activity or object

• after (dict) – ActivityStreams activity or object

• inReplyTo (bool) – whether to return True if inReplyTo has changed

• log (bool) – whether to log each changed field

Return type:

bool

append_in_reply_to(before, after)[source]

Appends before’s inReplyTo to after, in place.

Parameters:

• before (dict) – ActivityStreams activity or object

• after (dict) – ActivityStreams activity or object

actor_name(actor)[source]

Returns the given actor’s name if available, otherwise Unknown.

original_post_discovery(activity, domains=None, include_redirect_sources=True, include_reserved_hosts=True, max_redirect_fetches=None, **kwargs)[source]

Discovers original post links.

This is a variation on http://indiewebcamp.com/original-post-discovery . It differs in that it finds multiple candidate links instead of one, and it doesn’t bother looking for MF2 (etc) markup because the silos don’t let you input it. More background: https://github.com/snarfed/bridgy/issues/51#issuecomment-136018857

Original post candidates come from the upstreamDuplicates, attachments, and tags fields, as well as links and permashortlinks/permashortcitations in the text content.

Parameters:

• activity (dict) – activity

• domains (sequence of str) – these domains will be considered original and stored in upstreamDuplicates. (Permashortcitations are exempt.)

• include_redirect_sources (bool) – whether to include URLs that redirect as well as their final destination URLs

• include_reserved_hosts (bool) – whether to include domains on reserved TLDs (eg foo.example) and local hosts (eg http://foo.local/, http://my-server/)

• max_redirect_fetches (int) – if specified, only make up to this many HTTP fetches to resolve redirects.

• kwargs – passed to requests.head() when following redirects

Returns:

(original post URLs, mentions)

Return type:

(list of str, list of str) tuple

prefix_urls(activity, field, prefix)[source]

Adds a prefix to all matching URL fields, eg to inject a caching proxy.

Generally used with the image or stream fields. For example:

>>> prefix_urls({'actor': {'image': 'http://image'}}, 'image', 'https://proxy/')
{'actor': {'image': 'https://proxy/http://image'}}

Skips any URL fields that already start with the prefix. URLs are not URL-encoded before adding the prefix. (This is currently used with our caching-proxy Cloudflare worker and https://cloudimage.io/ , neither of which URL-decodes.)

Parameters:

• activity (dict) – AS1 activity; modified in place

• prefix (str)

object_urls(obj)[source]

Returns an object’s unique URLs, preserving order.

targets(obj)[source]

Collects an AS1 activity or object’s targets.

This is all ids/URLs that are direct “targets” of the activity, eg:

• the post it’s replying to

• the post it’s sharing

• the post it’s reacting to

• the post it’s quoting

• the actor or other object it’s tagging

• the event it’s inviting someone to

• the event it’s RSVPing to

• the link or object it’s bookmarking

etc…

Parameters:

obj (dict) – AS1 object or activity

Returns:

targets

Return type:

list of str

quoted_posts(obj)[source]

Returns the ids that an object or activity is quoting.

In AS1, we define quoted posts as attachments with objectType: note.

Arg:

obj (dict): AS1 object or activity

Returns:

sequence of string ids, possibly empty

mentions(obj)[source]

Returns an object or activity’s mention tags.

Their url fields are extracted and returned, not ``id`, but in the common case the values are interpreted as ids.

Arg:

obj (dict): AS1 object or activity

Returns:

sequence of string URLs, possibly empty

as2

Convert between ActivityStreams 1 and 2, including ActivityPub.

• AS2:

  • http://www.w3.org/TR/activitystreams-core/

  • https://www.w3.org/TR/activitypub/

  • https://activitypub.rocks/

• AS1:

  • http://activitystrea.ms/specs/json/1.0/

  • http://activitystrea.ms/specs/json/schema/activity-schema.html

get_urls(obj, key='url')[source]

Returns link['href'] or link, for each link in obj[key].

set_content(obj, new_content)[source]

Sets content and also all matching values in contentMap.

…to try to keep them in sync.

Parameters:

• obj (dict) – AS2 object

• new_content (str)

from_as1(obj, type=None, context=('https://www.w3.org/ns/activitystreams', 'https://purl.archive.org/miscellany'), top_level=True)[source]

Converts an ActivityStreams 1 activity or object to ActivityStreams 2.

Parameters:

• obj (dict) – AS1 activity or object

• type (str) – default type if type inference can’t determine a type.

• context (str) – included as @context

Returns:

AS2 activity or object

Return type:

dict

to_as1(obj, use_type=True, get_fn=None)[source]

Converts an ActivityStreams 2 activity or object to ActivityStreams 1.

May make external HTTP requests if get_fn is provided, eg to fetch the featured collection. https://docs.joinmastodon.org/spec/activitypub/#featured

Parameters:

• obj (dict) – AS2 activity or object

• use_type (bool) – whether to include objectType and verb

• get_fn (callable, str URL => requests.Response) – requests to fetch AS2 objects when necessary, eg the featured collection. HTTP requests should usually be signed to satisfy many fediverse servers’ authorized fetch requirement.

Returns:

AS1 activity or object

Return type:

dict

is_public(activity, unlisted=True)[source]

Returns True if the given AS2 object or activity is public or unlisted.

https://docs.joinmastodon.org/spec/activitypub/#properties-used

Parameters:

• activity (dict) – AS2 activity or object

• unlisted (bool) – whether unlisted, ie public in cc instead of to counts as public or not

address(actor)[source]

Returns an actor’s fediverse handle aka WebFinger address aka @-@.

There’s no standard for this, it’s just a heuristic that uses preferredUsername and id or url if available, otherwise detects and transforms common user profile URLs.

Parameters:

actor (dict) – AS2 JSON actor or str actor id

Returns:

handle, eg @user@example.com, or None

Return type:

str

link_tags(obj)[source]

Adds HTML links to content for tags with startIndex and length.

content is modified in place. If content_is_html is true, does nothing. Otherwise, sets it to true if at least one link is added. Tags without startIndex/length are ignored.

TODO: duplicated in microformats2.render_content(). unify?

Parameters:

obj (dict) – AS2 JSON object

is_server_actor(actor)[source]

Returns True if this is the instance’s server actor, False otherwise.

Server actors are non-user actors used for fetching remote objects, sending Flag activities, etc. Background: * https://seb.jambor.dev/posts/understanding-activitypub-part-4-threads/#the-instance-actor * https://codeberg.org/fediverse/fep/src/branch/main/fep/d556/fep-d556.md

Right now, this just uses a well-known set of paths as a heuristic.

TODO: actually do a WebFinger lookup of the root path, eg webfinger?resource=https://example.com/, and use FEP-d556 to determine the server actor.

Parameters:

actor (dict) – AS2 actor

Return type:

bool

atom

Convert between ActivityStreams 1 and Atom.

Atom spec: https://tools.ietf.org/html/rfc4287 (RIP atomenabled.org)

class Defaulter(init={})[source]

Bases: defaultdict

Emulates Django template behavior that returns a special default value that can continue to be referenced when an attribute or item lookup fails. Helps avoid conditionals in the template itself.

https://docs.djangoproject.com/en/1.8/ref/templates/language/#variables

from_as1(input, actor=None, title=None, request_url=None, host_url=None, xml_base=None, rels=None, reader=True)[source]

Converts an ActivityStreams 1 activity or activities to an Atom feed.

Parameters:

• input (dict or list of dict) – ActivityStreams activity or activities

• actor (dict) – ActivityStreams actor, the author of the feed.

• title (str) – the feed <title> element. Defaults to User feed for [NAME]

• request_url (str) – URL of this Atom feed, if any. Used in a link rel=”self”.

• host_url (str) – home URL for this Atom feed, if any. Used in the top-level feed <id> element.

• xml_base (str) – base URL, if any. Used in the top-level xml:base attribute.

• rels (dict) – rel links to include. Keys are string rel, values are string URLs.

• reader (bool) – whether the output will be rendered in a feed reader. Currently just includes location if True, not otherwise.

Returns:

Atom XML

Return type:

str

activities_to_atom(input, actor=None, title=None, request_url=None, host_url=None, xml_base=None, rels=None, reader=True)

Deprecated! Use from_as1() instead.

activity_to_atom(input, actor=None, title=None, request_url=None, host_url=None, xml_base=None, rels=None, reader=True)

Deprecated! Use from_as1() instead.

to_as1(atom)[source]

Converts an Atom feed or entry to ActivityStreams 1 activities.

Parameters:

atom (str) – Atom document with top-level <feed> or <entry> element

Returns:

ActivityStreams activities

Return type:

list of dict

atom_to_activities(atom)

Deprecated! Use to_as1() instead.

atom_to_activity(atom)[source]

Converts an Atom entry to an ActivityStreams 1 activity.

Deprecated! Use to_as1() instead.

Parameters:

atom (str) – Atom document with top-level <entry> element

Returns:

ActivityStreams activity

Return type:

dict

from_html(html, url=None, fetch_author=False, reader=True)[source]

Converts microformats2 HTML to an Atom feed.

Parameters:

• html (str)

• url (str) – URL html came from, optional

• fetch_author (bool) – whether to make HTTP request to fetch rel-author link

• reader (bool) – whether the output will be rendered in a feed reader. Currently just includes location if True, not otherwise.

Returns:

Atom XML

Return type:

str

html_to_atom(html, url=None, fetch_author=False, reader=True)

Deprecated! Use from_html() instead.

extract_entries(atom)[source]

Extracts <entry> elements into their own separate XML documents.

Parameters:

atom (str) – Atom document with top-level <feed> or <entry> element

Returns:

Atom documents with top-level <entry> element for each entry

Return type:

list of str

bluesky

Bluesky source class.

• https://bsky.app/

• https://atproto.com/lexicons/app-bsky-actor

• https://github.com/bluesky-social/atproto/tree/main/lexicons/app/bsky

url_to_did_web(url)[source]

Converts a URL to a did:web.

In AT Proto, only hostname-based web DIDs are supported. Paths are not supported, and will be discarded.

https://atproto.com/specs/did

Examples:

• https://foo.com => did:web:foo.com

• https://foo.com:3000 => did:web:foo.com

• https://foo.bar.com/baz/baj => did:web:foo.bar.com

Parameters:

url (str)

Return type:

str

did_web_to_url(did)[source]

Converts a did:web to a URL.

In AT Proto, only hostname-based web DIDs are supported. Paths are not supported, and will throw an invalid error.

Examples:

• did:web:foo.com => https://foo.com

• did:web:foo.com%3A3000 => INVALID

• did:web:bar.com:baz:baj => INVALID

https://atproto.com/specs/did

Parameters:

did (str)

Return type:

str

at_uri_to_web_url(uri, handle=None)[source]

Converts an at:// URI to a https://bsky.app URL.

https://atproto.com/specs/at-uri-scheme

Parameters:

• uri (str) – at:// URI

• handle – (str): optional user handle. If not provided, defaults to the DID in uri.

Returns:

https://bsky.app URL, or None

Return type:

str

Raises:

ValueError – if uri is not a string or doesn’t start with at://

web_url_to_at_uri(url, handle=None, did=None)[source]

Converts a https://bsky.app URL to an at:// URI.

https://atproto.com/specs/at-uri-scheme

Currently supports profile, post, and feed URLs with DIDs and handles, eg:

• https://bsky.app/profile/did:plc:123abc

• https://bsky.app/profile/vito.fyi/post/3jt7sst7vok2u

• https://bsky.app/profile/bsky.app/feed/mutuals

If both handle and did are provided, and handle matches the URL, the handle in the resulting URI will be replaced with did.

Parameters:

• url (str) – bsky.app URL

• handle (str) – Bluesky handle, or None

• did (str) – Valid DID, or None

Returns:

at:// URI, or None

Return type:

str

Raises:

ValueError – if url can’t be parsed as a bsky.app profile or post URL

from_as1_to_strong_ref(obj, client=None, value=False, raise_=False)[source]

Converts an AS1 object to an ATProto com.atproto.repo.strongRef.

Uses AS1 id or url`, which should be an ``at:// URI.

Parameters:

• obj (dict) – AS1 object or activity

• client (lexrpc.Client) – optional; if provided, this will be used to make API calls to PDSes to fetch and populate the cid field and resolve handle to DID.

• value (bool) – whether to include the record’s value field in the returned object

• raise (bool) – whether to raise ValueError if client is provided and we can’t fetch the object’s record and populate cid

Returns:

ATProto com.atproto.repo.strongRef record

Return type:

dict

from_as1_datetime(val)[source]

Converts an AS1 RFC 3339 datetime string to ATProto ISO 8601.

Bluesky requires full date and time with time zone, recommends UTC with Z suffix, fractional seconds.

https://atproto.com/specs/lexicon#datetime

Returns now (ie the current time) if the input datetime can’t be parsed.

Parameters:

val (str) – RFC 3339 datetime

Returns:

ATProto compatible ISO 8601 datetime

Return type:

str

base_object(obj)[source]

Returns the “base” Bluesky object that an object operates on.

If the object is a reply, repost, or like of a Bluesky post, this returns that post object. The id in the returned object is the AT protocol URI, while the URL is the bsky.app web URL.

If the object is a follow or block, this returns the followed or blocked id, eg a DID.

Parameters:

obj (dict) – ActivityStreams object

Returns:

minimal ActivityStreams object. Usually has at least id; may also have url, author, etc.

Return type:

dict

from_as1(obj, out_type=None, blobs=None, aspects=None, client=None, original_fields_prefix=None, as_embed=False, raise_=False)[source]

Converts an AS1 object to a Bluesky object.

Converts to record types by default, eg app.bsky.actor.profile or app.bsky.feed.post. Use out_type to convert to a different type, eg app.bsky.actor.defs#profileViewBasic or app.bsky.feed.defs#feedViewPost.

The objectType field is required.

If a string value in an output Bluesky object is longer than its maxGraphemes or maxLength in its lexicon, it’s truncated with an … ellipsis character at the end in order to fit.

Parameters:

• obj (dict) – AS1 object or activity

• out_type (str) – desired output lexicon $type

• blobs (dict) – optional mapping from str URL to $type: blob dict (with ref, mimeType, and size) to use in the returned object. If not provided, or if this doesn’t have an image or similar URL in the input object, its output blob will be omitted.

• aspects (dict) – optional mapping from str URL to int (width,height) tuple. Used to provide aspect ratio in image/video embeds.

• client (Bluesky or lexrpc.Client) – optional; if provided, this will be used to make API calls to PDSes to fetch and populate CIDs for records referenced by replies, likes, reposts, etc.

• original_fields_prefix (str) – optional; if provided, stores original object URLs, post text, and actor profiles (ie before truncation) in custom fields with this prefix in output records. For example, if this is foo, an actor’s complete summary field will be stored in the custom fooOriginalDescription field, and their (first) url will be stored in the custom fooOriginalUrl field.

• as_embed (bool) – whether to render the post as an external embed (ie link preview) instead of a native post. This happens automatically if objectType is article

• raise (bool) – whether to raise ValueError if client is provided and we can’t fetch an object’s record

Returns:

app.bsky.* object

Return type:

dict

Raises:

ValueError – if the object can’t be converted, eg if the objectType or verb fields are missing or unsupported

to_external_embed(obj, description=None, blobs=None)[source]

Converts an AS1 object to a Bluesky app.bsky.embed.external#external.

Parameters:

• obj (dict) – AS1 object

• description (str) – if provided, overrides summary and content in obj

Returns:

Bluesky app.bsky.embed.external#external record

Return type:

dict

to_as1(obj, type=None, uri=None, repo_did=None, repo_handle=None, pds='https://bsky.social/', client=None)[source]

Converts a Bluesky object to an AS1 object.

Parameters:

• obj (dict) – app.bsky.* object

• type (str) – optional $type to parse with, only used if obj['$type'] is unset

• uri (str) – optional at:// URI of this object. Used to populate the id and url fields for some object types, eg posts.

• repo_did (str) – optional DID of the repo this object is from. Required to generate image URLs.

• repo_handle (str) – optional handle of the user whose repo this object is from

• pds (str) – base URL of the PDS that currently serves this object’s repo. Required to generate image URLs. Defaults to https://bsky.social/.

• client (Bluesky or lexrpc.Client) – optional; if provided, this will be used to make API calls to PDSes to fetch secondary records needed for conversion, eg community.lexicon.payments.webMonetization for profiles

Returns:

AS1 object, or None if the record doesn’t correspond to an AS1 object,

eg “not found” records

Return type:

dict

Raises:

ValueError – if the $type field is missing or unsupported

blob_to_url(*, blob, repo_did, pds='https://bsky.social/')[source]

Generates a URL for a blob.

Supports both new and old style blobs: https://atproto.com/specs/data-model#blob-type

Supports ref values as raw bytes, base-32 encoded strings, and DAG-JSON mappings with inner $link values.

The resulting URL is a com.atproto.sync.getBlob XRPC call to the PDS.

For blobs on the official bsky.social PDS, we could consider using their CDN instead: https://av-cdn.bsky.app/img/avatar/plain/[DID]/[CID]@jpeg

They also run a resizing image proxy on cdn.bsky.social with URLs like https://cdn.bsky.social/imgproxy/[SIG]/rs:fit:2000:2000:1:0/plain/[CID]@jpeg, not sure how to generate signatures for it yet.

Parameters:

• blob (dict) – https://atproto.com/specs/data-model#blob-type

• repo_did (str) – DID of the repo that owns this blob

• pds (str) – base URL of the PDS that serves this repo. Defaults to DEFAULT_PDS

Returns:

URL for this blob, or None if blob is empty or has no CID

Return type:

str

blob_cid(blob)[source]

Returns a blob’s base32-encoded CID.

Supports both new and old style blobs: https://atproto.com/specs/data-model#blob-type

Supports ref values as raw bytes, base-32 encoded strings, and DAG-JSON mappings with inner $link values.

Parameters:

blob (dict) – https://atproto.com/specs/data-model#blob-type

Returns:

this blob’s CID, base32-encoded

Return type:

str

class Bluesky(handle, pds_url=None, did=None, access_token=None, refresh_token=None, app_password=None, auth=None, session_callback=None, **requests_kwargs)[source]

Bases: Source

Bluesky source class. See file docstring and Source class for details.

handle

Type:

str

did

Type:

str

client

Type:

lexrpc.Client

classmethod user_url(handle)[source]

Returns the profile URL for a given handle.

Parameters:

handle (str)

Returns:

profile URL

Return type:

str

classmethod to_as1_actor(user, **kwargs)[source]

Converts a user to an actor.

Parameters:

• user (dict) – an app.bsky.actor.profile record

• kwargs – passed through to to_as1()

Returns:

ActivityStreams actor

Return type:

dict

classmethod user_to_actor(user, **kwargs)

Deprecated! Use to_as1_actor() instead.

classmethod post_url(handle, tid)[source]

Returns the post URL for a given handle and tid.

Parameters:

• handle (str)

• tid (str)

Returns:

profile URL

Return type:

str

classmethod post_id(url)[source]

Returns the at:// URI for the given URL if it’s for a post.

Also see arroba.util.parse_at_uri.

Returns:

str or None

get_activities_response(user_id=None, group_id=None, app_id=None, activity_id=None, fetch_replies=False, fetch_likes=False, fetch_shares=False, include_shares=True, fetch_mentions=False, search_query=None, start_index=None, count=None, cache=None, **kwargs)[source]

Fetches posts and converts them to AS1 activities.

See Source.get_activities_response() for more information.

Bluesky-specific details:

Parameters:

activity_id (str) – an at:// URI

get_actor(user_id=None)[source]

Fetches and returns a user.

Parameters:

user_id (str) – either handle or DID; defaults to current user

Returns:

ActivityStreams actor

Return type:

dict

get_comment(comment_id, **kwargs)[source]

Fetches and returns a comment.

Parameters:

• comment_id – string status id

• **kwargs – unused

Returns: dict, ActivityStreams object

Raises:

ValueError – if comment_id is invalid

get_followers(user_id=None)[source]

Returns the current user’s followers.

Limited to the first 10k followers.

Parameters:

user_id (str) – the DID to fetch followers for. If unset, defaults to self.user_id.

Returns:

ActivityStreams 1 actors

Return type:

sequence of dict

get_follows(user_id=None)[source]

Returns the current user’s follows.

Limited to the first 10k follows.

Parameters:

user_id (str) – the DID to fetch follows for. If unset, defaults to self.user_id.

Returns:

ActivityStreams 1 actors

Return type:

sequence of dict

create(obj, include_link='omit', ignore_formatting=False)[source]

Creates a post, reply, repost, or like.

Parameters:

• obj – ActivityStreams object

• include_link (str)

• ignore_formatting (bool)

Returns:

whose content will be a dict with id, url, and type keys (all optional) for the newly created object (or None)

Return type:

CreationResult

preview_create(obj, include_link='omit', ignore_formatting=False)[source]

Preview creating a post, reply, repost, or like.

Parameters:

• obj – ActivityStreams object

• include_link (str)

• ignore_formatting (bool)

Returns:

content will be a str HTML snippet or None

Return type:

CreationResult

delete(at_uri)[source]

Deletes a record.

Parameters:

at_uri (str) – at:// URI of record delete

Returns:

content is dict with url and id fields

Return type:

CreationResult

preview_delete(at_uri)[source]

Previews deleting a record.

Parameters:

at_uri (str) – at:// URI of record delete

Return type:

CreationResult

upload_media(media)[source]

Parameters:

media (sequence of dict AS1 objects)

Return type:

(dict mapping string URL to dict blob, dict mapping string URL to (int width, int height)) tuple

truncate(*args, type=None, **kwargs)[source]

Thin wrapper around Source.truncate() that sets default kwargs.

facebook

Facebook source class. Supports both Graph API and scraping HTML.

https://developers.facebook.com/docs/graph-api/using-graph-api/

class FacebookId(user, post, comment)

Bases: tuple

class Facebook(access_token=None, user_id=None, scrape=False, cookie_c_user=None, cookie_xs=None)[source]

Bases: Source

Facebook source class. See file docstring and Source for details.

access_token

optional, OAuth access token

Type:

str

user_id

optional, current user’s id (either global or app-scoped)

Type:

str

scrape

whether to scrape mbasic.facebook.com’s HTML (True) or use the API (False)

Type:

bool

cookie_c_user

optional c_user cookie to use when scraping

Type:

str

cookie_xs

optional xs cookie to use when scraping

Type:

str

get_actor(user_id=None)[source]

Returns a user as a JSON ActivityStreams actor dict.

Parameters:

user_id (str) – id or username. Defaults to me, ie the current user.

get_activities_response(user_id=None, group_id=None, app_id=None, activity_id=None, start_index=0, count=0, etag=None, min_id=None, cache=None, fetch_replies=False, fetch_likes=False, fetch_shares=False, fetch_events=False, fetch_mentions=False, search_query=None, fetch_news=False, event_owner_id=None, **kwargs)[source]

Fetches posts and converts them to ActivityStreams activities.

See Source.get_activities_response() for details.

Likes, top-level replies (ie comments), and reactions are always included. They come from the comments, likes, and reactions fields in the Graph API’s Post object: https://developers.facebook.com/docs/reference/api/post/

Threaded comments, ie comments in reply to other top-level comments, require an additional API call, so they’re only included if fetch_replies is True.

Mentions are never fetched or included because the API doesn’t support searching for them. https://github.com/snarfed/bridgy/issues/523#issuecomment-155523875

Most parameters are documented in Source.get_activities_response(). Additional parameters are documented here.

Parameters:

• fetch_news (bool) – whether to also fetch and include Open Graph news stories (/USER/news.publishes). Requires the user_actions.news permission. Background in https://github.com/snarfed/bridgy/issues/479

• event_owner_id (str) – if provided, only events owned by this user id will be returned. Avoids (but doesn’t entirely prevent) processing big non-indieweb events with tons of attendees that put us over App Engine’s instance memory limit. https://github.com/snarfed/bridgy/issues/77

get_event(event_id, owner_id=None)[source]

Returns a Facebook event post.

Parameters:

• id (str) – site-specific event id

• owner_id (str)

Returns:

ActivityStreams activity, or None if the event is not found or is owned by a different user than owner_id (if provided)

Return type:

dict

get_comment(comment_id, activity_id=None, activity_author_id=None, activity=None)[source]

Returns an ActivityStreams comment object.

Parameters:

• comment_id (str) – comment id

• activity_id (str) – activity id, optional

• activity_author_id (str) – activity author id, optional

• activity (dict) – activity object (optional)

Return type:

dict

get_share(activity_user_id, activity_id, share_id, activity=None)[source]

Returns an ActivityStreams share activity object.

Parameters:

• activity_user_id (str) – id of the user who posted the original activity

• activity_id (str) – activity id

• share_id (str) – id of the share object

• activity (dict) – activity object, optional

Return type:

dict

get_albums(user_id=None)[source]

Fetches and returns a user’s photo albums.

Parameters:

user_id (str) – id or username. Defaults to me, ie the current user.

Returns:

ActivityStream album objects

Return type:

sequence of dict

get_reaction(activity_user_id, activity_id, reaction_user_id, reaction_id, activity=None)[source]

Fetches and returns a reaction.

Parameters:

• activity_user_id (str) – id of the user who posted the original activity

• activity_id (str) – activity id

• reaction_user_id (str) – id of the user who reacted

• reaction_id (str) – id of the reaction. one of: love, wow, haha, sad, angry, thankful, pride, care

• activity (dict) – activity object (optional)

Return type:

dict

create(obj, include_link='omit', ignore_formatting=False)[source]

Creates a new post, comment, like, or RSVP.

Parameters:

• obj (dict) – ActivityStreams object

• include_link (str)

• ignore_formatting (bool)

Returns:

contents will be a dict with id and url keys for the newly created Facebook object

Return type:

CreationResult or None

preview_create(obj, include_link='omit', ignore_formatting=False)[source]

Previews creating a new post, comment, like, or RSVP.

Parameters:

• obj (dict) – ActivityStreams object

• include_link (str)

• ignore_formatting (bool)

Returns:

contents will be an HTML snippet

Return type:

CreationResult or None

create_notification(user_id, text, link)[source]

Sends the authenticated user a notification.

Uses the Notifications API (beta): https://developers.facebook.com/docs/games/notifications/#impl

Parameters:

• user_id (str) – username or user ID

• text (str) – shown to the user in the notification

• link (str) – relative URL, the user is redirected here when they click on the notification. Note that only the path and query parameters are used! they’re combined with the domain in your Facebook app’s Game App URL: https://developers.facebook.com/docs/games/services/appnotifications#parameters

Raises:

urllib3.HTPPError –

post_url(post)[source]

Returns a short Facebook URL for a post.

Parameters:

post (dict) – Facebook post

comment_url(post_id, comment_id, post_author_id=None)[source]

Returns a short Facebook URL for a comment.

Parameters:

• post_id (str) – Facebook post id

• comment_id (str) – Facebook comment id

classmethod base_id(url)[source]

Guesses the id of the object in the given URL.

Return type:

str or None

base_object(obj, verb=None, resolve_numeric_id=False)[source]

Returns the ‘base’ silo object that an object operates on.

This is mostly a big bag of heuristics for reverse engineering and parsing Facebook URLs. Whee.

Parameters:

• obj (dict) – ActivityStreams object

• verb (str) – optional

• resolve_numeric_id (bool) – if True, tries harder to populate the numeric_id field by making an additional API call to look up the object if necessary.

Returns:

minimal ActivityStreams object. Usually has at least id, numeric_id, and url fields; may also have author.

Return type:

dict

post_to_as1_activity(post)[source]

Converts a post to an AS1 activity.

Parameters:

post (dict) – a decoded JSON post

Returns:

ActivityStreams activity

Return type:

dict

post_to_activity(post)

Deprecated! Use post_to_as1_activity() instead.

post_to_as1(post, type=None)[source]

Converts a post to an AS1 object.

TODO: handle the sharedposts field

Parameters:

• post (dict) – a decoded JSON post

• type (str) – object type: None, post, or comment

Returns:

ActivityStreams object

Return type:

dict

post_to_object(post, type=None)

Deprecated! Use post_to_as1() instead.

comment_to_as1(comment, post_id=None, post_author_id=None)[source]

Converts a comment to an AS1 object.

Parameters:

• comment (dict) – a decoded JSON comment

• post_id (str) – optional Facebook post id. Only used if the comment id doesn’t have an embedded post id.

• post_author_id (str) – optional Facebook post author id. Only used if the comment id doesn’t have an embedded post author id.

Returns:

ActivityStreams object

Return type:

dict

comment_to_object(comment, post_id=None, post_author_id=None)

Deprecated! Use comment_to_as1() instead.

share_to_as1(share)[source]

Converts a share (from /OBJECT/sharedposts) to an AS1 object.

Parameters:

share (dict) – JSON share

Returns:

ActivityStreams object

Return type:

dict

share_to_object(share)

Deprecated! Use share_to_as1() instead.

to_as1_actor(user)[source]

Converts a user or page to an actor.

Parameters:

user (dict) – Facebook user or page object

Returns:

ActivityStreams actor

Return type:

dict

user_to_actor(user)

Deprecated! Use to_as1_actor() instead.

event_to_as1_object(event, rsvps=None)[source]

Converts an event to an AS1 object.

Parameters:

• event (dict) – Facebook event object

• rsvps (sequence of dict) – optional Facebook RSVPs

Returns:

ActivityStreams object

Return type:

dict

event_to_object(event, rsvps=None)

Deprecated! Use event_to_as1_object() instead.

event_to_as1_activity(event, rsvps=None)[source]

Converts a event to an AS1 activity.

Parameters:

• event (dict) – Facebook event object

• rsvps (list of dict) – Facebook RSVP objects

Returns:

ActivityStreams activity

Return type:

dict

event_to_activity(event, rsvps=None)

Deprecated! Use event_to_as1_activity() instead.

rsvp_to_as1(rsvp, type=None, event=None)[source]

Converts an RSVP to an AS1 object.

The id field will ony be filled in if event['id'] is provided.

Parameters:

• rsvp (dict) – Facebook RSVP object

• type (str) – optional Facebook RSVP type, one of RSVP_FIELDS

• event (dict) – Facebook event object. May contain only a single id element.

Returns:

ActivityStreams object

Return type:

dict

rsvp_to_object(rsvp, type=None, event=None)

Deprecated! Use rsvp_to_as1() instead.

album_to_as1(album)[source]

Converts a photo album to an object.

Parameters:

album (dict) – Facebook album object

Returns:

ActivityStreams object

Return type:

dict

album_to_object(album)

Deprecated! Use album_to_as1() instead.

privacy_to_to(obj, type=None)[source]

Converts a Facebook privacy field to an ActivityStreams to field.

privacy is sometimes an object: https://developers.facebook.com/docs/graph-api/reference/post#fields

…and other times a string: https://developers.facebook.com/docs/graph-api/reference/album/#readfields

Parameters:

• obj (dict) – Facebook object (post, album, comment, etc)

• type (str) – object type: None, post, or comment

Returns:

ActivityStreams to object, or None if unknown

Return type:

dict

email_to_as1(html)[source]

Converts a Facebook HTML notification email to an AS1 object.

Parameters:

html – str

Returns:

ActivityStreams object, or None if html couldn’t be parsed

Return type:

dict

email_to_object(html)

Deprecated! Use email_to_as1() instead.

scraped_to_as1_activities(scraped, log_html=False, **kwargs)[source]

Converts HTML from an mbasic.facebook.com timeline to AS1 activities.

Parameters:

• scraped (str) – HTML

• log_html (bool)

• kwargs – unused

Returns:

([AS activities], AS logged in actor (ie viewer))

Return type:

tuple

scraped_to_activities(scraped, log_html=False, **kwargs)

Deprecated! Use scraped_to_as1_activities() instead.

scraped_to_as1_activity(scraped, log_html=False, **kwargs)[source]

Converts HTML from an mbasic.facebook.com post page to an AS1 activity.

Parameters:

• scraped (str) – HTML from an mbasic.facebook.com post permalink

• log_html (bool)

• kwargs – unused

Returns:

(dict AS activity or None, AS logged in actor (ie viewer))

Return type:

tuple

scraped_to_activity(scraped, log_html=False, **kwargs)

Deprecated! Use scraped_to_as1_activity() instead.

merge_scraped_reactions(scraped, activity)[source]

Converts and merges scraped likes and reactions into an activity.

New likes and emoji reactions are added to the activity in tags. Existing likes and emoji reactions in tags are ignored.

Parameters:

• scraped (str) – HTML from an mbasic.facebook.com/ufi/reaction/profile/browser/ page

• activity (dict) – AS activity to merge these reactions into

Returns:

AS like/react tag objects converted from scraped

Return type:

list of dict

scraped_to_as1_actor(scraped)[source]

Converts HTML from a profile about page to an AS1 actor.

Parameters:

scraped (str) – HTML from an mbasic.facebook.com post permalink

Returns:

AS1 actor

Return type:

dict

scraped_to_actor(scraped)

Deprecated! Use scraped_to_as1_actor() instead.

static parse_id(id, is_comment=False)[source]

Parses a Facebook post or comment id.

Facebook ids come in different formats:

• Simple number, usually a user or post: 12

• Two numbers with underscore, usually POST_COMMENT or USER_POST: 12_34

• Three numbers with underscores, USER_POST_COMMENT: 12_34_56

• Three numbers with colons, USER:POST:SHARD: 12:34:63 (We’re guessing that the third part is a shard in some FB internal system. In our experience so far, it’s always either 63 or the app-scoped user id for 63.)

• Two numbers with colon, POST:SHARD: 12:34 (We’ve seen 0 as shard in this format.)

• Four numbers with colons/underscore, USER:POST:SHARD_COMMENT: 12:34:63_56

• Five numbers with colons/underscore, USER:EVENT:UNKNOWN:UNKNOWN_UNKNOWN. Not currently supported! Examples: * 111599105530674:998145346924699:10102446236688861:10207188792305341_998153510257216 * 111599105530674:195181727490727:10102446236688861:10205257726909910_195198790822354

Background:

• https://github.com/snarfed/bridgy/issues/305

• https://developers.facebook.com/bugs/786903278061433/

Parameters:

• id (str or int)

• is_comment (bool)

Returns:

Some or all fields may be None.

Return type:

FacebookId

resolve_object_id(user_id, post_id, activity=None)[source]

Resolve a post id to its Facebook object id, if any.

Used for photo posts, since Facebook has (at least) two different objects (and ids) for them, one for the post and one for each photo.

This is the same logic that we do for canonicalizing photo objects in get_activities() above.

If activity is not provided, fetches the post from Facebook.

Parameters:

• user_id (str) – Facebook user id who posted the post

• post_id (str) – Facebook post id

• activity (dict) – optional AS activity representation of Facebook post

Returns:

Facebook object id or None

Return type:

str

urlopen(url, _as=<class 'dict'>, **kwargs)[source]

Wraps urllib2.urlopen() and passes through the access token.

Parameters:

_as (type) – if not None, parses the response as JSON and passes it through _as() with this type. if None, returns the response object.

Returns:

decoded JSON response

Return type:

dict

urlopen_batch(urls)[source]

Sends a batch of multiple API calls using Facebook’s batch API.

Raises the appropriate urllib2.HTTPError if any individual call returns HTTP status code 4xx or 5xx.

https://developers.facebook.com/docs/graph-api/making-multiple-requests

Parameters:

urls (sequence of str) – relative API URLs, eg [me, me/accounts]

Returns:

responses, either decoded JSON objects (when possible) or raw str bodies

Return type:

sequence of dict

urlopen_batch_full(requests)[source]

Sends a batch of multiple API calls using Facebook’s batch API.

Similar to urlopen_batch(), but the requests arg and return value are dicts with headers, HTTP status code, etc. Raises urllib2.HTTPError if the outer batch request itself returns an HTTP error.

https://developers.facebook.com/docs/graph-api/making-multiple-requests

Parameters:

requests (sequence of dict) –

requests in Facebook’s batch format, except that headers is a single dict, not a list of dicts, e.g.:

[{'relative_url': 'me/feed',
  'headers': {'ETag': 'xyz', ...},
 },
 ...
]

Returns:

responses in Facebook’s batch format, except that body is JSON-decoded if possible, and headers is a single dict, not a list of dicts, e.g.:

[{'code': 200,
  'headers': {'ETag': 'xyz', ...},
  'body': {...},
 },
 ...
]

Return type:

sequence of dict

flickr

Flickr source class.

Uses Flickr’s REST API https://www.flickr.com/services/api/

TODO: Fetching feeds with comments and/or favorites is very request intensive right now. It would be ideal to find a way to batch requests, make requests asynchronously, or make better calls to the API itself. Maybe use flickr.activity.userPhotos (https://www.flickr.com/services/api/flickr.activity.userPhotos.html) when group_id=SELF`.

class Flickr(access_token_key, access_token_secret, user_id=None, path_alias=None)[source]

Bases: Source

Flickr source class. See file docstring and Source class for details.

call_api_method(method, params=None)[source]

Call a Flickr API method.

upload(params, file)[source]

Upload a photo or video via the Flickr API.

create(obj, include_link='omit', ignore_formatting=False)[source]

Creates a photo, comment, or favorite.

Parameters:

• obj (dict) – ActivityStreams object

• include_link (str)

• ignore_formatting (bool)

Returns:

content will be a dict with id, url, and type keys (all optional) for the newly created Flickr object

Return type:

CreationResult or None

preview_create(obj, include_link='omit', ignore_formatting=False)[source]

Preview creation of a photo, comment, or favorite.

Parameters:

• obj (dict) – ActivityStreams object

• include_link (str)

• ignore_formatting (bool)

Returns:

whose description will be an HTML summary of what publishing will do, and whose content will be an HTML preview of the result

Return type:

CreationResult or None

delete(id)[source]

Deletes a photo. The authenticated user must have created it.

Parameters:

id (int or str) – photo id to delete

Returns:

content is Flickr API response dict

Return type:

CreationResult

preview_delete(id)[source]

Previews deleting a photo.

Parameters:

id (int or str) – photo id to delete

Return type:

CreationResult

get_activities_response(user_id=None, group_id=None, app_id=None, activity_id=None, start_index=0, count=0, etag=None, min_id=None, cache=None, fetch_replies=False, fetch_likes=False, fetch_shares=False, fetch_events=False, fetch_mentions=False, search_query=None, **kwargs)[source]

Fetches Flickr photos and converts them to ActivityStreams activities.

See Source.get_activities_response() for details.

Mentions are not fetched or included because they don’t exist in Flickr. https://github.com/snarfed/bridgy/issues/523#issuecomment-155523875

get_actor(user_id=None)[source]

Get an ActivityStreams object of type person given a user’s nsid. If no user_id is provided, this method will make another API request to find out the currently logged in user’s id.

Parameters:

user_id (str) – optional

Returns:

an ActivityStreams object

Return type:

dict

to_as1_actor(resp)[source]

Convert a Flickr user dict into an ActivityStreams actor.

user_to_actor(resp)

Deprecated! Use to_as1_actor() instead.

get_comment(comment_id, activity_id=None, activity_author_id=None, activity=None)[source]

Returns an ActivityStreams comment object.

Parameters:

• comment_id (str)

• activity_id (str)

• activity_author_id (str)

• activity (dict) – activity object, optional. Avoids fetching the activity if provided.

photo_to_activity(photo)[source]

Convert a Flickr photo to an ActivityStreams object.

Takes either data in the expanded form returned by flickr.photos.getInfo or the abbreviated form returned by flickr.people.getPhotos.

Parameters:

photo (dict) – response from Flickr

Returns:

ActivityStreams object

Return type:

dict

like_to_as1(person, photo_activity)[source]

Convert a Flickr favorite into an ActivityStreams like tag.

Parameters:

• person (dict) – the person object from Flickr

• photo_activity (dict) – the ActivityStreams object representing the photo this like belongs to

Returns:

ActivityStreams object

Return type:

dict

like_to_object(person, photo_activity)

Deprecated! Use like_to_as1() instead.

comment_to_as1(comment, photo_id)[source]

Convert a Flickr comment JSON object to an ActivityStreams comment.

Parameters:

• comment (dict) – the comment object from Flickr

• photo_id (str) – the Flickr ID of the photo that this comment belongs to

Returns:

ActivityStreams object

Return type:

dict

comment_to_object(comment, photo_id)

Deprecated! Use comment_to_as1() instead.

get_user_image(farm, server, author)[source]

Convert fields from a typical Flickr response into the buddy icon URL.

https://www.flickr.com/services/api/misc.buddyicons.html

user_id()[source]

Get the nsid of the currently authorized user.

The first time this is called, it will invoke the flickr.people.getLimits API method.

https://www.flickr.com/services/api/flickr.people.getLimits.html

Return type:

str

path_alias()[source]

Get the path_alias of the currently authorized user.

The first time this is called, it will invoke the flickr.people.getInfo API method.

https://www.flickr.com/services/api/flickr.people.getInfo.html

Return type:

str

user_url(user_id)[source]

Convert a user’s path_alias to their Flickr profile page URL.

Parameters:

user_id (str) – user’s alphanumeric nsid or path alias

Returns:

a profile URL

Return type:

str

photo_url(user_id, photo_id)[source]

Construct a url for a photo.

Parameters:

• user_id (str) – alphanumeric user ID or path alias

• photo_id (str) – numeric photo ID

Returns:

photo URL

Return type:

str

classmethod base_id(url)[source]

Used when publishing comments or favorites.

Flickr photo ID is the 3rd path component rather than the first.

github

GitHub source class. Uses the v4 GraphQL API and the v3 REST API.

API docs:

• https://developer.github.com/v4/

• https://developer.github.com/v3/

• https://developer.github.com/apps/building-oauth-apps/authorization-options-for-oauth-apps/#web-application-flow

class GitHub(access_token=None)[source]

Bases: Source

GitHub source class. See file docstring and Source for details.

access_token

optional, OAuth access token

Type:

str

classmethod base_id(url)[source]

Extracts and returns a USERNAME:REPO:ID id for an issue or PR.

Parameters:

url (str)

Return type:

str or None

graphql(graphql, kwargs)[source]

Makes a v4 GraphQL API call.

Parameters:

graphql (str) – GraphQL operation

Returns:

parsed JSON response

Return type:

dict

rest(url, data=None, parse_json=True, **kwargs)[source]

Makes a v3 REST API call.

Uses HTTP POST if data is provided, otherwise GET.

Parameters:

• data (dict) – JSON payload for POST requests

• json (bool) – whether to parse the response body as JSON and return it as a dict. If False, returns a requests.Response instead.

Returns:

decoded from JSON response if json=True, otherwise

requests.Response

Return type:

dict

get_activities_response(user_id=None, group_id=None, app_id=None, activity_id=None, start_index=0, count=0, etag=None, min_id=None, cache=None, fetch_replies=False, fetch_likes=False, fetch_shares=False, fetch_events=False, fetch_mentions=False, search_query=None, public_only=True, **kwargs)[source]

Fetches issues and comments and converts them to ActivityStreams activities.

See Source.get_activities_response() for details.

Not comprehensive! Uses the notifications API (v3 REST).

Also note that start_index is not currently supported.

• https://developer.github.com/v3/activity/notifications/

• https://developer.github.com/v3/issues/

• https://developer.github.com/v3/issues/comments/

fetch_likes determines whether emoji reactions are fetched: https://help.github.com/articles/about-conversations-on-github#reacting-to-ideas-in-comments

The notifications API call supports Last-Modified/If-Modified-Since headers and 304 Not Changed responses. If provided, etag should be an RFC2822 timestamp, usually the exact value returned in a Last-Modified header. It will also be passed to the comments API endpoint as the since= value (converted to ISO8601).

get_actor(user_id=None)[source]

Fetches and returns a user.

Parameters:

user_id (str) – defaults to current user

Returns:

ActivityStreams actor object

Return type:

dict

get_comment(comment_id, **kwargs)[source]

Fetches and returns a comment.

Parameters:

comment_id (str) – comment id (either REST or GraphQL), of the form REPO-OWNER:REPO-NAME:ID, e.g. snarfed:bridgy:456789

Returns:

an ActivityStreams comment object

Return type:

dict

render_markdown(markdown, owner, repo)[source]

Uses the GitHub API to render GitHub-flavored Markdown to HTML.

• https://developer.github.com/v3/markdown/

• https://github.github.com/gfm/

Parameters:

• markdown (str) – input

• repo (owner and) – the repo to render in, for context. affects git hashes #XXX for issues/PRs.

Returns:

rendered HTML

Return type:

str

create(obj, include_link='omit', ignore_formatting=False)[source]

Creates a new issue or comment.

Parameters:

• obj (dict) – ActivityStreams object

• include_link (str)

• ignore_formatting (bool)

Returns:

contents will be a dict with id and url keys for the newly created GitHub object

Return type:

CreationResult or None

preview_create(obj, include_link='omit', ignore_formatting=False)[source]

Previews creating an issue or comment.

Parameters:

• obj (dict) – ActivityStreams object

• include_link (str)

• ignore_formatting (bool)

Returns:

contents will be a str HTML snippet

Return type:

CreationResult or None

existing_labels(owner, repo)[source]

Fetches and returns a repo’s labels.

Parameters:

• owner (str) – GitHub username or org that owns the repo

• repo (str)

Return type:

set of str

issue_to_as1(issue)[source]

Converts a GitHub issue or pull request to ActivityStreams.

Handles both v4 GraphQL and v3 REST API issue and PR objects.

• https://developer.github.com/v4/object/issue/

• https://developer.github.com/v4/object/pullrequest/

• https://developer.github.com/v3/issues/

• https://developer.github.com/v3/pulls/

Parameters:

issue (dict) – GitHub issue or PR

Returns:

ActivityStreams object

Return type:

dict

issue_to_object(issue)

Deprecated! Use issue_to_as1() instead.

pr_to_as1(issue)

Converts a GitHub issue or pull request to ActivityStreams.

Handles both v4 GraphQL and v3 REST API issue and PR objects.

• https://developer.github.com/v4/object/issue/

• https://developer.github.com/v4/object/pullrequest/

• https://developer.github.com/v3/issues/

• https://developer.github.com/v3/pulls/

Parameters:

issue (dict) – GitHub issue or PR

Returns:

ActivityStreams object

Return type:

dict

pr_to_object(issue)

Deprecated! Use pr_to_as1() instead.

comment_to_as1(comment)[source]

Converts a GitHub comment to ActivityStreams.

Handles both v4 GraphQL and v3 REST API issue objects.

• https://developer.github.com/v4/object/issue/

• https://developer.github.com/v3/issues/

Parameters:

comment (dict) – GitHub issue

Returns:

ActivityStreams comment

Return type:

dict

comment_to_object(comment)

Deprecated! Use comment_to_as1() instead.

reaction_to_as1(reaction, target)[source]

Converts a GitHub emoji reaction to ActivityStreams.

Handles v3 REST API reaction objects.

https://developer.github.com/v3/reactions/

Parameters:

• reaction (dict) – v3 GitHub reaction

• target (dict) – ActivityStreams object of reaction

Returns:

ActivityStreams reaction

Return type:

dict

reaction_to_object(reaction, target)

Deprecated! Use reaction_to_as1() instead.

to_as1_actor(user)[source]

Converts a GitHub user to an ActivityStreams actor.

Handles both v4 GraphQL and v3 REST API user objects.

• https://developer.github.com/v4/object/user/

• https://developer.github.com/v3/users/

Parameters:

user (dict) – GitHub user

Returns:

ActivityStreams actor

Return type:

dict

user_to_actor(user)

Deprecated! Use to_as1_actor() instead.

instagram

Instagram source class.

Instagram’s API doesn’t tell you if a user has marked their account private or not, so the Audience Targeting to field is currently always set to @public.

• http://help.instagram.com/448523408565555

• https://groups.google.com/forum/m/#!topic/instagram-api-developers/DAO7OriVFsw

• https://groups.google.com/forum/#!searchin/instagram-api-developers/private

class Instagram(access_token=None, allow_comment_creation=False, scrape=False, cookie=None)[source]

Bases: Source

Instagram source class. See file docstring and Source class for details.

urlopen(url, **kwargs)[source]

Wraps urllib2.urlopen() and passes through the access token.

get_actor(user_id=None, **kwargs)[source]

Returns a user as a JSON ActivityStreams actor dict.

Parameters:

• user_id (str) – id or username. Defaults to self, ie the current user.

• kwargs – if scraping, passed through to :meth:get_activities_response``.

Raises:

AssertionError – if kwargs is provided but we’re not scraping

get_activities_response(user_id=None, group_id=None, app_id=None, activity_id=None, start_index=0, count=0, etag=None, min_id=None, cache=None, fetch_replies=False, fetch_likes=False, fetch_shares=False, fetch_events=False, fetch_mentions=False, search_query=None, scrape=False, cookie=None, ignore_rate_limit=False, **kwargs)[source]

Fetches posts and converts them to ActivityStreams activities.

See Source.get_activities_response() for details. app_id is ignored. Supports min_id, but not ETag, since Instagram doesn’t support it.

• http://instagram.com/developer/endpoints/users/#get_users_feed

• http://instagram.com/developer/endpoints/users/#get_users_media_recent

Likes are always included, regardless of the fetch_likes kwarg. They come bundled in the likes field of the API Media object: http://instagram.com/developer/endpoints/media/#

Mentions are never fetched or included because the API doesn’t support searching for them. https://github.com/snarfed/bridgy/issues/523#issuecomment-155523875

Shares are never fetched or included since there is no share feature.

Instagram only supports search over hashtags, so if search_query is set, it must begin with #.

May populate a custom ig_like_count property in media objects. (Currently only when scraping.)

Parameters:

• scrape (bool) – if True, scrapes HTML from instagram.com instead of using the API. Populates the user’s actor object in the actor response field. Useful for apps that haven’t yet been approved in the new permissions approval process. Currently only supports group_id=SELF. Also supports passing a shortcode as activity_id as well as the internal API id. http://developers.instagram.com/post/133424514006/instagram-platform-update

• cookie (str) – only used if scrape=True

• ignore_rate_limit (bool) – for scraping, always make an HTTP request, even if we’ve been rate limited recently

get_comment(comment_id, activity_id=None, activity_author_id=None, activity=None)[source]

Returns an ActivityStreams comment object.

Parameters:

• comment_id (str) – comment id

• activity_id (str) – activity id, optional

• activity_author_id (str) – activity author id. Ignored.

• activity (dict) – activity object, optional. Avoids fetching the activity.

get_share(activity_user_id, activity_id, share_id, activity=None)[source]

Not implemented. Returns None. Resharing isn’t a feature of Instagram.

create(obj, include_link='omit', ignore_formatting=False)[source]

Creates a new comment or like.

Parameters:

• obj (dict) – ActivityStreams object

• include_link (str)

• ignore_formatting (bool)

Returns:

if successful, content will have and id and url

keys for the newly created Instagram object

Return type:

CreationResult

preview_create(obj, include_link='omit', ignore_formatting=False)[source]

Preview a new comment or like.

Parameters:

• obj (Dcit) – ActivityStreams object

• include_link (str)

• ignore_formatting (bool)

Returns:

if successful, content and description will describe the

new Instagram object.

Return type:

CreationResult

media_to_as1(media)[source]

Converts a media to an activity.

http://instagram.com/developer/endpoints/media/#get_media

Parameters:

media (dict) – JSON object retrieved from the Instagram API

Returns:

ActivityStreams activity

Return type:

dict

media_to_activity(media)

Deprecated! Use media_to_as1() instead.

media_to_object(media)[source]

Converts a media to an object.

Deprecated! Use media_to_as1() instead.

Parameters:

media (dict) – JSON object retrieved from the Instagram API

Returns:

ActivityStreams object

Return type:

dict

comment_to_as1(comment, media_id, media_url)[source]

Converts a comment to an object.

Parameters:

• comment (dict) – JSON object retrieved from the Instagram API

• media_id (str)

• media_url (str)

Returns:

ActivityStreams object

Return type:

dict

comment_to_object(comment, media_id, media_url)

Deprecated! Use comment_to_as1() instead.

like_to_as1(liker, media_id, media_url)[source]

Converts a like to an object.

Parameters:

• liker (dict) – JSON object from the Instagram API, user who does the liking

• media_id (str)

• media_url (str)

Returns:

ActivityStreams object

Return type:

dict

like_to_object(liker, media_id, media_url)

Deprecated! Use like_to_as1() instead.

to_as1_actor(user)[source]

Converts a user to an actor.

Parameters:

user (dict) – JSON object from the Instagram API

Returns:

ActivityStreams actor

Return type:

dict

user_to_actor(user)

Deprecated! Use to_as1_actor() instead.

base_object(obj)[source]

Extends the default base_object() to avoid using shortcodes as object ids.

static id_to_shortcode(id)[source]

Converts a media id to the shortcode used in its instagram.com URL.

Based on http://carrot.is/coding/instagram-ids , which determined that shortcodes are just URL-safe base64 encoded ids.

scraped_to_as1(input, cookie=None, count=None, fetch_extras=False)[source]

Converts scraped Instagram HTML to ActivityStreams activities.

The input HTML may be from:

• a user’s feed, eg https://www.instagram.com/ while logged in

• a user’s profile, eg https://www.instagram.com/snarfed/

• a photo or video, eg https://www.instagram.com/p/BBWCSrfFZAk/

• serialized JSON from the API for a feed, profile, or post, eg https://i.instagram.com/api/v1/feed/timeline/

Parameters:

• input (str) – containing either HTML or JSON

• cookie (str) – optional sessionid cookie to be used for subsequent HTTP fetches, if necessary.

• count (int) – number of activities to return, None for all

• fetch_extras (bool) – whether to make extra HTTP fetches to get likes, etc.

Returns:

([ActivityStreams activities], ActivityStreams viewer actor)

Return type:

tuple

html_to_activities(input, cookie=None, count=None, fetch_extras=False)

Deprecated! Use scraped_to_as1() instead.

scraped_to_activities(input, cookie=None, count=None, fetch_extras=False)

Deprecated! Use scraped_to_as1() instead.

scraped_json_to_as1(input, cookie=None, count=None, fetch_extras=False)[source]

Converts scraped Instagram JSON to ActivityStreams activities.

The input JSON may be from a user’s profile, eg

https://i.instagram.com/api/v1/users/web_profile_info/?username=…

Parameters:

• input (dict or sequence of dicts) – Instagram JSON object(s)

• cookie (str) – optional sessionid cookie to be used for subsequent HTTP fetches, if necessary.

• count (int) – number of activities to return, None for all

• fetch_extras (bool) – whether to make extra HTTP fetches to get likes, etc.

Returns:

([ActivityStreams activities], ActivityStreams viewer actor)

Return type:

tuple

scraped_json_to_activities(input, cookie=None, count=None, fetch_extras=False)

Deprecated! Use scraped_json_to_as1() instead.

scraped_to_activity(html, **kwargs)[source]

Converts HTML from photo/video permalink page to an AS1 activity.

Deprecated! Use scraped_to_as1() instead.

Parameters:

• html (str) – HTML from a photo/video page on instagram.com

• kwargs – passed through to scraped_to_activities

Returns:

(AS activity or None, AS logged in actor (ie viewer))

Return type:

tuple

scraped_to_as1_actor(html, **kwargs)[source]

Extracts and returns the logged in actor from any Instagram HTML.

Parameters:

html (str)

Returns:

AS1 actor

Return type:

dict

scraped_to_actor(html, **kwargs)

Deprecated! Use scraped_to_as1_actor() instead.

merge_scraped_comments(scraped, activity)[source]

Converts and merges scraped comments (replies) into an activity.

Parameters:

• scraped (str or sequence) – scraped JSON comments

• activity (dict) – AS activity to merge these comments into

Returns:

AS comment objects converted from scraped

Return type:

list of dict

Raises:

ValueError – if scraped is not valid JSON

merge_scraped_reactions(scraped, activity)[source]

Converts and merges scraped likes and reactions into an activity.

New likes and emoji reactions are added to the activity in tags. Existing likes and emoji reactions in tags are ignored.

Supports both legacy and v2 Instagram JSON.

Parameters:

• scraped (str or dict) – scraped JSON likes

• activity (dict) – AS activity to merge these reactions into

Returns:

AS like tag objects converted from scraped

Return type:

list of dict

Raises:

ValueError – if scraped is not valid JSON