Generate Reply Context

To generate reply context for a given page, use the following function:

indieweb_utils.get_reply_context(url: str, twitter_bearer_token: str = '', summary_word_limit: int = 75) → ReplyContext[source]

Generate reply context for use on your website based on a URL.

Parameters:

url (str) – The URL of the post to generate reply context for.
twitter_bearer_token (str) – The optional Twitter bearer token to use. This token is used to retrieve a Tweet from Twitter’s API if you want to generate context using a Twitter URL.
summary_word_limit (int) – The maximum number of words to include in the summary (default 75).

Returns:

A ReplyContext object with information about the specified web page.

Return type:

ReplyContext

Example:

import indieweb_utils

context = indieweb_utils.get_reply_context(
    url="https://jamesg.blog",
    summary_word_limit=50
)

# print the name of the specified page to the console
print(context.name) # "Home | James' Coffee Blog"

Raises:

ReplyContextRetrievalError – Reply context cannot be retrieved.
UnsupportedScheme – The specified URL does not use http:// or https://.

This function returns a ReplyContext object that looks like this:

class indieweb_utils.ReplyContext(webmention_endpoint: str, photo: str, name: str, video: str, post_html: str, post_text: str, authors: List[PostAuthor], description: str)[source]: Context about a web page and its contents.

Generate a URL Summary

You can generate a summary of a URL without retrieving the page using the get_url_summary function.

By default, this function can generate a summary for the following URLs:

github.com
twitter.com
eventbrite.com / eventbrite.co.uk
upcoming.com
calagator.com
events.indieweb.org
indieweb.org

indieweb_utils.get_url_summary(url: str, custom_templates: list | None = None)[source]

Return a text summary for given url.

Parameters:

url – The URL to summarize.
custom_templates – A list of tuples with patterns against which to check when generating a summary associated with results to return.

Returns:

A summary of the URL.

Return type:

str

import indieweb_utils

# a dictionary of custom patterns against which to match during the lookup
custom_properties = {
    "jamesg.blog": [
        (r"coffee/maps/(?P<location>.+)", "A map of {location} coffee shops on jamesg.blog")
    ]
}

summary = indieweb_utils.get_summary("https://github.com/capjamesg/indieweb-utils/pulls/1")

print(summary) # "A comment on a pull request in the indieweb-utils GitHub repository"

summary = indieweb_utils.get_summary("https://jamesg.blog/coffee/maps/london")

print(summary) # "A map of london coffee shops on jamesg.blog"

You can specify custom mappings for other domains using the custom_mappings parameter.

This parameter accepts a dictionary of with domain names mapped to lists of tuples with patterns to match and strings to return, like this:

{
    "example.com": [
        (r"example.com/(\d+)", "Example #{}"),
    ]
}

If a summary cannot be generated, this function returns “A post by [domain_name].”, where domain name is the domain of the URL you passed into the function.