Parse localized input
Users type numbers and dates the way their language writes them. A Czech user enters 1234,5, an American user 1234.5. Your code needs the same Decimal("1234.5") from both.
Citry reads this input with the same format profile you use to display the value. A profile can say which input it accepts, and the parser accepts only that: the locale's own digits, separators, and field order. It does not guess.
Read a number
Call self.i18n.parse.number() with the text and a profile name:
result = self.i18n.parse.number(
raw_amount,
format="measurement",
)
if result.valid:
save_amount(result.value)
else:
show_edit_again(result.input, result.error)
A number result keeps the user's exact text in input and reports one of three states:
valid:valueholds the number as aDecimal;incomplete: more typing could make it valid, as with a trailing decimal separator; andinvalid: the text does not match the profile.
While the user is still typing, leave their text in the field. Do not replace it with value; use value in your own logic once the result is valid.
Outside a component, use parse on a service for an explicit locale context, as in the datetime example below.
Accept number formats
Every NumberFormat accepts plain decimal numbers by default. To also accept scientific notation, set NumberInput:
from citry import FormatRegistry, NumberFormat, NumberInput
formats = FormatRegistry(
number={
"measurement": NumberFormat(),
"scientific-measurement": NumberFormat(
input=NumberInput(
notation="decimal_or_scientific",
),
),
},
)
The parser checks the locale's digits, decimal separator, grouping separator and group sizes, and signs. A separator or digit from another locale is invalid.
With decimal_or_scientific, the exponent marker is ASCII e or E. The exponent digits still use the locale's digits.
Read percentages
PercentInput says whether the user types the percent sign:
from citry import FormatRegistry, PercentFormat, PercentInput
formats = FormatRegistry(
percent={
"completion": PercentFormat(
input=PercentInput(affix="required"),
),
"completion-field": PercentFormat(
input=PercentInput(affix="omit"),
),
},
)
Use required when the percent sign is part of the typed text. Use omit when the form shows the sign outside the input field.
Both return a ratio: 12.5 percent comes back as Decimal("0.125").
Read dates
A date profile only reads input when you give it a DateInput. Choose one of two modes:
from citry import DateFormat, DateInput, FormatRegistry
formats = FormatRegistry(
date={
"invoice-date": DateFormat(
length="short",
input=DateInput(mode="strict_text"),
),
"birthday-fields": DateFormat(
length="long",
input=DateInput(mode="segments"),
),
},
)
strict_textreads one text field. It accepts the field order, separators, digits, and month names this profile displays in the locale, and nothing from other locales.segmentsreads a form that already has separate year, month, and day fields.
For segments, pass each field by name, whatever order the form shows them in:
from citry import DateSegments
result = self.i18n.parse.date_segments(
DateSegments(
year=year_edit,
month=month_edit,
day=day_edit,
),
format="birthday-fields",
)
A valid result holds a Python date. Citry reads the fields in the locale's calendar and reports an error for unclear or unsupported input instead of guessing.
Read times
Time profiles use the same two modes, with TimeInput:
from citry import (
FormatRegistry,
TimeFormat,
TimeInput,
TimeSegments,
)
formats = FormatRegistry(
time={
"appointment-time": TimeFormat(
length="medium",
input=TimeInput(mode="segments"),
),
},
)
result = self.i18n.parse.time_segments(
TimeSegments(
hour="2",
minute="30",
second="00",
day_period="PM",
),
format="appointment-time",
)
A valid result holds a Python time without a time zone. To get an exact moment, you also need a date and a zone; read both together as a datetime.
Read a date and time
A datetime profile combines date and time fields. Reading it needs a locale context with a time zone:
from citry import (
Citry,
DateSegments,
DateTimeFormat,
DateTimeInput,
DateTimeSegments,
FormatRegistry,
TimeSegments,
)
from citry.ext.i18n import make_context
formats = FormatRegistry(
datetime={
"appointment": DateTimeFormat(
length="medium",
input=DateTimeInput(mode="segments"),
),
},
)
app = Citry(
extensions_defaults={
"i18n": {
"source_locale": "en-US",
"locales": ("en-US",),
"formats": formats,
},
},
)
context = make_context(
app,
locale="en-US",
time_zone="Europe/Prague",
)
i18n = app.extensions.get_extension("i18n")
parser = i18n.for_context(context).parse
edit = DateTimeSegments(
date=DateSegments(year="2026", month="10", day="25"),
time=TimeSegments(
hour="2",
minute="30",
second="00",
day_period="AM",
),
)
result = parser.datetime_segments(edit, format="appointment")
Daylight saving time makes some local times special:
- A time that the clocks skip when daylight saving starts is
invalid. - A time that happens twice when the clocks go back is
ambiguous. The result lists both possible moments inalternatives.
The example above is ambiguous: 2:30 AM happens twice in Prague on 25 October 2026. Ask the user which one they mean, then pass it as fold:
result = parser.datetime_segments(
edit,
format="appointment",
fold="earlier", # or "later"
)
Parse in the browser
Inside a browser i18n provider, $i18n.parse reads numbers and percentages:
const result = $i18n.parse.number(
"12,345.50",
{ format: "measurement" },
);
It returns a frozen object with input, state, value, error, and valid. value is a string, so JavaScript does not lose decimal digits.
Dates, times, and datetimes are parsed only on the server; the browser has no methods for them. Reading them exactly like the server needs the server's calendar and daylight saving data, and Citry does not try to rebuild that data in the browser.
Less common cases
Accept two-digit years
By default, a year must have enough digits to identify it. To accept two-digit years, choose the first year of a 100-year window:
DateInput(
mode="strict_text",
two_digit_year_start=1950,
)
Two-digit years then map to 1950 through 2049. Citry does not move the window with the current date.
Read money and units
Parse the amount with parse.number() and keep the currency code or unit as separate data. Citry does not read a currency or unit from the typed text.
No relative dates
Citry does not read phrases such as "next Tuesday evening". Each profile accepts one strict format.
Time-zone data
Citry reads time-zone rules from the tzdata Python package it depends on, not from the operating system. A context with a time zone records the tzdata version it used.