Package babel :: Module core :: Class Locale |

# Class Locale

    object --+
             |
            Locale

Representation of a specific locale.

    >>> locale = Locale('en', 'US')
    >>> repr(locale)
    '<Locale "en_US">'
    >>> locale.display_name
    u'English (United States)'

A Locale object can also be instantiated from a raw locale string:

    >>> locale = Locale.parse('en-US', sep='-')
    >>> repr(locale)
    '<Locale "en_US">'

Locale objects provide access to a collection of locale data, such as territory and language names, number and date format patterns, and more:

    >>> locale.number_symbols['decimal']
    u'.'

If a locale is requested for which no locale data is available, an UnknownLocaleError is raised:

    >>> Locale.parse('en_DE')
    Traceback (most recent call last):
        ...
    UnknownLocaleError: unknown locale 'en_DE'

See Also: IETF RFC 3066

Instance Methods
__init__(self, language, territory=None, script=None, variant=None) Initialize the locale object from the given identifier components. |
__eq__(self, other) |
__ne__(self, other) |
__repr__(self) repr(x) |
__str__(self) str(x) |
get_display_name(self, locale=None) Return the display name of the locale using the given locale. |
Inherited from `object`: `__delattr__`, `__format__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__sizeof__`, `__subclasshook__`

Class Methods
Locale |
default(cls, category=None, aliases=`{``'``ar``'``:` `'``ar_SY``'``,` `'``bg``'``:` `'``bg_BG``'``,` `'``bs``'``:` `'``bs_BA``'``,` `'``ca``'``:` `'``ca_ES``'``,` `'``...`) Return the system default locale for the specified category. |
Locale |
negotiate(cls, preferred, available, sep=`'``_``'`, aliases=`{``'``ar``'``:` `'``ar_SY``'``,` `'``bg``'``:` `'``bg_BG``'``,` `'``bs``'``:` `'``bs_BA``'``,` `'``ca``'``:` `'``ca_ES``'``,` `'``...`) Find the best match between available and requested locale strings. |
Locale |
parse(cls, identifier, sep=`'``_``'`) Create a Locale instance for the given locale identifier. |

Properties
`unicode` | display_name The localized display name of the locale.
`unicode` | english_name The english display name of the locale.
Inherited from `object`: `__class__`
General Locale Display Names
`dict` | languages Mapping of language codes to translated language names.
`dict` | scripts Mapping of script codes to translated script names.
`dict` | territories Mapping of script codes to translated script names.
`dict` | variants Mapping of script codes to translated script names.
Number Formatting
`dict` | currencies Mapping of currency codes to translated currency names.
`dict` | currency_symbols Mapping of currency codes to symbols.
`dict` | number_symbols Symbols used in number formatting.
`dict` | decimal_formats Locale patterns for decimal number formatting.
`dict` | currency_formats Locale patterns for currency number formatting.
`dict` | percent_formats Locale patterns for percent number formatting.
`dict` | scientific_formats Locale patterns for scientific number formatting.
Calendar Information and Date Formatting
`dict` | periods Locale display names for day periods (AM/PM).
`dict` | days Locale display names for weekdays.
`dict` | months Locale display names for months.
`dict` | quarters Locale display names for quarters.
`dict` | eras Locale display names for eras.
`dict` | time_zones Locale display names for time zones.
`dict` | meta_zones Locale display names for meta time zones.
`dict` | zone_formats Patterns related to the formatting of time zones.
`int` | first_week_day The first day of a week, with 0 being Monday.
`int` | weekend_start The day the weekend starts, with 0 being Monday.
`int` | weekend_end The day the weekend ends, with 0 being Monday.
`int` | min_week_days The minimum number of days in a week so that the week is counted as the first week of a year or month.
`dict` | date_formats Locale patterns for date formatting.
`dict` | time_formats Locale patterns for time formatting.
`dict` | datetime_formats Locale patterns for datetime formatting.

Method Details

### __init__(self, language, territory=None, script=None, variant=None) (Constructor) |
Initialize the locale object from the given identifier components.
    >>> locale = Locale('en', 'US')
    >>> locale.language
    'en'
    >>> locale.territory
    'US'
Parameters: `language` - the language code `territory` - the territory (country or region) code `script` - the script code `variant` - the variant code Raises: `UnknownLocaleError` - if no locale data is available for the requested locale Overrides: object.__init__

### default(cls, category=None, aliases=`{``'``ar``'``:` `'``ar_SY``'``,` `'``bg``'``:` `'``bg_BG``'``,` `'``bs``'``:` `'``bs_BA``'``,` `'``ca``'``:` `'``ca_ES``'``,` `'``...`) Class Method |
Return the system default locale for the specified category.
    >>> for name in ['LANGUAGE', 'LC_ALL', 'LC_CTYPE']:
    ...     os.environ[name] = ''
    >>> os.environ['LANG'] = 'fr_FR.UTF-8'
    >>> Locale.default('LC_MESSAGES')
    <Locale "fr_FR">
