webapp2/webapp2_extras/i18n.py

# -*- coding: utf-8 -*-
"""
    webapp2_extras.i18n
    ===================

    Internationalization support for webapp2.

    Several ideas borrowed from tipfy.i18n and Flask-Babel.

    :copyright: 2011 by tipfy.org.
    :license: Apache Sotware License, see LICENSE for details.
"""
import datetime
import gettext as gettext_stdlib

import babel
from babel import dates
from babel import numbers
from babel import support

try:
    # Monkeypatches pytz for gae.
    import pytz.gae
except ImportError: # pragma: no cover
    pass

import pytz

import webapp2

#: Default configuration values for this module. Keys are:
#:
#: translations_path
#:     Path to the translations directory. Default is `locale`.
#:
#: domains
#:     List of gettext domains to be used. Default is ``['messages']``.
#:
#: default_locale
#:     A locale code to be used as fallback. Default is ``'en_US'``.
#:
#: default_timezone
#:     The application default timezone according to the Olson
#:     database. Default is ``'UTC'``.
#:
#: locale_selector
#:     A function that receives (store, request) and returns a locale
#:     to be used for a request. If not defined, uses `default_locale`.
#:     Can also be a string in dotted notation to be imported.
#:
#: timezone_selector
#:     A function that receives (store, request) and returns a timezone
#:     to be used for a request. If not defined, uses `default_timezone`.
#:     Can also be a string in dotted notation to be imported.
#:
#: date_formats
#:     Default date formats for datetime, date and time.
default_config = {
    'translations_path':   'locale',
    'domains':             ['messages'],
    'default_locale':      'en_US',
    'default_timezone':    'UTC',
    'locale_selector':     None,
    'timezone_selector':   None,
    'date_formats': {
        'time':            'medium',
        'date':            'medium',
        'datetime':        'medium',
        'time.short':      None,
        'time.medium':     None,
        'time.full':       None,
        'time.long':       None,
        'time.iso':        "HH':'mm':'ss",
        'date.short':      None,
        'date.medium':     None,
        'date.full':       None,
        'date.long':       None,
        'date.iso':        "yyyy'-'MM'-'dd",
        'datetime.short':  None,
        'datetime.medium': None,
        'datetime.full':   None,
        'datetime.long':   None,
        'datetime.iso':    "yyyy'-'MM'-'dd'T'HH':'mm':'ssZ",
    },
}

NullTranslations = gettext_stdlib.NullTranslations


class I18nStore(object):
    """Internalization store.

    Caches loaded translations and configuration to be used between requests.
    """

    #: Configuration key.
    config_key = __name__
    #: A dictionary with all loaded translations.
    translations = None
    #: Path to where traslations are stored.
    translations_path = None
    #: Translation domains to merge.
    domains = None
    #: Default locale code.
    default_locale = None
    #: Default timezone code.
    default_timezone = None
    #: Dictionary of default date formats.
    date_formats = None
    #: A callable that returns the locale for a request.
    locale_selector = None
    #: A callable that returns the timezone for a request.
    timezone_selector = None

    def __init__(self, app, config=None):
        """Initializes the i18n store.

        :param app:
            A :class:`webapp2.WSGIApplication` instance.
        :param config:
            A dictionary of configuration values to be overridden. See
            the available keys in :data:`default_config`.
        """
        config = app.config.load_config(self.config_key,
            default_values=default_config, user_values=config,
            required_keys=None)
        self.translations = {}
        self.translations_path = config['translations_path']
        self.domains = config['domains']
        self.default_locale = config['default_locale']
        self.default_timezone = config['default_timezone']
        self.date_formats = config['date_formats']
        self.set_locale_selector(config['locale_selector'])
        self.set_timezone_selector(config['timezone_selector'])

    def set_locale_selector(self, func):
        """Sets the function that defines the locale for a request.

        :param func:
            A callable that receives (store, request) and returns the locale
            for a request.
        """
        if func is None:
            self.locale_selector = self.default_locale_selector
        else:
            if isinstance(func, basestring):
                func = webapp2.import_string(func)

            # Functions are descriptors, so bind it to this instance with
            # __get__.
            self.locale_selector = func.__get__(self, self.__class__)

    def set_timezone_selector(self, func):
        """Sets the function that defines the timezone for a request.

        :param func:
            A callable that receives (store, request) and returns the timezone
            for a request.
        """
        if func is None:
            self.timezone_selector = self.default_timezone_selector
        else:
            if isinstance(func, basestring):
                func = webapp2.import_string(func)

            self.timezone_selector = func.__get__(self, self.__class__)

    def default_locale_selector(self, request):
        return self.default_locale

    def default_timezone_selector(self, request):
        return self.default_timezone

    def get_translations(self, locale):
        """Returns a translation catalog for a locale.

        :param locale:
            A locale code.
        :returns:
            A ``babel.support.Translations`` instance, or
            ``gettext.NullTranslations`` if none was found.
        """
        trans = self.translations.get(locale)
        if not trans:
            locales = (locale, self.default_locale)
            trans = self.load_translations(self.translations_path, locales,
                                           self.domains)
            if not webapp2.get_app().debug:
                self.translations[locale] = trans

        return trans

    def load_translations(self, dirname, locales, domains):
        """Loads a translation catalog.

        :param dirname:
            Path to where translations are stored.
        :param locales:
            A list of locale codes.
        :param domains:
            A list of domains to be merged.
        :returns:
            A ``babel.support.Translations`` instance, or
            ``gettext.NullTranslations`` if none was found.
        """
        trans = None
        trans_null = None
        for domain in domains:
            _trans = support.Translations.load(dirname, locales, domain)
            if isinstance(_trans, NullTranslations):
                trans_null = _trans
                continue
            elif trans is None:
                trans = _trans
            else:
                trans.merge(_trans)

        return trans or trans_null or NullTranslations()


