Skip to content

partial_tokens

Implementation of partial tokens.

A partial token is a callable that wraps text with a given string. It can also be used with pipe operators to allow composition with other tokens.

To create your own partial tokens, use the create_partial_token function.

InvalidPartialTokenCompositionError

Bases: Exception

Raised when a partial token is constructed in an invalid way.

Source code in src/pymarkdown_builder/partial_tokens.py 
13
14
class InvalidPartialTokenCompositionError(Exception):
    """Raised when a partial token is constructed in an invalid way."""

PartialToken

Partial token representation.

A partial token is a callable that wraps text with a given string. It can also be used with pipe operators to allow composition with other tokens.

Examples:

>>> bold = PartialToken("**")
>>> italic = PartialToken("_")
>>> bold | "hello" | italic | "world" | italic | bold
'**hello_world_**'
Source code in src/pymarkdown_builder/partial_tokens.py 
 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
class PartialToken:
    """Partial token representation.

    A partial token is a callable that wraps text with a given string.
        It can also be used with pipe operators to allow composition with other tokens.

    Examples:
        >>> bold = PartialToken("**")
        >>> italic = PartialToken("_")
        >>> bold | "hello" | italic | "world" | italic | bold
        '**hello_world_**'
    """

    open_tag: str
    """String that will be prepended to the text."""
    close_tag: str
    """String that will be appended to the text."""

    def __init__(
        self,
        open_tag: str,
        close_tag: Optional[str] = None,
    ) -> None:
        """Initializes the partial token.

        Args:
            open_tag (str): The string that will be prepended to the text.
            close_tag (Optional[str]): The string that will be appended to the text. If not provided, will use the `open_tag` value.
        """  # noqa: E501
        close_tag = close_tag or open_tag

        self.open_tag = open_tag
        self.close_tag = close_tag

    def __call__(self, text: str) -> str:
        """Wraps the text with the tags."""
        return f"{self.open_tag}{text}{self.close_tag}"

    def __or__(self, value: "str | PartialToken") -> PartialTokenContent:
        """Executed when on the **left** side of the pipe operator, **opening** the tag.

        The right side of the pipe operator can be either a `#!python str` or a
            [`PartialToken`][pymarkdown_builder.partial_tokens.PartialToken].
            Always returns a [`PartialTokenContent`][pymarkdown_builder.partial_tokens.PartialTokenContent].
        """  # noqa: E501
        if isinstance(value, PartialToken):
            return PartialTokenContent(self.open_tag + value.open_tag)

        if isinstance(value, str):
            return PartialTokenContent(self.open_tag + value)

    def __ror__(self, value: PartialTokenContent) -> PartialTokenContent:
        """Executed when on the **right** side of the pipe operator, **closing** the tag.

        The left side of the pipe operator must be a
            [`PartialTokenContent`][pymarkdown_builder.partial_tokens.PartialTokenContent].
            Always returns a [`PartialTokenContent`][pymarkdown_builder.partial_tokens.PartialTokenContent].
        """  # noqa: E501
        if isinstance(value, PartialTokenContent):
            return PartialTokenContent(value + self.close_tag)

        raise InvalidPartialTokenCompositionError()

close_tag: str = close_tag instance-attribute

String that will be appended to the text.

open_tag: str = open_tag instance-attribute

String that will be prepended to the text.

__call__(text)

Wraps the text with the tags.

Source code in src/pymarkdown_builder/partial_tokens.py 
85
86
87
def __call__(self, text: str) -> str:
    """Wraps the text with the tags."""
    return f"{self.open_tag}{text}{self.close_tag}"

__init__(open_tag, close_tag=None)

Initializes the partial token.

Parameters:

Name Type Description Default
open_tag str

The string that will be prepended to the text.

 required
close_tag Optional[str]

The string that will be appended to the text. If not provided, will use the open_tag value.

 None
Source code in src/pymarkdown_builder/partial_tokens.py 
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def __init__(
    self,
    open_tag: str,
    close_tag: Optional[str] = None,
) -> None:
    """Initializes the partial token.

    Args:
        open_tag (str): The string that will be prepended to the text.
        close_tag (Optional[str]): The string that will be appended to the text. If not provided, will use the `open_tag` value.
    """  # noqa: E501
    close_tag = close_tag or open_tag

    self.open_tag = open_tag
    self.close_tag = close_tag

__or__(value)

Executed when on the left side of the pipe operator, opening the tag.

The right side of the pipe operator can be either a str or a PartialToken. Always returns a PartialTokenContent.

Source code in src/pymarkdown_builder/partial_tokens.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def __or__(self, value: "str | PartialToken") -> PartialTokenContent:
    """Executed when on the **left** side of the pipe operator, **opening** the tag.

    The right side of the pipe operator can be either a `#!python str` or a
        [`PartialToken`][pymarkdown_builder.partial_tokens.PartialToken].
        Always returns a [`PartialTokenContent`][pymarkdown_builder.partial_tokens.PartialTokenContent].
    """  # noqa: E501
    if isinstance(value, PartialToken):
        return PartialTokenContent(self.open_tag + value.open_tag)

    if isinstance(value, str):
        return PartialTokenContent(self.open_tag + value)