Parameters: `category` - one of the `LC_XXX` environment variable names `aliases` - a dictionary of aliases for locale identifiers Returns: Locale the value of the variable, or any of the fallbacks (`LANGUAGE`, `LC_ALL`, `LC_CTYPE`, and `LANG`) See Also: default_locale

### negotiate(cls, preferred, available, sep=`'``_``'`, aliases=`{``'``ar``'``:` `'``ar_SY``'``,` `'``bg``'``:` `'``bg_BG``'``,` `'``bs``'``:` `'``bs_BA``'``,` `'``ca``'``:` `'``ca_ES``'``,` `'``...`) Class Method |
Find the best match between available and requested locale strings.
    >>> Locale.negotiate(['de_DE', 'en_US'], ['de_DE', 'de_AT'])
    <Locale "de_DE">
    >>> Locale.negotiate(['de_DE', 'en_US'], ['en', 'de'])
    <Locale "de">
    >>> Locale.negotiate(['de_DE', 'de'], ['en_US'])
You can specify the character used in the locale identifiers to separate the differnet components. This separator is applied to both lists. Also, case is ignored in the comparison:
    >>> Locale.negotiate(['de-DE', 'de'], ['en-us', 'de-de'], sep='-')
    <Locale "de_DE">
Parameters: `preferred` - the list of locale identifers preferred by the user `available` - the list of locale identifiers available `aliases` - a dictionary of aliases for locale identifiers Returns: Locale the Locale object for the best match, or `None` if no match was found See Also: negotiate_locale

### parse(cls, identifier, sep=`'``_``'`) Class Method |
Create a Locale instance for the given locale identifier.
    >>> l = Locale.parse('de-DE', sep='-')
    >>> l.display_name
    u'Deutsch (Deutschland)'
If the `identifier` parameter is not a string, but actually a Locale object, that object is returned:
    >>> Locale.parse(l)
    <Locale "de_DE">
Parameters: `identifier` - the locale identifier string `sep` - optional component separator Returns: Locale a corresponding Locale instance Raises: `ValueError` - if the string does not appear to be a valid locale identifier `UnknownLocaleError` - if no locale data is available for the requested locale See Also: parse_locale

### __repr__(self) (Representation operator) |
repr(x) Overrides: object.__repr__ (inherited documentation)

### __str__(self) (Informal representation operator) |
str(x) Overrides: object.__str__ (inherited documentation)

### get_display_name(self, locale=None) |
Return the display name of the locale using the given locale. The display name will include the language, territory, script, and variant, if those are specified.
    >>> Locale('zh', 'CN', script='Hans').get_display_name('en')
    u'Chinese (Simplified Han, China)'
Parameters: `locale` - the locale to use Returns: the display name

Property Details

### display_name The localized display name of the locale.
    >>> Locale('en').display_name
    u'English'
    >>> Locale('en', 'US').display_name
    u'English (United States)'
    >>> Locale('sv').display_name
    u'svenska'
Get Method: get_display_name(self, locale=None) - Return the display name of the locale using the given locale. Type: `unicode`

### english_name The english display name of the locale.
    >>> Locale('de').english_name
    u'German'
    >>> Locale('de', 'DE').english_name
    u'German (Germany)'
Get Method: unreachable.english_name(self) Type: `unicode`

### languages Mapping of language codes to translated language names.
    >>> Locale('de', 'DE').languages['ja']
    u'Japanisch'
Get Method: unreachable.languages(self) Type: `dict` See Also: ISO 639

### scripts Mapping of script codes to translated script names.
    >>> Locale('en', 'US').scripts['Hira']
    u'Hiragana'
Get Method: unreachable.scripts(self) Type: `dict` See Also: ISO 15924

### territories Mapping of script codes to translated script names.
    >>> Locale('es', 'CO').territories['DE']
    u'Alemania'
Get Method: unreachable.territories(self) Type: `dict` See Also: ISO 3166

### variants Mapping of script codes to translated script names.
    >>> Locale('de', 'DE').variants['1901']
    u'Alte deutsche Rechtschreibung'
Get Method: unreachable.variants(self) Type: `dict`

### currencies Mapping of currency codes to translated currency names.
    >>> Locale('en').currencies['COP']
    u'Colombian Peso'
    >>> Locale('de', 'DE').currencies['COP']
    u'Kolumbianischer Peso'
Get Method: unreachable.currencies(self) Type: `dict`

### currency_symbols Mapping of currency codes to symbols.
    >>> Locale('en', 'US').currency_symbols['USD']
    u'$'
    >>> Locale('es', 'CO').currency_symbols['USD']
    u'US$'
Get Method: unreachable.currency_symbols(self) Type: `dict`