class I18n(object):
    """Internalization provider for a single request."""

    #: A reference to :class:`I18nStore`.
    store = None
    #: The current locale code.
    locale = None
    #: The current translations.
    translations = None
    #: The current timezone code.
    timezone = None
    #: The current tzinfo object.
    tzinfo = None

    def __init__(self, request):
        """Initializes the i18n provider for a request.

        :param request:
            A :class:`webapp2.Request` instance.
        """
        self.store = store = get_store(app=request.app)
        self.set_locale(store.locale_selector(request))
        self.set_timezone(store.timezone_selector(request))

    def set_locale(self, locale):
        """Sets the locale code for this request.

        :param locale:
            A locale code.
        """
        self.locale = locale
        self.translations = self.store.get_translations(locale)

    def set_timezone(self, timezone):
        """Sets the timezone code for this request.

        :param timezone:
            A timezone code.
        """
        self.timezone = timezone
        self.tzinfo = pytz.timezone(timezone)

    def gettext(self, string, **variables):
        """Translates a given string according to the current locale.

        :param string:
            The string to be translated.
        :param variables:
            Variables to format the returned string.
        :returns:
            The translated string.
        """
        if variables:
            return self.translations.ugettext(string) % variables

        return self.translations.ugettext(string)

    def ngettext(self, singular, plural, n, **variables):
        """Translates a possible pluralized string according to the current
        locale.

        :param singular:
            The singular for of the string to be translated.
        :param plural:
            The plural for of the string to be translated.
        :param n:
            An integer indicating if this is a singular or plural. If greater
            than 1, it is a plural.
        :param variables:
            Variables to format the returned string.
        :returns:
            The translated string.
        """
        if variables:
            return self.translations.ungettext(singular, plural, n) % variables

        return self.translations.ungettext(singular, plural, n)

    def to_local_timezone(self, datetime):
        """Returns a datetime object converted to the local timezone.

        :param datetime:
            A ``datetime`` object.
        :returns:
            A ``datetime`` object normalized to a timezone.
        """
        if datetime.tzinfo is None:
            datetime = datetime.replace(tzinfo=pytz.UTC)

        return self.tzinfo.normalize(datetime.astimezone(self.tzinfo))

    def to_utc(self, datetime):
        """Returns a datetime object converted to UTC and without tzinfo.

        :param datetime:
            A ``datetime`` object.
        :returns:
            A naive ``datetime`` object (no timezone), converted to UTC.
        """
        if datetime.tzinfo is None:
            datetime = self.tzinfo.localize(datetime)

        return datetime.astimezone(pytz.UTC).replace(tzinfo=None)

    def _get_format(self, key, format):
        """A helper for the datetime formatting functions. Returns a format
        name or pattern to be used by Babel date format functions.

        :param key:
            A format key to be get from config. Valid values are "date",
            "datetime" or "time".
        :param format:
            The format to be returned. Valid values are "short", "medium",
            "long", "full" or a custom date/time pattern.
        :returns:
            A format name or pattern to be used by Babel date format functions.
        """
        if format is None:
            format = self.store.date_formats.get(key)

        if format in ('short', 'medium', 'full', 'long', 'iso'):
            rv = self.store.date_formats.get('%s.%s' % (key, format))
            if rv is not None:
                format = rv

        return format

    def format_date(self, date=None, format=None, rebase=True):
        """Returns a date formatted according to the given pattern and
        following the current locale.

        :param date:
            A ``date`` or ``datetime`` object. If None, the current date in
            UTC is used.
        :param format:
            The format to be returned. Valid values are "short", "medium",
            "long", "full" or a custom date/time pattern. Example outputs:

            - short:  11/10/09
            - medium: Nov 10, 2009
            - long:   November 10, 2009
            - full:   Tuesday, November 10, 2009

        :param rebase:
            If True, converts the date to the current :attr:`timezone`.
        :returns:
            A formatted date in unicode.
        """
        format = self._get_format('date', format)

        if rebase and isinstance(date, datetime.datetime):
            date = self.to_local_timezone(date)

        return dates.format_date(date, format, locale=self.locale)

    def format_datetime(self, datetime=None, format=None, rebase=True):
        """Returns a date and time formatted according to the given pattern
        and following the current locale and timezone.

        :param datetime:
            A ``datetime`` object. If None, the current date and time in UTC
            is used.
        :param format:
            The format to be returned. Valid values are "short", "medium",
            "long", "full" or a custom date/time pattern. Example outputs:

            - short:  11/10/09 4:36 PM
            - medium: Nov 10, 2009 4:36:05 PM
            - long:   November 10, 2009 4:36:05 PM +0000
            - full:   Tuesday, November 10, 2009 4:36:05 PM World (GMT) Time

        :param rebase:
            If True, converts the datetime to the current :attr:`timezone`.
        :returns:
            A formatted date and time in unicode.
        """
        format = self._get_format('datetime', format)

        kwargs = {}
        if rebase:
            kwargs['tzinfo'] = self.tzinfo

        return dates.format_datetime(datetime, format, locale=self.locale,
                                     **kwargs)

    def format_time(self, time=None, format=None, rebase=True):
        """Returns a time formatted according to the given pattern and
        following the current locale and timezone.

        :param time:
            A ``time`` or ``datetime`` object. If None, the current
            time in UTC is used.
        :param format:
            The format to be returned. Valid values are "short", "medium",
            "long", "full" or a custom date/time pattern. Example outputs:

            - short:  4:36 PM
            - medium: 4:36:05 PM
            - long:   4:36:05 PM +0000
            - full:   4:36:05 PM World (GMT) Time

        :param rebase:
            If True, converts the time to the current :attr:`timezone`.
        :returns:
            A formatted time in unicode.
        """
        format = self._get_format('time', format)

        kwargs = {}
        if rebase:
            kwargs['tzinfo'] = self.tzinfo

        return dates.format_time(time, format, locale=self.locale, **kwargs)

    def format_timedelta(self, datetime_or_timedelta, granularity='second',
                         threshold=.85):
        """Formats the elapsed time from the given date to now or the given
        timedelta. This currently requires an unreleased development version
        of Babel.

        :param datetime_or_timedelta:
            A ``timedelta`` object representing the time difference to format,
            or a ``datetime`` object in UTC.
        :param granularity:
            Determines the smallest unit that should be displayed, the value
            can be one of "year", "month", "week", "day", "hour", "minute" or
            "second".
        :param threshold:
            Factor that determines at which point the presentation switches to
            the next higher unit.
        :returns:
            A string with the elapsed time.
        """
        if isinstance(datetime_or_timedelta, datetime.datetime):
            datetime_or_timedelta = datetime.datetime.utcnow() - \
                datetime_or_timedelta

        return dates.format_timedelta(datetime_or_timedelta, granularity,
                                      threshold=threshold,
                                      locale=self.locale)

    def format_number(self, number):
        """Returns the given number formatted for the current locale. Example::

            >>> format_number(1099, locale='en_US')
            u'1,099'

        :param number:
            The number to format.
        :returns:
            The formatted number.
        """
        return numbers.format_number(number, locale=self.locale)

    def format_decimal(self, number, format=None):
        """Returns the given decimal number formatted for the current locale.
        Example::

            >>> format_decimal(1.2345, locale='en_US')
            u'1.234'
            >>> format_decimal(1.2346, locale='en_US')
            u'1.235'
            >>> format_decimal(-1.2346, locale='en_US')
            u'-1.235'
            >>> format_decimal(1.2345, locale='sv_SE')
            u'1,234'
            >>> format_decimal(12345, locale='de')
            u'12.345'

        The appropriate thousands grouping and the decimal separator are used
        for each locale::

            >>> format_decimal(12345.5, locale='en_US')
            u'12,345.5'

        :param number:
            The number to format.
        :param format:
            Notation format.
        :returns:
            The formatted decimal number.
        """
        return numbers.format_decimal(number, format=format,
                                      locale=self.locale)

    def format_currency(self, number, currency, format=None):
        """Returns a formatted currency value. Example::

            >>> format_currency(1099.98, 'USD', locale='en_US')
            u'$1,099.98'
            >>> format_currency(1099.98, 'USD', locale='es_CO')
            u'US$\\xa01.099,98'
            >>> format_currency(1099.98, 'EUR', locale='de_DE')
            u'1.099,98\\xa0\\u20ac'

        The pattern can also be specified explicitly::

            >>> format_currency(1099.98, 'EUR', u'\\xa4\\xa4 #,##0.00',
            ...                 locale='en_US')
            u'EUR 1,099.98'

        :param number:
            The number to format.
        :param currency:
            The currency code.
        :param format:
            Notation format.
        :returns:
            The formatted currency value.
        """
        return numbers.format_currency(number, currency, format=format,
                                       locale=self.locale)

    def format_percent(self, number, format=None):
        """Returns formatted percent value for the current locale. Example::

            >>> format_percent(0.34, locale='en_US')
            u'34%'
            >>> format_percent(25.1234, locale='en_US')
            u'2,512%'
            >>> format_percent(25.1234, locale='sv_SE')
            u'2\\xa0512\\xa0%'

        The format pattern can also be specified explicitly::

            >>> format_percent(25.1234, u'#,##0\u2030', locale='en_US')
            u'25,123\u2030'

        :param number:
            The percent number to format
        :param format:
            Notation format.
        :returns:
            The formatted percent number.
        """
        return numbers.format_percent(number, format=format,
                                      locale=self.locale)

    def format_scientific(self, number, format=None):
        """Returns value formatted in scientific notation for the current
        locale. Example::

            >>> format_scientific(10000, locale='en_US')
            u'1E4'

        The format pattern can also be specified explicitly::

            >>> format_scientific(1234567, u'##0E00', locale='en_US')
            u'1.23E06'

        :param number:
            The number to format.
        :param format:
            Notation format.
        :returns:
            Value formatted in scientific notation.
        """
        return numbers.format_scientific(number, format=format,
                                         locale=self.locale)

    def parse_date(self, string):
        """Parses a date from a string.

        This function uses the date format for the locale as a hint to
        determine the order in which the date fields appear in the string.
        Example::

            >>> parse_date('4/1/04', locale='en_US')
            datetime.date(2004, 4, 1)
            >>> parse_date('01.04.2004', locale='de_DE')
            datetime.date(2004, 4, 1)

        :param string:
            The string containing the date.
        :returns:
            The parsed date object.
        """
        return dates.parse_date(string, locale=self.locale)

    def parse_datetime(self, string):
        """Parses a date and time from a string.

        This function uses the date and time formats for the locale as a hint
        to determine the order in which the time fields appear in the string.

        :param string:
            The string containing the date and time.
        :returns:
            The parsed datetime object.
        """
        return dates.parse_datetime(string, locale=self.locale)

    def parse_time(self, string):
        """Parses a time from a string.

        This function uses the time format for the locale as a hint to
        determine the order in which the time fields appear in the string.
        Example::

            >>> parse_time('15:30:00', locale='en_US')
            datetime.time(15, 30)

        :param string:
            The string containing the time.
        :returns:
            The parsed time object.
        """
        return dates.parse_time(string, locale=self.locale)

    def parse_number(self, string):
        """Parses localized number string into a long integer. Example::

            >>> parse_number('1,099', locale='en_US')
            1099L
            >>> parse_number('1.099', locale='de_DE')
            1099L

        When the given string cannot be parsed, an exception is raised::

            >>> parse_number('1.099,98', locale='de')
            Traceback (most recent call last):
               ...
            NumberFormatError: '1.099,98' is not a valid number

        :param string:
            The string to parse.
        :returns:
            The parsed number.
        :raises:
            ``NumberFormatError`` if the string can not be converted to a
            number.
        """
        return numbers.parse_number(string, locale=self.locale)

    def parse_decimal(self, string):
        """Parses localized decimal string into a float. Example::

            >>> parse_decimal('1,099.98', locale='en_US')
            1099.98
            >>> parse_decimal('1.099,98', locale='de')
            1099.98

        When the given string cannot be parsed, an exception is raised::

            >>> parse_decimal('2,109,998', locale='de')
            Traceback (most recent call last):
               ...
            NumberFormatError: '2,109,998' is not a valid decimal number

        :param string:
            The string to parse.
        :returns:
            The parsed decimal number.
        :raises:
            ``NumberFormatError`` if the string can not be converted to a
            decimal number.
        """
        return numbers.parse_decimal(string, locale=self.locale)

    def get_timezone_location(self, dt_or_tzinfo):
        """Returns a representation of the given timezone using "location
        format".

        The result depends on both the local display name of the country and
        the city assocaited with the time zone::

            >>> from pytz import timezone
            >>> tz = timezone('America/St_Johns')
            >>> get_timezone_location(tz, locale='de_DE')
            u"Kanada (St. John's)"
            >>> tz = timezone('America/Mexico_City')
            >>> get_timezone_location(tz, locale='de_DE')
            u'Mexiko (Mexiko-Stadt)'

        If the timezone is associated with a country that uses only a single
        timezone, just the localized country name is returned::

            >>> tz = timezone('Europe/Berlin')
            >>> get_timezone_name(tz, locale='de_DE')
            u'Deutschland'

        :param dt_or_tzinfo:
            The ``datetime`` or ``tzinfo`` object that determines
            the timezone; if None, the current date and time in UTC is assumed.
        :returns:
            The localized timezone name using location format.
        """
        return dates.get_timezone_name(dt_or_tzinfo, locale=self.locale)


