formatter

class mautrix.util.formatter.AbstractEntity

Bases: ABC

__init__(type, offset, length, extra_info)

Parameters:

type (EntityType)
offset (int)
length (int)
extra_info (dict[str, Any])

Return type:

None

abstractmethod adjust_offset(offset, max_length=-1)

Parameters:

offset (int)
max_length (int)

Return type:

AbstractEntity | None

abstractmethod copy()

Return type:: AbstractEntity

class mautrix.util.formatter.EntityString

Bases: Generic[TEntity, TEntityType], FormattedString

__init__(text='', entities=None)

Parameters:

text (str)
entities (list[TEntity])

Return type:

None

append(*args)

Append strings to this FormattedString.

This method may mutate the source object, but it is not required to do so. Make sure to always use the return value when mutating and to duplicate strings if you don’t want the original to change.

Parameters:: *args (str | FormattedString) – The strings to append.
Returns:: A FormattedString that is a concatenation of this string and the given strings.
Return type:: EntityString

property entities: list[TEntity]

entity_class: alias of SimpleEntity

format(entity_type, offset=None, length=None, **kwargs)

Apply formatting to this FormattedString.

This method may mutate the source object, but it is not required to do so. Make sure to always use the return value when mutating and to duplicate strings if you don’t want the original to change.

Parameters:

entity_type (TEntityType) – The type of formatting to apply to this string.
**kwargs – Additional metadata required by the formatting type.
offset (int)
length (int)

Returns:

A FormattedString with the given formatting applied.

Return type:

EntityString

classmethod join(items, separator=' ')

Join a list of FormattedStrings with the given separator.

Parameters:

items (Sequence[str | EntityString]) – The strings to join.
separator (str) – The separator to join them with.

Returns:

A FormattedString that is a combination of the given strings with the given separator between each one.

Return type:

EntityString

prepend(*args)

Prepend strings to this FormattedString.

This method may mutate the source object, but it is not required to do so. Make sure to always use the return value when mutating and to duplicate strings if you don’t want the original to change.

Parameters:: *args (str | FormattedString) – The strings to prepend.
Returns:: A FormattedString that is a concatenation of the given strings and this string.
Return type:: EntityString

split(separator, max_items=-1)

Split this FormattedString by the given separator.

Parameters:

separator – The separator to split by.
max_items (int) – The maximum number of items to return. If the limit is reached, the remaining string will be returned as one even if it contains the separator.

Returns:

The split strings.

Return type:

list[EntityString]

trim()

Trim surrounding whitespace from this FormattedString.

This method may mutate the source object, but it is not required to do so. Make sure to always use the return value when mutating and to duplicate strings if you don’t want the original to change.

Returns:: A FormattedString without surrounding whitespace.
Return type:: EntityString

text: str

class mautrix.util.formatter.SemiAbstractEntity

Bases: AbstractEntity, ABC

adjust_offset(offset, max_length=-1)

Parameters:

offset (int)
max_length (int)

Return type:

SemiAbstractEntity | None

offset: int

length: int

class mautrix.util.formatter.SimpleEntity

Bases: SemiAbstractEntity

__init__(type, offset, length, extra_info=NOTHING)

Method generated by attrs for class SimpleEntity.

Parameters:

type (EntityType)
offset (int)
length (int)
extra_info (dict[str, Any])

Return type:

None

copy()

Return type:: SimpleEntity

type: EntityType

offset: int

length: int

extra_info: dict[str, Any]

class mautrix.util.formatter.EntityType

Bases: Enum

EntityType is a Matrix formatting entity type.

BOLD = 1

ITALIC = 2

STRIKETHROUGH = 3

UNDERLINE = 4

URL = 5

EMAIL = 6

USER_MENTION = 7

ROOM_MENTION = 8

PREFORMATTED = 9

INLINE_CODE = 10

BLOCKQUOTE = 11

HEADER = 12

COLOR = 13

SPOILER = 14

class mautrix.util.formatter.FormattedString

Bases: ABC

FormattedString is an abstract HTML parsing target.

abstractmethod append(*args)

Append strings to this FormattedString.

This method may mutate the source object, but it is not required to do so. Make sure to always use the return value when mutating and to duplicate strings if you don’t want the original to change.

