Skip to content

Message

messageformat2.format_message(msg, inputs=None, locale=None, *, formatters=None, selectors=None)

Format a message.

Use this function if you only need to format a message once.

Examples:

>>> message = Message("Hello, {$name}!")
>>> message.format({"name": "Alice"})
'Hello, Alice!'
>>> message = Message('''\
... .match {$count :integer}
... one {{You have one notification}}
... *   {{You have {$count} notifications}}''')
>>> message.format({"count": 3}, "en")
'You have 3 notifications'

Parameters:

Name Type Description Default
msg str

The message to format.

 required
locale Locale | str | None

The locale in which to format the message. Defaults to the system locale.

 None
inputs dict[str, Any] | None

Input variables referenced by the message.

 None
formatters dict[str, Formatter] | None

Additional formatters.

 None
selectors dict[str, Selector] | None

Additional selectors.

 None

Returns:

Type Description
str

The formatted message.

Raises:

Type Description
ParseError

If the message contains a syntax error.
DataModelError

If the message contains a semantic error.
FormatError

If the message cannot be formatted.
Source code in messageformat2/message.py 
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
def format_message(
    msg: str,
    inputs: dict[str, Any] | None = None,
    locale: Locale | str | None = None,
    *,
    formatters: dict[str, Formatter] | None = None,
    selectors: dict[str, Selector] | None = None,
) -> str:
    """Format a message.

    Use this function if you only need to format a message once.

    Examples:
        >>> message = Message("Hello, {$name}!")
        >>> message.format({"name": "Alice"})
        'Hello, Alice!'
        >>> message = Message('''\\
        ... .match {$count :integer}
        ... one {{You have one notification}}
        ... *   {{You have {$count} notifications}}''')
        >>> message.format({"count": 3}, "en")
        'You have 3 notifications'

    Args:
        msg: The message to format.
        locale: The locale in which to format the message. Defaults to the system locale.
        inputs: Input variables referenced by the message.
        formatters: Additional formatters.
        selectors: Additional selectors.

    Returns:
        The formatted message.

    Raises:
        ParseError: If the message contains a syntax error.
        DataModelError: If the message contains a semantic error.
        FormatError: If the message cannot be formatted.
    """
    return Message(msg).format(inputs, locale, formatters=formatters, selectors=selectors)

messageformat2.Message

Source code in messageformat2/message.py 
 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
class Message:
    def __init__(self, msg: str):
        """Create a new Message object that can be formatted.

        Use this class if you need to format the same message multiple times as
        the message is only parsed once.

        Args:
            msg: The message.

        Raises:
            ParseError: If the message contains a syntax error.
            DataModelError: If the message contains a semantic error.
        """
        self.msg = msg
        self._ast = parse(msg)

    def format(
        self,
        inputs: dict[str, Any] | None = None,
        locale: Locale | str | None = None,
        *,
        formatters: dict[str, Formatter] | None = None,
        selectors: dict[str, Selector] | None = None,
    ) -> str:
        """Format the message.

        Examples:
            >>> message = Message("Hello, {$name}!")
            >>> message.format({"name": "Alice"})
            'Hello, Alice!'
            >>> message = Message('''\\
            ... .match {$count :integer}
            ... one {{You have one notification}}
            ... *   {{You have {$count} notifications}}''')
            >>> message.format({"count": 3}, "en")
            'You have 3 notifications'

        Args:
            locale: The locale in which to format the message. Defaults to the system locale.
            inputs: Input variables referenced by the message.
            formatters: Additional formatters.
            selectors: Additional selectors.

        Returns:
            The formatted message.

        Raises:
            FormatError: If the message cannot be formatted.
        """
        if locale is None:
            locale = Locale.default()
        elif not isinstance(locale, Locale):
            locale = Locale.parse(locale)
        if inputs is None:
            inputs = {}
        registry = (
            default_registry
            if not formatters and not selectors
            else default_registry.extend(formatters=formatters, selectors=selectors)
        )
        return _format_message(self._ast, locale, inputs, registry)

    @property
    def datamodel(self) -> Node:
        """Return the data model representation of the message.

        Examples:
            >>> message = Message("Hello, {$name}!")
            >>> message.datamodel # doctest: +ELLIPSIS
            PatternMessage(..., pattern=['Hello, ', VariableExpression(arg=VariableRef(name='name'), ...), '!'])
        """
        return self._ast

    def __repr__(self) -> str:
        return f"Message({self.msg})"

__init__(msg)

Create a new Message object that can be formatted.

Use this class if you need to format the same message multiple times as the message is only parsed once.

Parameters:

Name Type Description Default
msg str

The message.

 required

Raises:

Type Description
ParseError

If the message contains a syntax error.
DataModelError

If the message contains a semantic error.
Source code in messageformat2/message.py 
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
def __init__(self, msg: str):
    """Create a new Message object that can be formatted.

    Use this class if you need to format the same message multiple times as
    the message is only parsed once.

    Args:
        msg: The message.

    Raises:
        ParseError: If the message contains a syntax error.
        DataModelError: If the message contains a semantic error.
    """
    self.msg = msg
    self._ast = parse(msg)

format(inputs=None, locale=None, *, formatters=None, selectors=None)

Format the message.

Examples:

>>> message = Message("Hello, {$name}!")
>>> message.format({"name": "Alice"})
'Hello, Alice!'
>>> message = Message('''\
... .match {$count :integer}
... one {{You have one notification}}
... *   {{You have {$count} notifications}}''')
>>> message.format({"count": 3}, "en")
'You have 3 notifications'

Parameters:

Name Type Description Default
locale Locale | str | None

The locale in which to format the message. Defaults to the system locale.

 None
inputs dict[str, Any] | None

Input variables referenced by the message.

 None
formatters dict[str, Formatter] | None

Additional formatters.

 None
selectors dict[str, Selector] | None

Additional selectors.

 None

Returns:

Type Description
str

The formatted message.

Raises:

Type Description
FormatError

If the message cannot be formatted.
Source code in messageformat2/message.py 
 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
def format(
    self,
    inputs: dict[str, Any] | None = None,
    locale: Locale | str | None = None,
    *,
    formatters: dict[str, Formatter] | None = None,
    selectors: dict[str, Selector] | None = None,
) -> str:
    """Format the message.

    Examples:
        >>> message = Message("Hello, {$name}!")
        >>> message.format({"name": "Alice"})
        'Hello, Alice!'
        >>> message = Message('''\\
        ... .match {$count :integer}
        ... one {{You have one notification}}
        ... *   {{You have {$count} notifications}}''')
        >>> message.format({"count": 3}, "en")
        'You have 3 notifications'

    Args:
        locale: The locale in which to format the message. Defaults to the system locale.
        inputs: Input variables referenced by the message.
        formatters: Additional formatters.
        selectors: Additional selectors.

    Returns:
        The formatted message.

    Raises:
        FormatError: If the message cannot be formatted.
    """
    if locale is None:
        locale = Locale.default()
    elif not isinstance(locale, Locale):
        locale = Locale.parse(locale)
    if inputs is None:
        inputs = {}
    registry = (
        default_registry
        if not formatters and not selectors
        else default_registry.extend(formatters=formatters, selectors=selectors)
    )
    return _format_message(self._ast, locale, inputs, registry)

datamodel property

Return the data model representation of the message.

Examples:

>>> message = Message("Hello, {$name}!")
>>> message.datamodel
PatternMessage(..., pattern=['Hello, ', VariableExpression(arg=VariableRef(name='name'), ...), '!'])