__ror__(value)

Executed when on the right side of the pipe operator, closing the tag.

The left side of the pipe operator must be a PartialTokenContent. Always returns a PartialTokenContent.

Source code in src/pymarkdown_builder/partial_tokens.py 
102
103
104
105
106
107
108
109
110
111
112
def __ror__(self, value: PartialTokenContent) -> PartialTokenContent:
    """Executed when on the **right** side of the pipe operator, **closing** the tag.

    The left side of the pipe operator must be a
        [`PartialTokenContent`][pymarkdown_builder.partial_tokens.PartialTokenContent].
        Always returns a [`PartialTokenContent`][pymarkdown_builder.partial_tokens.PartialTokenContent].
    """  # noqa: E501
    if isinstance(value, PartialTokenContent):
        return PartialTokenContent(value + self.close_tag)

    raise InvalidPartialTokenCompositionError()

PartialTokenContent

Bases: str

An "overloaded" string to support pipe operations with PartialToken.

Source code in src/pymarkdown_builder/partial_tokens.py 
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
class PartialTokenContent(str):
    """An "overloaded" string to support pipe operations with [`PartialToken`][pymarkdown_builder.partial_tokens.PartialToken]."""  # noqa: E501

    def __new__(cls, string: str):
        """Creates a new partial token content."""
        return super().__new__(cls, string)

    def __or__(self, value: "str | PartialToken") -> "PartialTokenContent":
        """Executed when on the **left** side of the pipe operator.

        The right side of the pipe operator can be either a `#!python str` or a
            [`PartialToken`][pymarkdown_builder.partial_tokens.PartialToken].
            Always returns a [`PartialToken`][pymarkdown_builder.partial_tokens.PartialToken].
        """  # noqa: E501
        if isinstance(value, str):
            return PartialTokenContent(self + value)

        if isinstance(value, PartialToken):
            return PartialTokenContent(self + value.close_tag)

    def __ror__(self, value: "str | PartialToken") -> "PartialTokenContent":
        """Executed when on the **right** side of the pipe operator.

        The left side of the pipe operator can be either a `#!python str` or a
            [`PartialToken`][pymarkdown_builder.partial_tokens.PartialToken].
            Always returns a [`PartialToken`][pymarkdown_builder.partial_tokens.PartialToken].
        """  # noqa: E501
        if isinstance(value, str):
            return PartialTokenContent(value + self)

        if isinstance(value, PartialToken):
            return PartialTokenContent(value.close_tag + self)

__new__(string)

Creates a new partial token content.

Source code in src/pymarkdown_builder/partial_tokens.py 
20
21
22
def __new__(cls, string: str):
    """Creates a new partial token content."""
    return super().__new__(cls, string)

__or__(value)

Executed when on the left side of the pipe operator.

The right side of the pipe operator can be either a str or a PartialToken. Always returns a PartialToken.

Source code in src/pymarkdown_builder/partial_tokens.py 
24
25
26
27
28
29
30
31
32
33
34
35
def __or__(self, value: "str | PartialToken") -> "PartialTokenContent":
    """Executed when on the **left** side of the pipe operator.

    The right side of the pipe operator can be either a `#!python str` or a
        [`PartialToken`][pymarkdown_builder.partial_tokens.PartialToken].
        Always returns a [`PartialToken`][pymarkdown_builder.partial_tokens.PartialToken].
    """  # noqa: E501
    if isinstance(value, str):
        return PartialTokenContent(self + value)

    if isinstance(value, PartialToken):
        return PartialTokenContent(self + value.close_tag)

__ror__(value)

Executed when on the right side of the pipe operator.

The left side of the pipe operator can be either a str or a PartialToken. Always returns a PartialToken.

Source code in src/pymarkdown_builder/partial_tokens.py 
37
38
39
40
41
42
43
44
45
46
47
48
def __ror__(self, value: "str | PartialToken") -> "PartialTokenContent":
    """Executed when on the **right** side of the pipe operator.

    The left side of the pipe operator can be either a `#!python str` or a
        [`PartialToken`][pymarkdown_builder.partial_tokens.PartialToken].
        Always returns a [`PartialToken`][pymarkdown_builder.partial_tokens.PartialToken].
    """  # noqa: E501
    if isinstance(value, str):
        return PartialTokenContent(value + self)

    if isinstance(value, PartialToken):
        return PartialTokenContent(value.close_tag + self)

create_partial_token(open_tag, close_tag=None)

Creates a partial token.

Parameters:

Name Type Description Default
open_tag str

The string that will be prepended to the text.

 required
close_tag Optional[str]

The string that will be appended to the text. If not provided, will use the open_tag value.

 None
Source code in src/pymarkdown_builder/partial_tokens.py 
115
116
117
118
119
120
121
122
123
124
125
def create_partial_token(
    open_tag: str,
    close_tag: Optional[str] = None,
):
    """Creates a partial token.

    Args:
        open_tag (str): The string that will be prepended to the text.
        close_tag (Optional[str]): The string that will be appended to the text. If not provided, will use the `open_tag` value.
    """  # noqa: E501
    return PartialToken(open_tag, close_tag)