Parameters:: *args (str | FormattedString) – The strings to append.
Returns:: A FormattedString that is a concatenation of this string and the given strings.
Return type:: FormattedString

classmethod concat(*args)

Concatenate many FormattedStrings.

Parameters:: *args (str | FormattedString) – The strings to concatenate.
Returns:: A FormattedString that is a concatenation of the given strings.
Return type:: FormattedString

abstractmethod format(entity_type, **kwargs)

Apply formatting to this FormattedString.

This method may mutate the source object, but it is not required to do so. Make sure to always use the return value when mutating and to duplicate strings if you don’t want the original to change.

Parameters:

entity_type (EntityType) – The type of formatting to apply to this string.
**kwargs – Additional metadata required by the formatting type.

Returns:

A FormattedString with the given formatting applied.

Return type:

FormattedString

abstractmethod classmethod join(items, separator=' ')

Join a list of FormattedStrings with the given separator.

Parameters:

items (Sequence[str | FormattedString]) – The strings to join.
separator (str) – The separator to join them with.

Returns:

A FormattedString that is a combination of the given strings with the given separator between each one.

Return type:

FormattedString

abstractmethod prepend(*args)

Prepend strings to this FormattedString.

This method may mutate the source object, but it is not required to do so. Make sure to always use the return value when mutating and to duplicate strings if you don’t want the original to change.

Parameters:: *args (str | FormattedString) – The strings to prepend.
Returns:: A FormattedString that is a concatenation of the given strings and this string.
Return type:: FormattedString

abstractmethod split(separator, max_items=-1)

Split this FormattedString by the given separator.

Parameters:

separator – The separator to split by.
max_items (int) – The maximum number of items to return. If the limit is reached, the remaining string will be returned as one even if it contains the separator.

Returns:

The split strings.

Return type:

list[FormattedString]

abstractmethod trim()

Trim surrounding whitespace from this FormattedString.

This method may mutate the source object, but it is not required to do so. Make sure to always use the return value when mutating and to duplicate strings if you don’t want the original to change.

Returns:: A FormattedString without surrounding whitespace.
Return type:: FormattedString

class mautrix.util.formatter.HTMLNode

Bases: list

__init__(tag, attrs)

Parameters:

tag (str)
attrs (list[tuple[str, str]])

Return type:

None

tag: str

text: str

tail: str

attrib: dict[str, str]

mautrix.util.formatter.read_html(data)

Parameters:: data (str)
Return type:: HTMLNode

class mautrix.util.formatter.MarkdownString

Bases: FormattedString

__init__(text='')

Parameters:: text (str)
Return type:: None

append(*args)

Append strings to this FormattedString.

This method may mutate the source object, but it is not required to do so. Make sure to always use the return value when mutating and to duplicate strings if you don’t want the original to change.

Parameters:: *args (str | FormattedString) – The strings to append.
Returns:: A FormattedString that is a concatenation of this string and the given strings.
Return type:: MarkdownString

format(entity_type, **kwargs)

Apply formatting to this FormattedString.

This method may mutate the source object, but it is not required to do so. Make sure to always use the return value when mutating and to duplicate strings if you don’t want the original to change.

Parameters:

entity_type (EntityType) – The type of formatting to apply to this string.
**kwargs – Additional metadata required by the formatting type.

Returns:

A FormattedString with the given formatting applied.

Return type:

MarkdownString

classmethod join(items, separator=' ')

Join a list of FormattedStrings with the given separator.

Parameters:

items (Sequence[str | FormattedString]) – The strings to join.
separator (str) – The separator to join them with.

Returns:

A FormattedString that is a combination of the given strings with the given separator between each one.

Return type:

MarkdownString

prepend(*args)

Prepend strings to this FormattedString.

This method may mutate the source object, but it is not required to do so. Make sure to always use the return value when mutating and to duplicate strings if you don’t want the original to change.

Parameters:: *args (str | FormattedString) – The strings to prepend.
Returns:: A FormattedString that is a concatenation of the given strings and this string.
Return type:: MarkdownString

split(separator, max_items=-1)

Split this FormattedString by the given separator.

Parameters:

separator – The separator to split by.
max_items (int) – The maximum number of items to return. If the limit is reached, the remaining string will be returned as one even if it contains the separator.

Returns:

The split strings.

Return type:

