messageformat2 0.1.1__tar.gz → 1.0.0__tar.gz

{messageformat2-0.1.1 → messageformat2-1.0.0}/.github/workflows/ci.yml

@@ -11,10 +11,10 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.12", "3.13", "3.14"]
+        python-version: ["3.12", "3.13", "3.14", "3.15"]
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7.0.1
 
       - name: Install the latest version of uv and set the python version
         uses: astral-sh/setup-uv@v7
@@ -23,7 +23,11 @@ jobs:
 
       - name: Lint code 🧹
         run: |
-          uv run ruff check tests/ messageformat2/ --exclude messageformat2/cli.py
+          uv run ruff check tests/ messageformat2/
+
+      - name: Format code 📃
+        run: |
+          uv run ruff format --check --output-format=github messageformat2/ tests/
 
       - name: Type check 🏷
         run: |

{messageformat2-0.1.1 → messageformat2-1.0.0}/.github/workflows/release.yml

@@ -17,7 +17,7 @@ jobs:
       id-token: write
 
     steps:
-    - uses: actions/checkout@v6
+    - uses: actions/checkout@v7.0.1
 
     - name: Install the latest version of uv and set the python version
       uses: astral-sh/setup-uv@v7

{messageformat2-0.1.1 → messageformat2-1.0.0}/.readthedocs.yaml

@@ -6,14 +6,16 @@ version: 2
 
 # Set the version of Python and other tools you might need
 build:
-  os: ubuntu-22.04
+  os: ubuntu-26.04
   tools:
-    python: "3.12"
-  jobs:
-    post_create_environment:
-      - pip install uv
-    post_install:
-      - uv sync --group docs
+    python: "3.14"
+
+python:
+  install:
+    - method: uv
+      command: sync
+      groups:
+        - docs
 
 mkdocs:
   configuration: mkdocs.yml

{messageformat2-0.1.1 → messageformat2-1.0.0}/PKG-INFO

@@ -1,9 +1,10 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: messageformat2
-Version: 0.1.1
+Version: 1.0.0
 Summary: Python implementation of Unicode MessageFormat 2.0
 Project-URL: Homepage, https://github.com/tomasr8/messageformat2
 Project-URL: Github, https://github.com/tomasr8/messageformat2
+Project-URL: Documentation, https://messageformat2.readthedocs.io/en/latest/
 Author-email: Tomas Roun <tomas.roun8@gmail.com>
 License: MIT License
         
@@ -28,16 +29,17 @@ License: MIT License
         SOFTWARE.
 License-File: LICENSE
 Keywords: cldr,gettext,i18n,internationalization,localization,messageformat,messageformat 2
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Topic :: Software Development :: Internationalization
 Classifier: Topic :: Software Development :: Localization
 Requires-Python: >=3.12
-Requires-Dist: babel==2.17.0
-Requires-Dist: click==8.3.1
+Requires-Dist: babel>=2
+Requires-Dist: click>=8
 Description-Content-Type: text/markdown
 
 