def gettext(string, **variables):
    """See :meth:`I18n.gettext`."""
    return get_i18n().gettext(string, **variables)


def ngettext(singular, plural, n, **variables):
    """See :meth:`I18n.ngettext`."""
    return get_i18n().ngettext(singular, plural, n, **variables)


def to_local_timezone(datetime):
    """See :meth:`I18n.to_local_timezone`."""
    return get_i18n().to_local_timezone(datetime)


def to_utc(datetime):
    """See :meth:`I18n.to_utc`."""
    return get_i18n().to_utc(datetime)


def format_date(date=None, format=None, rebase=True):
    """See :meth:`I18n.format_date`."""
    return get_i18n().format_date(date, format, rebase)


def format_datetime(datetime=None, format=None, rebase=True):
    """See :meth:`I18n.format_datetime`."""
    return get_i18n().format_datetime(datetime, format, rebase)


def format_time(time=None, format=None, rebase=True):
    """See :meth:`I18n.format_time`."""
    return get_i18n().format_time(time, format, rebase)


def format_timedelta(datetime_or_timedelta, granularity='second',
    threshold=.85):
    """See :meth:`I18n.format_timedelta`."""
    return get_i18n().format_timedelta(datetime_or_timedelta,
                                       granularity, threshold)


def format_number(number):
    """See :meth:`I18n.format_number`."""
    return get_i18n().format_number(number)


