# HG changeset patch # User cmlenz # Date 1182179731 0 # Node ID 98dcabc99308dc34396d6d9a77bdb108577280d5 # Parent 31ca37101a240dfe8557f778871a191274360314 Split docs on date and number formatting. diff --git a/doc/formatting.txt b/doc/dates.txt rename from doc/formatting.txt rename to doc/dates.txt --- a/doc/formatting.txt +++ b/doc/dates.txt @@ -1,8 +1,8 @@ .. -*- mode: rst; encoding: utf-8 -*- -========================== -Number and Date Formatting -========================== +=============== +Date Formatting +=============== .. contents:: Contents @@ -10,9 +10,6 @@ .. sectnum:: -Date Formatting -=============== - When working with date and time information in Python, you commonly use the classes ``date``, ``datetime`` and/or ``time`` from the `datetime`_ package. Babel provides functions for locale-specific formatting of those objects in its @@ -55,7 +52,7 @@ Pattern Syntax --------------- +============== While Babel makes it simple to use the appropriate date/time format for a given locale, you can also force it to use custom patterns. Note that Babel uses @@ -106,7 +103,6 @@ .. _`Locale Data Markup Language specification`: http://unicode.org/reports/tr35/#Date_Format_Patterns ------------ Date Fields ----------- @@ -162,7 +158,6 @@ | | ``c`` | ?? | +----------+--------+--------------------------------------------------------+ ------------ Time Fields ----------- @@ -199,7 +194,7 @@ Time-Zone Support ------------------ +================= Many of the verbose time formats include the time-zone, but time-zone information is not by default available for the Python ``datetime`` and @@ -245,112 +240,10 @@ Parsing Dates -------------- +============= Babel can also parse date and time information in a locale-sensitive manner: .. code-block:: pycon >>> from babel.dates import parse_date, parse_datetime, parse_time - - -Number Formatting -================= - -Support for locale-specific formatting and parsing of numbers is provided by -the ``babel.numbers`` module: - -.. code-block:: pycon - - >>> from babel.numbers import format_number, format_decimal, format_percent - -Examples: - -.. code-block:: pycon - - >>> format_decimal(1.2345, locale='en_US') - u'1.234' - >>> format_decimal(1.2345, locale='sv_SE') - u'1,234' - >>> format_decimal(12345, locale='de_DE') - u'12.345' - - -Pattern Syntax --------------- - -While Babel makes it simple to use the appropriate number format for a given -locale, you can also force it to use custom patterns. As with date/time -formatting patterns, the patterns Babel supports for number formatting are -based on the `Locale Data Markup Language specification`_ (LDML). - -Examples: - -.. code-block:: pycon - - >>> format_decimal(-1.2345, format='#,##0.##;-#', locale='en') - u'-1.23' - >>> format_decimal(-1.2345, format='#,##0.##;(#)', locale='en') - u'(1.23)' - -The syntax for custom number format patterns is described in detail in the -the specification. The following table is just a relatively brief overview. - - +----------+-----------------------------------------------------------------+ - | Symbol | Description | - +==========+=================================================================+ - | ``0`` | Digit | - +----------+-----------------------------------------------------------------+ - | ``1-9`` | '1' through '9' indicate rounding. | - +----------+-----------------------------------------------------------------+ - | ``@`` | Significant digit | - +----------+-----------------------------------------------------------------+ - | ``#`` | Digit, zero shows as absent | - +----------+-----------------------------------------------------------------+ - | ``.`` | Decimal separator or monetary decimal separator | - +----------+-----------------------------------------------------------------+ - | ``-`` | Minus sign | - +----------+-----------------------------------------------------------------+ - | ``,`` | Grouping separator | - +----------+-----------------------------------------------------------------+ - | ``E`` | Separates mantissa and exponent in scientific notation | - +----------+-----------------------------------------------------------------+ - | ``+`` | Prefix positive exponents with localized plus sign | - +----------+-----------------------------------------------------------------+ - | ``;`` | Separates positive and negative subpatterns | - +----------+-----------------------------------------------------------------+ - | ``%`` | Multiply by 100 and show as percentage | - +----------+-----------------------------------------------------------------+ - | ``‰`` | Multiply by 1000 and show as per mille | - +----------+-----------------------------------------------------------------+ - | ``¤`` | Currency sign, replaced by currency symbol. If doubled, | - | | replaced by international currency symbol. If tripled, uses the | - | | long form of the decimal symbol. | - +----------+-----------------------------------------------------------------+ - | ``'`` | Used to quote special characters in a prefix or suffix | - +----------+-----------------------------------------------------------------+ - | ``*`` | Pad escape, precedes pad character | - +----------+-----------------------------------------------------------------+ - - -Parsing Numbers ---------------- - -Babel can also parse numeric data in a locale-sensitive manner: - -.. code-block:: pycon - - >>> from babel.numbers import parse_decimal, parse_number - -Examples: - -.. code-block:: pycon - - >>> parse_decimal('1,099.98', locale='en_US') - 1099.98 - >>> parse_decimal('1.099,98', locale='de') - 1099.98 - >>> parse_decimal('2,109,998', locale='de') - Traceback (most recent call last): - ... - NumberFormatError: '2,109,998' is not a valid decimal number diff --git a/doc/display.txt b/doc/display.txt --- a/doc/display.txt +++ b/doc/display.txt @@ -12,7 +12,7 @@ Introduction ============ -While `message catalogs `_ allow you to localize any messages +While `message catalogs `_ allow you to localize any messages in your application, there are a number of strings that are used in many applications for which translations are readily available. @@ -45,14 +45,12 @@ In addition to country/territory names, the locale data also provides access to names of languages, scripts, variants, time zones, and more. Some of the data -is closely related to `number and date formatting`_. +is closely related to number and date formatting. Most of the corresponding ``Locale`` properties return dictionaries, where the key is a code such as the ISO country and language codes. Consult the API documentation for references to the relevant specifications. -.. _`number and date formatting`: formatting.html - Calender Display Names ====================== diff --git a/doc/index.txt b/doc/index.txt --- a/doc/index.txt +++ b/doc/index.txt @@ -20,9 +20,10 @@ web-based applications. * `Introduction `_ - * `Working with Message Catalogs `_ * `Locale Display Names `_ - * `Number and Date Formatting `_ + * `Date Formatting `_ + * `Number Formatting `_ + * `Working with Message Catalogs `_ * `Command-Line Interface `_ * `Distutils/Setuptools Integration `_ * `Support Classes and Functions `_ diff --git a/doc/intro.txt b/doc/intro.txt --- a/doc/intro.txt +++ b/doc/intro.txt @@ -35,7 +35,7 @@ necessarily available on all platforms. See `Working with Message Catalogs`_ for details on this aspect of Babel. -.. _`Working with Message Catalogs`: catalogs.html +.. _`Working with Message Catalogs`: messages.html Locale Data @@ -57,4 +57,5 @@ .. _`Locale Display Names`: display.html -.. _`Number and Date Formatting`: formatting.html +.. _`Date Formatting`: dates.html +.. _`Number Formatting`: numbers.html diff --git a/doc/catalogs.txt b/doc/messages.txt rename from doc/catalogs.txt rename to doc/messages.txt diff --git a/doc/numbers.txt b/doc/numbers.txt new file mode 100644 --- /dev/null +++ b/doc/numbers.txt @@ -0,0 +1,111 @@ +.. -*- mode: rst; encoding: utf-8 -*- + +========================== +Number Formatting +========================== + + +.. contents:: Contents + :depth: 2 +.. sectnum:: + + +Support for locale-specific formatting and parsing of numbers is provided by +the ``babel.numbers`` module: + +.. code-block:: pycon + + >>> from babel.numbers import format_number, format_decimal, format_percent + +Examples: + +.. code-block:: pycon + + >>> format_decimal(1.2345, locale='en_US') + u'1.234' + >>> format_decimal(1.2345, locale='sv_SE') + u'1,234' + >>> format_decimal(12345, locale='de_DE') + u'12.345' + + +Pattern Syntax +============== + +While Babel makes it simple to use the appropriate number format for a given +locale, you can also force it to use custom patterns. As with date/time +formatting patterns, the patterns Babel supports for number formatting are +based on the `Locale Data Markup Language specification`_ (LDML). + +Examples: + +.. code-block:: pycon + + >>> format_decimal(-1.2345, format='#,##0.##;-#', locale='en') + u'-1.23' + >>> format_decimal(-1.2345, format='#,##0.##;(#)', locale='en') + u'(1.23)' + +The syntax for custom number format patterns is described in detail in the +the specification. The following table is just a relatively brief overview. + + .. _`Locale Data Markup Language specification`: http://unicode.org/reports/tr35/#Number_Format_Patterns + + +----------+-----------------------------------------------------------------+ + | Symbol | Description | + +==========+=================================================================+ + | ``0`` | Digit | + +----------+-----------------------------------------------------------------+ + | ``1-9`` | '1' through '9' indicate rounding. | + +----------+-----------------------------------------------------------------+ + | ``@`` | Significant digit | + +----------+-----------------------------------------------------------------+ + | ``#`` | Digit, zero shows as absent | + +----------+-----------------------------------------------------------------+ + | ``.`` | Decimal separator or monetary decimal separator | + +----------+-----------------------------------------------------------------+ + | ``-`` | Minus sign | + +----------+-----------------------------------------------------------------+ + | ``,`` | Grouping separator | + +----------+-----------------------------------------------------------------+ + | ``E`` | Separates mantissa and exponent in scientific notation | + +----------+-----------------------------------------------------------------+ + | ``+`` | Prefix positive exponents with localized plus sign | + +----------+-----------------------------------------------------------------+ + | ``;`` | Separates positive and negative subpatterns | + +----------+-----------------------------------------------------------------+ + | ``%`` | Multiply by 100 and show as percentage | + +----------+-----------------------------------------------------------------+ + | ``‰`` | Multiply by 1000 and show as per mille | + +----------+-----------------------------------------------------------------+ + | ``¤`` | Currency sign, replaced by currency symbol. If doubled, | + | | replaced by international currency symbol. If tripled, uses the | + | | long form of the decimal symbol. | + +----------+-----------------------------------------------------------------+ + | ``'`` | Used to quote special characters in a prefix or suffix | + +----------+-----------------------------------------------------------------+ + | ``*`` | Pad escape, precedes pad character | + +----------+-----------------------------------------------------------------+ + + +Parsing Numbers +=============== + +Babel can also parse numeric data in a locale-sensitive manner: + +.. code-block:: pycon + + >>> from babel.numbers import parse_decimal, parse_number + +Examples: + +.. code-block:: pycon + + >>> parse_decimal('1,099.98', locale='en_US') + 1099.98 + >>> parse_decimal('1.099,98', locale='de') + 1099.98 + >>> parse_decimal('2,109,998', locale='de') + Traceback (most recent call last): + ... + NumberFormatError: '2,109,998' is not a valid decimal number