webmentions package

Subpackages

• webmentions.handlers package
  • Module contents
    • WebmentionsHandler
      • WebmentionsHandler.process_incoming_webmention()
      • WebmentionsHandler.process_outgoing_webmentions()
      • WebmentionsHandler.retrieve_stored_webmentions()
• webmentions.server package
  • Subpackages
    • webmentions.server.adapters package
      • Submodules
      • Module contents
  • Module contents
• webmentions.storage package
  • Subpackages
    • webmentions.storage.adapters package
      • Subpackages
      • Module contents
  • Module contents
    • WebmentionsStorage
      • WebmentionsStorage.delete_webmention()
      • WebmentionsStorage.mark_sent()
      • WebmentionsStorage.retrieve_webmentions()
      • WebmentionsStorage.store_webmention()

Module contents

class webmentions.ContentTextFormat(value)

Bases: str, Enum

Supported content text formats.

HTML = 'html'

MARKDOWN = 'markdown'

TEXT = 'text'

class webmentions.Webmention(source: str, target: str, direction: ~webmentions._model.WebmentionDirection, title: str | None = None, excerpt: str | None = None, content: str | None = None, author_name: str | None = None, author_url: str | None = None, author_photo: str | None = None, published: ~datetime.datetime | None = None, status: ~webmentions._model.WebmentionStatus = WebmentionStatus.CONFIRMED, mention_type: ~webmentions._model.WebmentionType = WebmentionType.UNKNOWN, mention_type_raw: str | None = None, metadata: dict = <factory>, created_at: ~datetime.datetime | None = None, updated_at: ~datetime.datetime | None = None)

Bases: object

Data class representing a Webmention.

author_name: str | None = None

author_photo: str | None = None

author_url: str | None = None

classmethod build(data: dict, direction: WebmentionDirection = WebmentionDirection.IN) → Webmention

content: str | None = None

created_at: datetime | None = None

direction: WebmentionDirection

excerpt: str | None = None

mention_type: WebmentionType = 'unknown'

mention_type_raw: str | None = None

metadata: dict

published: datetime | None = None

source: str

status: WebmentionStatus = 'confirmed'

target: str

title: str | None = None

to_dict() → dict

Returns:

A dictionary representation of the Webmention

updated_at: datetime | None = None

class webmentions.WebmentionDirection(value)

Bases: str, Enum

Enum representing the direction of a Webmention (incoming or outgoing).

IN = 'incoming'

OUT = 'outgoing'

classmethod from_raw(raw: str) → WebmentionDirection

exception webmentions.WebmentionException(source: str | None, target: str | None, message: str, **_)

Bases: Exception

Base exception for webmention errors.

exception webmentions.WebmentionGone(source: str | None, target: str | None, msg: str | None = None, **_)

Bases: WebmentionException, ValueError

Exception for webmentions that no longer exist.

class webmentions.WebmentionStatus(value)

Bases: str, Enum

Enum representing the status of a Webmention (pending, confirmed, or deleted).

CONFIRMED = 'confirmed'

DELETED = 'deleted'

PENDING = 'pending'

class webmentions.WebmentionType(value)

Bases: str, Enum

Enum representing the type of Webmention.

Note that this list is not exhaustive, and the Webmention recommendation itself does not provide any static list.

This is however a lis of commonly supported types in Microformats.

BOOKMARK = 'bookmark'

FOLLOW = 'follow'

LIKE = 'like'

MENTION = 'mention'

REPLY = 'reply'

REPOST = 'repost'

RSVP = 'rsvp'

UNKNOWN = 'unknown'

classmethod from_raw(raw: str | None) → WebmentionType

class webmentions.WebmentionsHandler(storage: WebmentionsStorage, *, base_url: str | None = None, http_timeout: float = 10.0, user_agent: str = 'WebmentionSender', on_mention_processed: Callable[[Webmention], None] | None = None, on_mention_deleted: Callable[[Webmention], None] | None = None, initial_mention_status: WebmentionStatus = WebmentionStatus.CONFIRMED, **kwargs)

Bases: object

Webmentions handler.

Parameters:

• storage – The Webmentions storage backend

• base_url – The base URL of the server, used to validate target URLs

• http_timeout – The HTTP timeout for fetching source URLs

• user_agent – The User-Agent header to use when fetching source URLs

• on_mention_processed – A callback to call when a Webmention is processed

• on_mention_deleted – A callback to call when a Webmention is deleted

• initial_mention_status – The initial status of Webmentions (see WebmentionStatus). If not specified, defaults to WebmentionStatus.CONFIRMED. If you set this to WebmentionStatus.PENDING then you will need to manually mark mentions as confirmed on your storage, or create your on on_mention_processed that performs custom filtering or moderation and calls handler.storage.store_webmention(webmention) with the right status after processing.

process_incoming_webmention(source_url: str | None, target_url: str | None) → Any

Process an incoming Webmention.

Parameters:

• source_url – The source URL of the Webmention

• target_url – The target URL of the Webmention

process_outgoing_webmentions(source_url: str, *, text: str | None = None, text_format: ContentTextFormat | None = None) → Any

Process an outgoing Webmention.

Parameters:

• source_url – The source URL of the Webmention. Ignored if text is provided.

• text – The text of the Webmention. If not provided, the source URL will be fetched.

• text_format – The text format of the Webmention. If not provided, it will be inferred from the source URL or text.

retrieve_stored_webmentions(resource: str, direction: WebmentionDirection) → list[Webmention]

Retrieve stored Webmentions for a given URL.

Parameters:

• resource – The resource URL

• direction – The direction of the Webmentions (inbound or outbound)

Returns:

A list of Webmentions

class webmentions.WebmentionsStorage

Bases: ABC

Base class for Webmention storage backends.

abstract delete_webmention(source: str, target: str, direction: WebmentionDirection) → Any | None

Mark a Webmention as deleted.

Parameters:

• source – The source URL of the Webmention

• target – The target URL of the Webmention

• direction – The direction of the Webmention (inbound or outbound)

mark_sent(source: str, target: str) → None

Mark a Webmention as sent.

Parameters:

• source – The source URL of the Webmention

• target – The target URL of the Webmention

abstract retrieve_webmentions(resource: str, direction: WebmentionDirection) → list[Webmention]

Retrieve the stored Webmentions for a given URL.

Parameters:

• resource – The URL of the resource associated to the Webmentions

• direction – The direction of the Webmentions (inbound or outbound)

Returns:

A list of Webmentions

abstract store_webmention(mention: Webmention) → Any

Store a Webmention.

Parameters:

mention – The Webmention to store