def format_decimal(number, format=None):
    """See :meth:`I18n.format_decimal`."""
    return get_i18n().format_decimal(number, format)


def format_currency(number, currency, format=None):
    """See :meth:`I18n.format_currency`."""
    return get_i18n().format_currency(number, currency, format)


def format_percent(number, format=None):
    """See :meth:`I18n.format_percent`."""
    return get_i18n().format_percent(number, format)


def format_scientific(number, format=None):
    """See :meth:`I18n.format_scientific`."""
    return get_i18n().format_scientific(number, format)


def parse_date(string):
    """See :meth:`I18n.parse_date`"""
    return get_i18n().parse_date(string)


def parse_datetime(string):
    """See :meth:`I18n.parse_datetime`."""
    return get_i18n().parse_datetime(string)


def parse_time(string):
    """See :meth:`I18n.parse_time`."""
    return get_i18n().parse_time(string)


def parse_number(string):
    """See :meth:`I18n.parse_number`."""
    return get_i18n().parse_number(string)


def parse_decimal(string):
    """See :meth:`I18n.parse_decimal`."""
    return get_i18n().parse_decimal(string)


def get_timezone_location(dt_or_tzinfo):
    """See :meth:`I18n.get_timezone_location`."""
    return get_i18n().get_timezone_location(dt_or_tzinfo)


