Theme
Version
GitHub PyPI Discord
On this page

Format values

The same number or date is written differently in each language. One amount may be €1,234.50 in American English and 1 234,50 € in Czech, with different digits, separators, currency placement, or date order elsewhere.

Citry formats values for the current locale through format profiles. A format profile is a named set of formatting options, such as account-balance for currency amounts. You define each profile once, then refer to it by name in Python, templates, and browser code.

Define named formats

Create a FormatRegistry with your profiles, grouped by kind, and pass it in the i18n settings:

from citry import (
    Citry,
    CurrencyFormat,
    DateFormat,
    DateTimeFormat,
    FormatRegistry,
    NumberFormat,
    PercentFormat,
)

formats = FormatRegistry(
    number={
        "measurement": NumberFormat(),
    },
    percent={
        "completion": PercentFormat(),
    },
    currency={
        "account-balance": CurrencyFormat(),
    },
    date={
        "invoice-date": DateFormat(length="long"),
    },
    datetime={
        "appointment": DateTimeFormat(
            length="medium",
            time_zone_name="short",
        ),
    },
)

app = Citry(
    extensions_defaults={
        "i18n": {
            "source_locale": "en-US",
            "locales": ("en-US", "cs-CZ", "ar-EG"),
            "formats": formats,
        },
    },
)

Each kind has its own profile class:

KindProfile classOptions
numberNumberFormatinput
percentPercentFormatinput
currencyCurrencyFormatnone
dateDateFormatfields, length, input
timeTimeFormatlength, input
datetimeDateTimeFormatlength, time_zone_name, input
relative_timeRelativeTimeFormatunit
listListFormatkind, length
unitUnitFormatwidth

All of these classes are importable from citry. The input option says how to read what users type; see Parse localized input.

Format a value

In component Python code, use self.i18n.format:

from decimal import Decimal

class AccountBalance(Component):
    citry = app

    def template_data(self, kwargs, slots):
        return {
            "balance": self.i18n.format.currency(
                Decimal("1234.50"),
                "EUR",
                format="account-balance",
            ),
        }

    template = """
      <data>{{ balance }}</data>
    """

In a template, use fmt:

<data>{{ fmt.number(total, format="measurement") }}</data>

Outside a component, use a service for an explicit locale context:

i18n = app.extensions.get_extension("i18n")
formatted = i18n.for_context(context).format.number(
    Decimal("1234.50"),
    format="measurement",
)

Pass the right value

Each kind accepts a specific Python value:

OperationValueRule
numberint or finite DecimalKeeps every decimal digit
percentint or finite DecimalA ratio: 0.125 means 12.5%
currencyint or Decimal, plus a currency codeA code of three uppercase letters, such as EUR
datedateUses the locale's calendar
timetime without a time zoneA time on the clock, not a moment
datetimedatetime with a time zoneShown in the context's time zone
relative_timeint or Decimal, plus unit="day"Days are the only unit
listlist or tuple of non-empty stringsJoins items with "and" or "or"
unitint or Decimal, plus a unit nameYou always pass the unit

Floats are rejected with TypeError, because they cannot hold every decimal amount exactly. Convert amounts to Decimal first.

The formatters and tr() accept a Decimal with at most 32,768 digits before the decimal point and 32,768 after it, counting every zero of the written-out number. percent allows two fewer before the point, because it multiplies by 100. A larger value raises ValueError before any digits are written. Check numbers that come from a request: Decimal("1e999999999") is 11 characters long, but written out it is a billion digits. Even in range, a value can write tens of thousands of digits, so limit the size of a submitted Decimal in your own checks.

Use ratios for percent

A percent profile takes the ratio, not the number of percent:

from decimal import Decimal

label = self.i18n.format.percent(
    Decimal("0.125"),
    format="completion",
)

Decimal("0.125") means 12.5% in every locale. The locale decides the digits, the decimal separator, the spacing, and the percent sign. Reading the value back with the same profile returns the ratio again.

Format dates and times

Citry keeps three kinds apart:

  • a date is a calendar day, with no clock time;
  • a time is a clock time, with no date or time zone;
  • a datetime is an exact moment, which Citry shows in the context's time zone.

Formatting a datetime therefore needs a context with a time zone:

from citry.ext.i18n import make_context

i18n = app.extensions.get_extension("i18n")
context = make_context(
    app,
    locale="cs-CZ",
    time_zone="Europe/Prague",
)
formatter = i18n.for_context(context).format

text = formatter.datetime(
    aware_instant,
    format="appointment",
)

datetime() raises ValueError when the context has no time zone. time() raises ValueError for a time that carries a time zone, because the offset of a zone can depend on the date, which a time does not have.

Show part of a date

By default a date profile shows year, month, and day. Set fields for a calendar heading, a weekday name, or another partial date:

calendar_formats = FormatRegistry(
    date={
        "calendar-heading": DateFormat(
            fields="year_month",
            length="long",
        ),
        "calendar-weekday": DateFormat(
            fields="weekday",
            length="medium",
        ),
        "calendar-day": DateFormat(fields="day", length="short"),
        "calendar-date-label": DateFormat(
            fields="year_month_day_weekday",
            length="long",
        ),
    },
)

The values are year, month, day, weekday, year_month, month_day, day_weekday, month_day_weekday, year_month_day, and year_month_day_weekday. They choose which parts appear, not their order; the locale still decides the order, names, digits, and punctuation.

A profile that also reads user input (input=DateInput(...)) must keep the default fields="year_month_day", because Citry only reads complete dates.

Format in the browser

Inside a browser i18n provider, $i18n.format uses the same profile names:

<output
  v-text="$i18n.format.currency(
    '1234.50',
    'EUR',
    { format: 'account-balance' },
  )"
></output>

In the browser, pass exact decimals as strings, or as integers small enough for JavaScript to hold exactly. Pass a date as { year, month, day }, a time as its clock fields, and a moment as a JavaScript Date, which is shown in the context's time zone.

Less common cases

Name and kind errors

A profile name may contain ASCII letters, digits, -, and _. Any other name raises ValueError when you create the registry. A profile of the wrong class for its kind, such as a PercentFormat under number, raises TypeError there too. Calling a profile name that does not exist raises ValueError.

Built-in kinds only

You can add any number of profiles under the kinds above, but you cannot add a new kind or plug in your own formatter. The server and the browser must apply the same rules, and that is only possible for the built-in kinds.

Browser output differs

The server formats with ICU4X, the locale library Citry uses, and the browser with its built-in Intl API. Both apply the same profile, but a browser may have newer or older locale data, so small details such as spacing can differ. Do not compare formatted text to identify a value.