### number_symbols Symbols used in number formatting.
    >>> Locale('fr', 'FR').number_symbols['decimal']
    u','
Get Method: unreachable.number_symbols(self) Type: `dict`

### decimal_formats Locale patterns for decimal number formatting.
    >>> Locale('en', 'US').decimal_formats[None]
    <NumberPattern u'#,##0.###'>
Get Method: unreachable.decimal_formats(self) Type: `dict`

### currency_formats Locale patterns for currency number formatting.
    >>> print Locale('en', 'US').currency_formats[None]
    <NumberPattern u'\xa4#,##0.00'>
Get Method: unreachable.currency_formats(self) Type: `dict`

### percent_formats Locale patterns for percent number formatting.
    >>> Locale('en', 'US').percent_formats[None]
    <NumberPattern u'#,##0%'>
Get Method: unreachable.percent_formats(self) Type: `dict`

### scientific_formats Locale patterns for scientific number formatting.
    >>> Locale('en', 'US').scientific_formats[None]
    <NumberPattern u'#E0'>
Get Method: unreachable.scientific_formats(self) Type: `dict`

### periods Locale display names for day periods (AM/PM).
    >>> Locale('en', 'US').periods['am']
    u'AM'
Get Method: unreachable.periods(self) Type: `dict`

### days Locale display names for weekdays.
    >>> Locale('de', 'DE').days['format']['wide'][3]
    u'Donnerstag'
Get Method: unreachable.days(self) Type: `dict`

### months Locale display names for months.
    >>> Locale('de', 'DE').months['format']['wide'][10]
    u'Oktober'
Get Method: unreachable.months(self) Type: `dict`

### quarters Locale display names for quarters.
    >>> Locale('de', 'DE').quarters['format']['wide'][1]
    u'1. Quartal'
Get Method: unreachable.quarters(self) Type: `dict`

### eras Locale display names for eras.
    >>> Locale('en', 'US').eras['wide'][1]
    u'Anno Domini'
    >>> Locale('en', 'US').eras['abbreviated'][0]
    u'BC'
Get Method: unreachable.eras(self) Type: `dict`

### time_zones Locale display names for time zones.
    >>> Locale('en', 'US').time_zones['Europe/London']['long']['daylight']
    u'British Summer Time'
    >>> Locale('en', 'US').time_zones['America/St_Johns']['city']
    u"St. John's"
Get Method: unreachable.time_zones(self) Type: `dict`

### meta_zones Locale display names for meta time zones. Meta time zones are basically groups of different Olson time zones that have the same GMT offset and daylight savings time.
    >>> Locale('en', 'US').meta_zones['Europe_Central']['long']['daylight']
    u'Central European Summer Time'
Get Method: unreachable.meta_zones(self) Type: `dict` Since: version 0.9

### zone_formats Patterns related to the formatting of time zones.
    >>> Locale('en', 'US').zone_formats['fallback']
    u'%(1)s (%(0)s)'
    >>> Locale('pt', 'BR').zone_formats['region']
    u'Hor\xe1rio %s'
Get Method: unreachable.zone_formats(self) Type: `dict` Since: version 0.9

### first_week_day The first day of a week, with 0 being Monday.
    >>> Locale('de', 'DE').first_week_day
    0
    >>> Locale('en', 'US').first_week_day
    6
Get Method: unreachable.first_week_day(self) Type: `int`

### weekend_start The day the weekend starts, with 0 being Monday.
    >>> Locale('de', 'DE').weekend_start
    5
Get Method: unreachable.weekend_start(self) Type: `int`

### weekend_end The day the weekend ends, with 0 being Monday.
    >>> Locale('de', 'DE').weekend_end
    6
Get Method: unreachable.weekend_end(self) Type: `int`

### min_week_days The minimum number of days in a week so that the week is counted as the first week of a year or month.
    >>> Locale('de', 'DE').min_week_days
    4
Get Method: unreachable.min_week_days(self) Type: `int`

### date_formats Locale patterns for date formatting.
    >>> Locale('en', 'US').date_formats['short']
    <DateTimePattern u'M/d/yy'>
    >>> Locale('fr', 'FR').date_formats['long']
    <DateTimePattern u'd MMMM yyyy'>
Get Method: unreachable.date_formats(self) Type: `dict`

### time_formats Locale patterns for time formatting.
    >>> Locale('en', 'US').time_formats['short']
    <DateTimePattern u'h:mm a'>
    >>> Locale('fr', 'FR').time_formats['long']
    <DateTimePattern u'HH:mm:ss z'>
Get Method: unreachable.time_formats(self) Type: `dict`

### datetime_formats Locale patterns for datetime formatting.
    >>> Locale('en').datetime_formats[None]
    u'{1} {0}'
    >>> Locale('th').datetime_formats[None]
    u'{1}, {0}'
Get Method: unreachable.datetime_formats(self) Type: `dict`