messageformat2 0.1.1__tar.gz → 1.1.0__tar.gz

{messageformat2-0.1.1 → messageformat2-1.1.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.1.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.1.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.1.0}/PKG-INFO

@@ -1,9 +1,10 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: messageformat2
-Version: 0.1.1
+Version: 1.1.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,42 +29,46 @@ 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
 
 
 
 # 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).
+This is a Python implementation of the [Unicode MessageFormat
+specification](https://www.unicode.org/reports/tr35/tr35-messageFormat.html) (LDML 49).
 
-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
+Unicode MessageFormat (MessageFormat 2.0, MF2) is a new iteration of MessageFormat which aims to be
+more expressive and flexible than both MessageFormat 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
 
 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)
+- A message parser and a formatter, passing the official
+  [test suite](https://github.com/unicode-org/message-format-wg/tree/main/test)
+- All default functions described by the
+  [spec](https://github.com/unicode-org/message-format-wg/blob/main/spec/functions/README.md)
+  (`:string`, `:number`, `:integer`, `:offset`, `:percent`, `:currency`, `:date`, `:time`, `:datetime`)
   and the possibility to write custom formatters/selectors
+- Formatting with fallback values and error reporting, optional bidi isolation of placeholders
 - 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/)
 
@@ -100,15 +105,18 @@ message.format({"name": "Bob"})  # -> "Hello, Bob!"
 There are several builtin locale-aware formatters available.
 
 ```python
-from datetime import datetime
+from datetime import date
 from messageformat2 import Message
 
-message = Message("Today's date is {$now :date}")
-now = datetime.now()
-message.format({"now": now}, locale='en_US')
-# -> Today's date is 5/10/2024
-message.format({"now": now}, locale='en_GB')
-# -> Today's date is 10/05/2024
+message = Message("Today's date is {$today :date}")
+today = date(2024, 5, 10)
+message.format({"today": today}, locale="en_US")
+# -> "Today's date is May 10, 2024"
+message.format({"today": today}, locale="en_GB")
+# -> "Today's date is 10 May 2024"
+
+Message("{$price :currency currency=EUR}").format({"price": 42}, locale="de")
+# -> "42,00\xa0€"
 ```
 
 ### Plural support
@@ -119,7 +127,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.}}
 """)
@@ -128,4 +137,25 @@ msg.format({"count": 42}, locale='en_US') # -> "You have 42 notifications."
 msg.format({"count": 1}, locale='en_US') # -> "You have 1 notification."
 ```
 
+### Error handling
+
+By default the first error is raised. To get the spec's fallback behaviour instead (`{$name}` for a
+missing variable, etc.) and collect the errors, pass an `on_error` callback:
+
+```python
+errors = []
+Message("Hello, {$name}!").format({}, on_error=errors.append)  # -> "Hello, {$name}!"
+errors  # -> [UnresolvedVariable('Unresolved variable: name')]
+```
+
+### Bidirectional text
+
+The spec's *Default Bidi Strategy* (wrapping placeholders in Unicode isolate controls so that mixed-direction
+text displays correctly) is available with `bidi_isolation=True`:
+
+```python
+Message("Hello, {$name}!").format({"name": "Alice"}, bidi_isolation=True)
+# -> "Hello, \u2068Alice\u2069!"
+```
+
 Complete documentation is available [here](https://messageformat2.readthedocs.io/en/latest/).

messageformat2-1.1.0/README.md

@@ -0,0 +1,117 @@
+
+
+# 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 MessageFormat
+specification](https://www.unicode.org/reports/tr35/tr35-messageFormat.html) (LDML 49).
+
+Unicode MessageFormat (MessageFormat 2.0, MF2) is a new iteration of MessageFormat which aims to be
+more expressive and flexible than both MessageFormat 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-messageFormat.html).
+
+## Features
+
+The library includes:
+
+- A message parser and a formatter, passing the official
+  [test suite](https://github.com/unicode-org/message-format-wg/tree/main/test)
+- All default functions described by the
+  [spec](https://github.com/unicode-org/message-format-wg/blob/main/spec/functions/README.md)
+  (`:string`, `:number`, `:integer`, `:offset`, `:percent`, `:currency`, `:date`, `:time`, `:datetime`)
+  and the possibility to write custom formatters/selectors
+- Formatting with fallback values and error reporting, optional bidi isolation of placeholders
+- Helper classes to inspect and transform the message [data
+  model](https://github.com/unicode-org/message-format-wg/blob/main/spec/data-model/README.md)
+
+## [Documentation](https://messageformat2.readthedocs.io/en/latest/)
+
+## Installation
+
+Via pip for Python `>= 3.12`
+
+```sh
+pip install messageformat2
+```
+
+## Examples
+
+### Simple messages
+
+```python
+from messageformat2 import format_message
+
+format_message("Hello, {$name}!", {"name": "Alice"})  # -> "Hello, Alice!"
+```
+
+Messages can be reused with different inputs.
+
+```python
+from messageformat2 import Message
+
+message = Message("Hello, {$name}!")
+message.format({"name": "Alice"})  # -> "Hello, Alice!"
+message.format({"name": "Bob"})  # -> "Hello, Bob!"
+```
+
+### Built-in formatters
+
+There are several builtin locale-aware formatters available.
+
+```python
+from datetime import date
+from messageformat2 import Message
+
+message = Message("Today's date is {$today :date}")
+today = date(2024, 5, 10)
+message.format({"today": today}, locale="en_US")
+# -> "Today's date is May 10, 2024"
+message.format({"today": today}, locale="en_GB")
+# -> "Today's date is 10 May 2024"
+
+Message("{$price :currency currency=EUR}").format({"price": 42}, locale="de")
+# -> "42,00\xa0€"
+```
+
+### Plural support
+
+MF2 supports pluralization using built-in or custom selectors.
+
+```python
+from messageformat2 import Message
+
+msg = Message ("""\
+.input {$count :number}
+.match $count
+one {{You have {$count} notification.}}
+*   {{You have {$count} notifications.}}
+""")
+
+msg.format({"count": 42}, locale='en_US') # -> "You have 42 notifications."
+msg.format({"count": 1}, locale='en_US') # -> "You have 1 notification."
+```
+
+### Error handling
+
+By default the first error is raised. To get the spec's fallback behaviour instead (`{$name}` for a
+missing variable, etc.) and collect the errors, pass an `on_error` callback:
+
+```python
+errors = []
+Message("Hello, {$name}!").format({}, on_error=errors.append)  # -> "Hello, {$name}!"
+errors  # -> [UnresolvedVariable('Unresolved variable: name')]
+```
+
+### Bidirectional text
+
+The spec's *Default Bidi Strategy* (wrapping placeholders in Unicode isolate controls so that mixed-direction
+text displays correctly) is available with `bidi_isolation=True`:
+
+```python
+Message("Hello, {$name}!").format({"name": "Alice"}, bidi_isolation=True)
+# -> "Hello, \u2068Alice\u2069!"
+```
+
+Complete documentation is available [here](https://messageformat2.readthedocs.io/en/latest/).

messageformat2-1.1.0/docs/builtins.md

@@ -0,0 +1,204 @@
+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
+from messageformat2 import format_message
+
+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`, `:percent`) 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 (grouping separators only for numbers with at least 5 integer digits)
+- `minimumIntegerDigits`
+- `minimumFractionDigits`
+- `maximumFractionDigits`
+- `minimumSignificantDigits`
+- `maximumSignificantDigits`
+- `roundingMode`
+    - ceil
+    - floor
+    - expand
+    - trunc
+    - halfCeil
+    - halfFloor
+    - halfExpand (default; ties away from zero, like `Intl.NumberFormat` and unlike Python's `round()`)
+    - halfTrunc
+    - halfEven
+- `roundingPriority`: which of the fraction and significant digits options wins when both are given
+    - auto (default; the significant digits options)
+    - morePrecision
+    - lessPrecision
+- `roundingIncrement`: 1 (default), 2, 5, 10, 20, 25, 50, 100, 200, 250, 500, 1000, 2000, 2500 or 5000,
+  in units of the last fraction digit; requires `minimumFractionDigits` and `maximumFractionDigits` to be equal
+- `trailingZeroDisplay`
+    - auto (default)
+    - stripIfInteger (no fraction digits when the rounded value is an integer)
+
+The digit options are *digit size options*: small non-negative integers (`0`-`99`).
+The numbering system is the default one of the locale (e.g. `Locale("ar", "EG")` uses Arabic-Indic digits).
+
+#### 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 rounded to an integer (`halfExpand`: `1.5` becomes `2`, `-2.5` becomes `-3`).
+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:
+
+```
+.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`.
+
+### `:percent`
+
+Formats a numeric operand multiplied by 100 as a percentage, e.g. `{0.25 :percent}` → `25%`.
+It takes the same options as `:number` except `select`, `minimumIntegerDigits` and `roundingIncrement`
+(by default no fraction digits are shown). As a selector it always uses the plural rules, on the value
+multiplied by 100. The resolved value of a `:percent` expression keeps the original (unmultiplied) value,
+so `.local $p = {0.25 :percent} {{{$p :number}}}` gives `0.25`.
+
+### `:currency`
+
+Formats a currency amount, e.g. `{42 :currency currency=EUR}` → `€42.00`. The operand is either a numeric
+operand together with the `currency` option, or a currency value: a `messageformat2.builtins.Currency(value, currency)`
+(or any mapping with the keys `value` and `currency`) passed as an input. The currency of a currency value cannot
+be overridden by the `currency` option (`BadOption`). `:currency` does not support selection.
+
+- `currency`: a three-letter currency code (case-insensitive); required for numeric operands
+- `currencySign`
+    - standard (default)
+    - accounting (e.g. `($42.50)`)
+- `currencyDisplay`
+    - symbol (default)
+    - narrowSymbol (treated as symbol)
+    - code (`USD42.00`)
+    - name (`42.00 US dollars`)
+    - never (`42.00`)
+- `useGrouping`, `minimumIntegerDigits`, `minimumSignificantDigits`, `maximumSignificantDigits`, `roundingMode`,
+  `roundingPriority`, `roundingIncrement`, `trailingZeroDisplay`: as for `:number`
+- `fractionDigits`
+    - auto (default): the number of fraction digits of the currency (2 for USD, 0 for JPY, ...)
+    - a *digit size option*: a fixed number of fraction digits
+
+### `: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.
+
+## The `u:` namespace options
+
+These options can be used with any function (including custom ones):
+
+- `u:dir`: `ltr`, `rtl`, `auto` or `inherit` (default). Sets the directionality of the placeholder for the
+  bidi isolation strategy and forces its isolation (except `inherit`). Not allowed on markup.
+- `u:id`: an identifier for the placeholder; accepted (it must be a string) but ignored when formatting to a string.
+
+Both are removed from the options before the function is called.

messageformat2-1.1.0/docs/explanation.md

@@ -0,0 +1,95 @@
+## 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
+from messageformat2 import Message
+
+counter = 0
+
+def formatter_with_side_effect(value, locale, options):
+    global 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.
+
+## Bidirectional text
+
+With `bidi_isolation=True`, placeholders are wrapped in Unicode isolate controls following the spec's
+*Default Bidi Strategy*, so that mixed left-to-right and right-to-left text displays correctly: a value whose
+direction is unknown (strings, literals, the results of custom formatters) is wrapped in U+2068 FIRST STRONG
+ISOLATE … U+2069 POP DIRECTIONAL ISOLATE, a value whose direction differs from the message's (e.g. a number,
+which has the direction of the locale, in a message formatted in an RTL locale) in U+2066 LEFT-TO-RIGHT ISOLATE /
+U+2067 RIGHT-TO-LEFT ISOLATE.
+
+```python
+Message("Hello, {$name}!").format({"name": "Alice"}, bidi_isolation=True)  # -> "Hello, \u2068Alice\u2069!"
+Message("{$n :number} items").format({"n": 3}, bidi_isolation=True)  # -> "3 items" (same direction)
+```
+
+The controls are invisible but do change the string, which is why isolation is off by default.
+The `u:dir` option sets the direction of a placeholder (`ltr`, `rtl` or `auto`) and forces its isolation:
+`{$name :string u:dir=rtl}`. Custom formatters can return a `messageformat2.builtins.FormattedValue(text, direction)`
+to declare the direction of their output.
+
+## 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
+from messageformat2 import format_message
+
+format_message(".local $x = {42 :number minimumFractionDigits=2 signDisplay=always} {{x = {$x :number minimumFractionDigits=1}}}")
+# -> "x = +42.0"
+format_message(".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
+from messageformat2 import Message
+
+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}}")
+```