List[MarkdownString]

trim()

Trim surrounding whitespace from this FormattedString.

This method may mutate the source object, but it is not required to do so. Make sure to always use the return value when mutating and to duplicate strings if you don’t want the original to change.

Returns:: A FormattedString without surrounding whitespace.
Return type:: MarkdownString

text: str

class mautrix.util.formatter.MatrixParser

Bases: Generic[T]

async basic_format_to_fstring(node, ctx)

Parameters:

node (HTMLNode)
ctx (RecursionContext)

Return type:

T

block_tags: tuple[str, ...] = ('p', 'pre', 'blockquote', 'ol', 'ul', 'li', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'div', 'hr', 'table')

async blockquote_to_fstring(node, ctx)

Parameters:

node (HTMLNode)
ctx (RecursionContext)

Return type:

T

async color_to_fstring(msg, color)

Parameters:

msg (T)
color (str)

Return type:

T

async custom_node_to_fstring(node, ctx)

Parameters:

node (HTMLNode)
ctx (RecursionContext)

Return type:

T | None

e: alias of EntityType

async event_link_to_fstring(msg, room, event_id)

Parameters:

msg (T)
room (RoomID | RoomAlias)
event_id (EventID)

Return type:

T | None

exclude_plaintext_attrib: str = 'data-mautrix-exclude-plaintext'

fs: alias of MarkdownString

async header_to_fstring(node, ctx)

Parameters:

node (HTMLNode)
ctx (RecursionContext)

Return type:

T

async hr_to_fstring(node, ctx)

Parameters:

node (HTMLNode)
ctx (RecursionContext)

Return type:

T

ignore_less_relevant_links: bool = True

async img_to_fstring(node, ctx)

Parameters:

node (HTMLNode)
ctx (RecursionContext)

Return type:

T

async link_to_fstring(node, ctx)

Parameters:

node (HTMLNode)
ctx (RecursionContext)

Return type:

T

list_bullet(depth)

Parameters:: depth (int)
Return type:: str

list_bullets: tuple[str, ...] = ('●', '○', '■', '‣')

async list_to_fstring(node, ctx)

Parameters:

node (HTMLNode)
ctx (RecursionContext)

Return type:

T

async node_to_fstring(node, ctx)

Parameters:

node (HTMLNode)
ctx (RecursionContext)

Return type:

T

async node_to_fstrings(node, ctx)

Parameters:

node (HTMLNode)
ctx (RecursionContext)

Return type:

list[T]

async node_to_tagged_fstrings(node, ctx)

Parameters:

node (HTMLNode)
ctx (RecursionContext)

Return type:

list[tuple[T, str]]

async parse(data)

Parameters:: data (str)
Return type:: T

async parse_node(node, ctx)

Parameters:

node (HTMLNode)
ctx (RecursionContext)

Return type:

T

static read_html(data)

Parameters:: data (str)
Return type:: HTMLNode

async room_id_link_to_fstring(msg, room_id)

Parameters:

msg (T)
room_id (RoomID)

Return type:

T | None

async room_pill_to_fstring(msg, room_alias)

Parameters:

msg (T)
room_alias (RoomAlias)

Return type:

T | None

async spoiler_to_fstring(msg, reason)

Parameters:

msg (T)
reason (str)

Return type:

T

async tag_aware_parse_node(node, ctx)

Parameters:

node (HTMLNode)
ctx (RecursionContext)

Return type:

T

async text_to_fstring(text, ctx, strip_leading_whitespace=False)

Parameters:

text (str)
ctx (RecursionContext)
strip_leading_whitespace (bool)

Return type:

T

async url_to_fstring(msg, url)

Parameters:

msg (T)
url (str)

Return type:

T | None

async user_pill_to_fstring(msg, user_id)

Parameters:

msg (T)
user_id (UserID)

Return type:

T | None

class mautrix.util.formatter.RecursionContext

Bases: object

__init__(preserve_whitespace=False, ul_depth=0)

Parameters:

preserve_whitespace (bool)
ul_depth (int)

Return type:

None

enter_code_block()

Return type:: RecursionContext

enter_list()

Return type:: RecursionContext

preserve_whitespace: bool

ul_depth: int

async mautrix.util.formatter.parse_html(input_html)

Parameters:: input_html (str)
Return type:: str