1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
# Copyright (c) 2022 Tulir Asokan
#
# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
from __future__ import annotations
from typing import Sequence
from abc import ABC, abstractmethod
from enum import Enum, auto
class EntityType(Enum):
"""EntityType is a Matrix formatting entity type."""
BOLD = auto()
ITALIC = auto()
STRIKETHROUGH = auto()
UNDERLINE = auto()
URL = auto()
EMAIL = auto()
USER_MENTION = auto()
ROOM_MENTION = auto()
PREFORMATTED = auto()
INLINE_CODE = auto()
BLOCKQUOTE = auto()
HEADER = auto()
COLOR = auto()
SPOILER = auto()
class FormattedString(ABC):
"""FormattedString is an abstract HTML parsing target."""
@abstractmethod
def append(self, *args: str | FormattedString) -> FormattedString:
"""
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.
Args:
*args: The strings to append.
Returns:
A FormattedString that is a concatenation of this string and the given strings.
"""
pass
@abstractmethod
def prepend(self, *args: str | FormattedString) -> FormattedString:
"""
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.
Args:
*args: The strings to prepend.
Returns:
A FormattedString that is a concatenation of the given strings and this string.
"""
pass
@abstractmethod
def format(self, entity_type: EntityType, **kwargs) -> FormattedString:
"""
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.
Args:
entity_type: 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.
"""
pass
@abstractmethod
def trim(self) -> FormattedString:
"""
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.
"""
pass
@abstractmethod
def split(self, separator, max_items: int = -1) -> list[FormattedString]:
"""
Split this FormattedString by the given separator.
Args:
separator: The separator to split by.
max_items: 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.
"""
pass
@classmethod
def concat(cls, *args: str | FormattedString) -> FormattedString:
"""
Concatenate many FormattedStrings.
Args:
*args: The strings to concatenate.
Returns:
A FormattedString that is a concatenation of the given strings.
"""
return cls.join(items=args, separator="")
@classmethod
@abstractmethod
def join(cls, items: Sequence[str | FormattedString], separator: str = " ") -> FormattedString:
"""
Join a list of FormattedStrings with the given separator.
Args:
items: The strings to join.
separator: The separator to join them with.
Returns:
A FormattedString that is a combination of the given strings with the given separator
between each one.
"""
pass
|
