.. -*- mode: rst; encoding: utf-8 -*-
-==========================
-Number and Date Formatting
-==========================
+===============
+Date Formatting
+===============
.. contents:: Contents
.. 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
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
.. _`Locale Data Markup Language specification`: http://unicode.org/reports/tr35/#Date_Format_Patterns
------------
Date Fields
-----------
| | ``c`` | ?? |
+----------+--------+--------------------------------------------------------+
------------
Time Fields
-----------
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
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
Introduction
============
-While `message catalogs <catalogs.html>`_ allow you to localize any messages
+While `message catalogs <messages.html>`_ 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.
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
======================
web-based applications.
* `Introduction <intro.html>`_
- * `Working with Message Catalogs <catalogs.html>`_
* `Locale Display Names <display.html>`_
- * `Number and Date Formatting <formatting.html>`_
+ * `Date Formatting <dates.html>`_
+ * `Number Formatting <numbers.html>`_
+ * `Working with Message Catalogs <messages.html>`_
* `Command-Line Interface <cmdline.html>`_
* `Distutils/Setuptools Integration <setup.html>`_
* `Support Classes and Functions <support.html>`_
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
.. _`Locale Display Names`: display.html
-.. _`Number and Date Formatting`: formatting.html
+.. _`Date Formatting`: dates.html
+.. _`Number Formatting`: numbers.html
--- /dev/null
+.. -*- 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
projects / thirdparty / babel.git / commitdiff