def lazy_gettext(string, **variables):
    """A lazy version of :func:`gettext`.

    :param string:
        The string to be translated.
    :param variables:
        Variables to format the returned string.
    :returns:
        A ``babel.support.LazyProxy`` object that when accessed translates
        the string.
    """
    return support.LazyProxy(gettext, string, **variables)


# Aliases.
_ = gettext
_lazy = lazy_gettext


# Factories -------------------------------------------------------------------


#: Key used to store :class:`I18nStore` in the app registry.
_store_registry_key = 'webapp2_extras.i18n.I18nStore'
#: Key used to store :class:`I18n` in the request registry.
_i18n_registry_key = 'webapp2_extras.i18n.I18n'


def get_store(factory=I18nStore, key=_store_registry_key, app=None):
    """Returns an instance of :class:`I18nStore` from the app registry.

    It'll try to get it from the current app registry, and if it is not
    registered it'll be instantiated and registered. A second call to this
    function will return the same instance.

    :param factory:
        The callable used to build and register the instance if it is not yet
        registered. The default is the class :class:`I18nStore` itself.
    :param key:
        The key used to store the instance in the registry. A default is used
        if it is not set.
    :param app:
        A :class:`webapp2.WSGIApplication` instance used to store the instance.
        The active app is used if it is not set.
    """
    app = app or webapp2.get_app()
    store = app.registry.get(key)
    if not store:
        store = app.registry[key] = factory(app)

    return store