@@ -45,14 +47,14 @@ Description-Content-Type: text/markdown
 # MessageFormat2 [![Documentation Status](https://readthedocs.org/projects/messageformat2/badge/?version=latest)](https://messageformat2.readthedocs.io/en/latest/?badge=latest) [![CI](https://github.com/tomasr8/messageformat2/workflows/CI/badge.svg)](https://github.com/tomasr8/messageformat2/workflows/CI/badge.svg)
 
 This is a Python implementation of the [Unicode Message Format 2.0
-specification](https://www.unicode.org/reports/tr35/tr35-72/tr35-messageFormat.html).
+specification](https://www.unicode.org/reports/tr35/tr35-messageFormat.html).
 
 Message Format 2.0 (MF2) is a new iteration of Message Format which aims to be
 more expressive and flexible than both Message Format 1.0 and, in the context of
 Python, gettext.
 
 If you would like to learn more about MF2 itself head over to the [Unicode technical
-specification](https://www.unicode.org/reports/tr35/tr35-72/tr35-messageFormat.html).
+specification](https://www.unicode.org/reports/tr35/tr35-messageFormat.html).
 
 ## Features
 
@@ -60,12 +62,14 @@ The library includes:
 
 - A message parser and a formatter
 - Several builtin formatters and selectors described by the
-  [spec](https://www.unicode.org/reports/tr35/tr35-72/tr35-messageFormat.html#function-registry)
+  [spec](https://github.com/unicode-org/message-format-wg/blob/main/spec/functions/README.md)
   and the possibility to write custom formatters/selectors
 - Helper classes to inspect and transform the message [data
-  model](https://www.unicode.org/reports/tr35/tr35-72/tr35-messageFormat.html#interchange-data-model)
+  model](https://github.com/unicode-org/message-format-wg/blob/main/spec/data-model/README.md)
 
-## [Documentation](https://messageformat2.readthedocs.io/en/latest/)
+## Documentation
+
+Documentation is available here: [https://messageformat2.readthedocs.io/en/latest/](https://messageformat2.readthedocs.io/en/latest/)
 
 ## Installation
 
@@ -119,7 +123,8 @@ MF2 supports pluralization using built-in or custom selectors.
 from messageformat2 import Message
 
 msg = Message ("""\
-.match {$count :number}
+.input {$count :number}
+.match $count
 one {{You have {$count} notification.}}
 *   {{You have {$count} notifications.}}
 """)

{messageformat2-0.1.1 → messageformat2-1.0.0}/README.md

@@ -3,14 +3,14 @@
 # MessageFormat2 [![Documentation Status](https://readthedocs.org/projects/messageformat2/badge/?version=latest)](https://messageformat2.readthedocs.io/en/latest/?badge=latest) [![CI](https://github.com/tomasr8/messageformat2/workflows/CI/badge.svg)](https://github.com/tomasr8/messageformat2/workflows/CI/badge.svg)
 
 This is a Python implementation of the [Unicode Message Format 2.0
-specification](https://www.unicode.org/reports/tr35/tr35-72/tr35-messageFormat.html).
+specification](https://www.unicode.org/reports/tr35/tr35-messageFormat.html).
 
 Message Format 2.0 (MF2) is a new iteration of Message Format which aims to be
 more expressive and flexible than both Message Format 1.0 and, in the context of
 Python, gettext.
 
 If you would like to learn more about MF2 itself head over to the [Unicode technical
-specification](https://www.unicode.org/reports/tr35/tr35-72/tr35-messageFormat.html).
+specification](https://www.unicode.org/reports/tr35/tr35-messageFormat.html).
 
 ## Features
 
@@ -18,12 +18,14 @@ The library includes:
 
 - A message parser and a formatter
 - Several builtin formatters and selectors described by the
-  [spec](https://www.unicode.org/reports/tr35/tr35-72/tr35-messageFormat.html#function-registry)
+  [spec](https://github.com/unicode-org/message-format-wg/blob/main/spec/functions/README.md)
   and the possibility to write custom formatters/selectors
 - Helper classes to inspect and transform the message [data
-  model](https://www.unicode.org/reports/tr35/tr35-72/tr35-messageFormat.html#interchange-data-model)
+  model](https://github.com/unicode-org/message-format-wg/blob/main/spec/data-model/README.md)
 
-## [Documentation](https://messageformat2.readthedocs.io/en/latest/)
+## Documentation
+
+Documentation is available here: [https://messageformat2.readthedocs.io/en/latest/](https://messageformat2.readthedocs.io/en/latest/)
 
 ## Installation
 
@@ -77,7 +79,8 @@ MF2 supports pluralization using built-in or custom selectors.
 from messageformat2 import Message
 
 msg = Message ("""\
-.match {$count :number}
+.input {$count :number}
+.match $count
 one {{You have {$count} notification.}}
 *   {{You have {$count} notifications.}}
 """)

messageformat2-1.0.0/docs/builtins.md

@@ -0,0 +1,142 @@
+The default function registry includes these functions
+
+in line with the [specification](https://github.com/unicode-org/message-format-wg/tree/main/spec/functions)
+
+### `:string`
+
+#### Formatter
+
+As a formatter, this function simply calls `str(value)`.
+
+#### Selector
+
+As a selector, this function selects the exact match among the variant keys
+(after NFC normalization of the value).
+
+```python
+format_message("""\
+.input {$pet :string}
+.match $pet
+dog {{I have a dog}}
+cat {{I have a cat}}
+* {{I have a {$pet}}}
+""", {"pet": "cat"})
+# -> "I have a cat"
+```
+
+### `:number`
+
+The operand must be an `int`, `float` or `Decimal` (but not a `bool`), or a string matching the
+`number-literal` production of the spec (e.g. `|-1234.5|`, `|1e3|`; `|01|` or `|.5|` are not numbers).
+The resolved value of another numeric function (`:number`, `:integer`, `:offset`) is also accepted, in which
+case its options are inherited, with the options of the expression taking priority.
+
+#### Formatter
+
+- `signDisplay`
+    - auto (default)
+    - always
+    - exceptZero
+    - negative
+    - never
+- `useGrouping`
+    - auto (default)
+    - always
+    - never
+    - min2 (treated as auto)
+- `minimumIntegerDigits`
+- `minimumFractionDigits`
+- `maximumFractionDigits`
+- `minimumSignificantDigits`
+- `maximumSignificantDigits`
+- `numberingSystem` (implementation extension): a Unicode Number System Identifier
+
+The digit options are *digit size options*: small non-negative integers (`0`-`99`).
+Not implemented: `trailingZeroDisplay`, `roundingPriority`, `roundingIncrement`, `roundingMode` (these are ignored).
+
+#### Selector
+
+The selector takes the same options as the formatter in addition to:
+
+- `select`
+    - plural (default)
+    - ordinal
+    - exact
+
+`select` must be set by a literal. The selector first tries an exact match between the number and
+numeric keys (e.g. `1`), then (unless `select=exact`) matches the CLDR plural or ordinal category of the number
+(`zero`, `one`, `two`, `few`, `many`, `other`). Any other key is a `BadVariantKey` error.
+
+### `:integer`
+
+Same as `:number`, but the operand is truncated to an integer. The `minimumFractionDigits`, `maximumFractionDigits`
+and `minimumSignificantDigits` options of an annotated operand are discarded.
+
+### `:offset`
+
+Adds or subtracts a small integer from a numeric operand, e.g. to count "other" users:
+
+```python
+.input {$likes :integer}
+.local $others = {$likes :offset subtract=1}
+```
+
+Exactly one of the options must be given:
+
+- `add`
+- `subtract`
+
+The formatting options of an annotated operand (e.g. `signDisplay` of `{$likes :integer signDisplay=always}`)
+are inherited. `:offset` can also be used as a selector, in which case it behaves like `:number`.
+
+### `:datetime`, `:date`, `:time`
+
+The operand must be a `datetime` (or a `date`/`time` for `:date`/`:time` respectively) or an ISO 8601 date or
+datetime string that can be parsed with `datetime.fromisoformat`, e.g. `|2006-01-02|` or `|2006-01-02T15:04:06+01:00|`.
+The resolved value of another date/time function is also accepted, in which case its override options
+(`timeZone`, `hour12`) are inherited.
+
+The option values below must be set by literals (an option set by a variable is a `BadOption` error).
+
+#### `:datetime`
+
+- `dateFields`
+    - weekday
+    - day-weekday
+    - month-day
+    - month-day-weekday
+    - year-month-day (default)
+    - year-month-day-weekday
+- `dateLength`
+    - long
+    - medium (default)
+    - short
+- `timePrecision`
+    - hour
+    - minute (default)
+    - second
+- `timeZoneStyle`: no time zone is shown unless set
+    - long
+    - short
+
+#### `:date`
+
+- `fields`: same values as `dateFields` above
+- `length`: same values as `dateLength` above
+
+#### `:time`
+
+- `precision`: same values as `timePrecision` above
+- `timeZoneStyle`: same values as above
+
+#### Override options
+
+- `timeZone`: `UTC`, `input` (the time zone of the operand, which must then have one), an IANA time zone
+  name (`|Europe/Zurich|`) or an offset (`|+01:00|`). A naive `datetime` is interpreted in this time zone,
+  an aware one is converted to it.
+- `hour12`: `true` or `false` (`:datetime` and `:time` only); the default is locale-dependent.
+- `calendar`: not implemented (ignored).
+
+#### Selector
+
+The date/time functions do not support selection, as it is not required by MF2.

messageformat2-1.0.0/docs/explanation.md

@@ -0,0 +1,71 @@
+## Runtime model
+
+All expressions are lazily evaluated at the time of use.
+If the same variable is referenced more than once, it will also be evaluated more than once.
+Pay attention when providing custom formatters/selectors with side effects:
+
+```python
+counter = 0
+
+def formatter_with_side_effect(value, locale, options):
+    nonlocal counter
+    counter +=1
+    return str(value)
+
+msg = Message("\
+.local $foo = {|foo| :side_effect}
+{{{$foo} {$foo}}}
+")
+msg.format(formatters={'side_effect': formatter_with_side_effect})
+print(counter)  # -> 2
+```
+
+## Unannotated variables
+
+A placeholder consisting only of a variable (`{$x}`) is formatted according to the type of its value:
+numbers (`int`, `float`, `Decimal`) as if annotated with `:number`, `datetime`, `date` and `time` values with
+`:datetime`, `:date` and `:time`. Anything else is formatted with `str()`.
+Literals are always strings, so `{|1234.5|}` is formatted verbatim.
+
+## Function composition
+
+A variable which was annotated with a function can be annotated again, for example in a placeholder.
+The function handler then receives the resolved value of the earlier annotation
+(a `messageformat2.builtins.LazyValue` carrying the earlier function's name, operand and options) as its operand,
+and decides what to do with it. The built-in numeric functions accept each other's resolved values
+and inherit their options, with the options of the later expression taking priority:
+
+```python
+.local $x = {42 :number minimumFractionDigits=2 signDisplay=always}
+{{x = {$x :number minimumFractionDigits=1}}}  # -> "x = +42.0"
+
+.local $x = {1.25 :integer}
+{{x = {$x :number}}}  # -> "x = 1"
+```
+
+whereas e.g. `{$x :date}` would raise `BadOperand`. See [Custom formatters](howto/formatter.md) for how to
+handle such operands in your own functions.
+
+## Whitespace
+
+This library implements the [grammar](https://github.com/unicode-org/message-format-wg/blob/main/spec/message.abnf) exactly as specified which includes whitespace.
+
+Whitespace around a complex message (a message containing declarations and/or a match block) is not significant,
+so complex messages can be freely indented, e.g. in multiline strings:
+
+```python
+Message("""
+    .input {$count :integer}
+    .match $count
+    * {{count is {$count}}}
+""")
+```
+
+Whitespace in a simple message (a message consisting of a single pattern) is always significant
+and is part of the message text. Note that the first non-whitespace character of a simple message
+cannot be a `.`, so a misspelled keyword (`.imput`) is a syntax error rather than silently becoming text.
+To get a pattern which starts with a `.`, use a quoted pattern:
+
+```python
+Message("{{.input is not a keyword here}}")
+```

{messageformat2-0.1.1 → messageformat2-1.0.0}/docs/getting_started.md

@@ -48,7 +48,8 @@ MF2 supports pluralization using built-in or custom selectors.
 from messageformat2 import Message
 
 msg = Message ("""\
-.match {$count :number}
+.input {$count :number}
+.match $count
 one {{You have {$count} notification.}}
 *   {{You have {$count} notifications.}}
 """)

{messageformat2-0.1.1 → messageformat2-1.0.0}/docs/howto/datamodel.md

@@ -1,6 +1,6 @@
 The `Message` class has a `datamodel` property which gives you access to the
 message data model which is based on the [MF2
-spec](https://www.unicode.org/reports/tr35/tr35-72/tr35-messageFormat.html#interchange-data-model).
+spec](https://github.com/unicode-org/message-format-wg/blob/main/spec/data-model/README.md).
 The data model nodes are documented [here](/datamodel).
 
 There are two classes to work with the datamodel - `DataModelVisitor` &

messageformat2-1.0.0/docs/howto/errors.md

@@ -0,0 +1,72 @@
+# Error handling
+
+Errors might be raised during parsing or during formatting. You can learn more
+about MF2 errors
+[here](https://github.com/unicode-org/message-format-wg/blob/main/spec/errors.md).
+
+During parsing the following exceptions (or their subclasses) might be raised:
+
+- `messageformat2.errors.ParseError` - for syntax errors
+- `messageformat2.errors.DataModelError` - for semantic errors
+
+During formatting the following exception (or its subclasses) might be raised:
+
+- `messageformat2.errors.FormatError`
+
+## Handling parsing errors
+
+```python
+from messageformat2.message import Message
+from messageformat2.errors import ParseError, DataModelError
+
+try:
+    Message("}} invalid syntax")
+except ParseError as e:
+    print(e)  # -> Invalid syntax
+
+
+try:
+    Message("""\
+.input {$count :integer}
+.match $count
+one {{The count is {$count}}}
+""")
+except DataModelError as e:
+    print(e)  # -> Missing fallback variant
+```
+
+## Handling formatting errors
+
+```python
+from messageformat2.message import Message
+from messageformat2.errors import FormatError
+
+msg = Message("Hello, {$name}!")
+try:
+    msg.format()
+except FormatError as e:
+    print(e)  # -> Unresolved variable
+```
+
+## Formatting with fallback values
+
+By default the first formatting error is raised and no output is produced. The spec requires
+that a valid message can always be formatted, with
+[fallback values](https://github.com/unicode-org/message-format-wg/blob/main/spec/formatting.md#fallback-resolution)
+standing in for the parts that failed. Pass an `on_error` callback to get this behaviour: every error is
+passed to the callback instead of being raised, and formatting continues.
+
+```python
+from messageformat2.message import Message
+
+errors = []
+msg = Message("Hello, {$name}! You have {$count :number} messages.")
+msg.format({"count": "many"}, on_error=errors.append)
+# -> "Hello, {$name}! You have {$count} messages."
+errors
+# -> [UnresolvedVariable('Unresolved variable: name'), BadOperand("Bad operand: 'many' is not a number")]
+```
+
+The fallback value is `{$name}` for a variable, `{|literal|}` for a literal operand and `{:function}` for a
+function without an operand. An option whose value cannot be resolved is omitted, and a selector which fails
+only matches the catch-all key `*`. Syntax and data model errors are still raised by `Message()`.

messageformat2-1.0.0/docs/howto/formatter.md

@@ -0,0 +1,96 @@
+It is possible to write a custom formatter to extend the functionality of the
+library. Here's an example of a simple formatter:
+
+```python
+def capitalize(value: Any, locale, options) -> str:
+    return value.capitalize()
+
+format_message(
+    "{|foo bar| :capitalize}",
+    formatters={"capitalize": capitalize}
+)
+# -> "Foo bar"
+```
+
+A formatter function must take exactly 3 arguments:
+
+- `value`: the value passed to the formatter when formatting
+- `locale`: the current locale as a `babel.Locale` instance
+- `options`: a dictionary containing all the options passed to the formatter.
+
+The return value of this function is converted to string and displayed.
+
+Here's an example using `options`:
+
+```python
+def capitalize(value: str, locale, options) -> str:
+    if options.get('eachWord') == "yes":
+        return value.title()
+    return value.capitalize()
+
+format_message(
+    "{|foo bar| :capitalize eachWord=yes}",
+    formatters={"capitalize": capitalize}
+)
+# -> "Foo Bar"
+```
+
+Any errors during the evaluation of the formatter will be automatically caught
+and `messageformat2.errors.MessageFunctionError` will be reraised instead.
+
+```python
+from messageformat2.errors import MessageFunctionError
+
+try:
+    format_message(
+        "{foo :raise}",
+        formatters={"raise": raise_some_error}
+    )
+except MessageFunctionError as e:
+    print(e)
+```
+
+To signal a specific error, a formatter can raise one of the `MessageFunctionError` subclasses
+defined by the spec: `BadOperand` (wrong operand type or format), `BadOption` (invalid option or
+option value), `BadVariantKey` (a variant key the selector cannot interpret) or `UnsupportedOperation`.
+These are reraised as-is.
+
+If the function can produce a result despite the error (the spec often asks to "emit a Bad Option error and
+ignore the option"), pass it as `result`: when the message is formatted with an `on_error` callback
+(see [Error handling](errors.md)), the error is reported and the result is used; otherwise the error is raised.
+
+```python
+from messageformat2.errors import BadOption
+
+def shout(value, locale, options) -> str:
+    result = str(value).upper()
+    if options.get("volume", "loud") != "loud":
+        raise BadOption("volume must be loud", result=result)
+    return result
+```
+
+## Annotated operands
+
+If the operand of your formatter is a variable that was already annotated with a function,
+`value` is a `messageformat2.builtins.LazyValue` carrying the earlier function's name (`fn_name`),
+operand (`value`) and resolved options (`options`). `str(value)` gives the formatted value of the earlier annotation.
+It is up to your function to decide which operands it accepts and whether to inherit the earlier options;
+raise `BadOperand` if your function cannot use the operand.
+
+```python
+from messageformat2.builtins import LazyValue
+from messageformat2.errors import BadOperand
+
+def shout(value, locale, options) -> str:
+    if isinstance(value, LazyValue):
+        if value.fn_name != "string":
+            raise BadOperand(f"Cannot shout a :{value.fn_name}")
+        value = str(value)
+    return str(value).upper()
+
+format_message(
+    ".local $name = {alice :string} {{{$name :shout}}}",
+    formatters={"shout": shout}
+)
+# -> "ALICE"
+```

{messageformat2-0.1.1 → messageformat2-1.0.0}/docs/howto/selector.md

@@ -24,7 +24,8 @@ def integer_selector(
 
 
 format_message("""\
-.match {$count :integer select=plural}
+.input {$count :integer select=plural}
+.match $count
 1   {{You have one notification.}}
 one {{You have {$count} notification.}}
 *   {{You have {$count} notifications.}}""",
@@ -44,7 +45,8 @@ A selector function must take exactly 3 arguments:
 For example, for this message:
 
 ```python
-.match {$count :integer select=plural}
+.input {$count :integer select=plural}
+.match $count
 1   {{You have one notification.}}
 one {{You have {$count} notification.}}
 *   {{You have ???}}

{messageformat2-0.1.1 → messageformat2-1.0.0}/docs/index.md

@@ -1,13 +1,13 @@
 This site contains documentation for the `messageformat2`, a Python library
 which implements the [Unicode Message Format 2.0
-specification](https://www.unicode.org/reports/tr35/tr35-72/tr35-messageFormat.html).
+specification](https://www.unicode.org/reports/tr35/tr35-messageFormat.html).
 
 Message Format 2.0 (MF2) is a new iteration of Message Format which aims to be
 more expressive and flexible than both Message Format 1.0 and, in the context of
 Python, gettext.
 
 If you would like to learn more about MF2 itself head over to the [Unicode technical
-specification](https://www.unicode.org/reports/tr35/tr35-72/tr35-messageFormat.html).
+specification](https://www.unicode.org/reports/tr35/tr35-messageFormat.html).
 
 ## Features
 
@@ -15,10 +15,10 @@ The `messageformat2` library includes:
 
 - A message parser and a formatter
 - Several builtin formatters and selectors described by the
-  [spec](https://www.unicode.org/reports/tr35/tr35-72/tr35-messageFormat.html#function-registry)
+  [spec](https://github.com/unicode-org/message-format-wg/blob/main/spec/functions/README.md)
   and the possibility to write custom formatters/selectors
 - Helper classes to inspect and transform the message [data
-  model](https://www.unicode.org/reports/tr35/tr35-72/tr35-messageFormat.html#interchange-data-model)
+  model](https://github.com/unicode-org/message-format-wg/blob/main/spec/data-model/README.md)
 
 ### Work in progress
 

{messageformat2-0.1.1 → messageformat2-1.0.0}/messageformat2/__init__.py

@@ -1,5 +1,5 @@
 from messageformat2.message import Message, format_message
 
 
-__version__ = "0.1.1"
+__version__ = "1.0.0"
 __all__ = ["Message", "format_message"]