def set_store(store, key=_store_registry_key, app=None):
    """Sets an instance of :class:`I18nStore` in the app registry.

    :param store:
        An instance of :class:`I18nStore`.
    :param key:
        The key used to retrieve the instance from the registry. A default
        is used if it is not set.
    :param request:
        A :class:`webapp2.WSGIApplication` instance used to retrieve the
        instance. The active app is used if it is not set.
    """
    app = app or webapp2.get_app()
    app.registry[key] = store


def get_i18n(factory=I18n, key=_i18n_registry_key, request=None):
    """Returns an instance of :class:`I18n` from the request registry.

    It'll try to get it from the current request registry, and if it is not
    registered it'll be instantiated and registered. A second call to this
    function will return the same instance.

    :param factory:
        The callable used to build and register the instance if it is not yet
        registered. The default is the class :class:`I18n` itself.
    :param key:
        The key used to store the instance in the registry. A default is used
        if it is not set.
    :param request:
        A :class:`webapp2.Request` instance used to store the instance. The
        active request is used if it is not set.
    """
    request = request or webapp2.get_request()
    i18n = request.registry.get(key)
    if not i18n:
        i18n = request.registry[key] = factory(request)

    return i18n


def set_i18n(i18n, key=_i18n_registry_key, request=None):
    """Sets an instance of :class:`I18n` in the request registry.

    :param store:
        An instance of :class:`I18n`.
    :param key:
        The key used to retrieve the instance from the registry. A default
        is used if it is not set.
    :param request:
        A :class:`webapp2.Request` instance used to retrieve the instance. The
        active request is used if it is not set.
    """
    request = request or webapp2.get_request()
    request.registry[key] = i18n