cherrypy-foundation 1.0.0__py3-none-any.whl → 1.0.0a1__py3-none-any.whl

cherrypy_foundation/tools/i18n.py

@@ -1,5 +1,5 @@
 # Internationalisation tool for cherrypy
-# Copyright (C) 2012-2026 IKUS Software
+# Copyright (C) 2012-2025 Patrik Dufresne
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -14,116 +14,95 @@
 # You should have received a copy of the GNU General Public License
 # along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
-"""
-Internationalization (i18n) and Localization (l10n) support for CherryPy.
-
-This module provides a CherryPy tool that integrates GNU gettext and Babel
-to handle language selection, translations, locale-aware formatting, and
-timezone handling on a per-request basis.
-
-The active language is resolved in the following order (highest priority first):
+"""Internationalization and Localization for CherryPy
 
-1. Language explicitly set with ``with i18n.preferred_lang():``
-2. User-defined callback (``tools.i18n.func``)
-3. HTTP ``Accept-Language`` request header
-4. Default language configured via ``tools.i18n.default``
+This tool provides locales and loads translations in the following order:
 
-Translations are loaded using Babel and gettext, and the resolved locale is
-available through ``i18n.get_translation()`` during request handling.
+1. `with i18n.preferred_lang()`
+2. `tools.i18n.func` callback function (optional)
+3. HTTP Accept-Language headers
+4. `tools.i18n.default` value
 
----------------------------------------------------------------------------
-Basic usage
----------------------------------------------------------------------------
+The tool uses `babel` <http://babel.edgewall.org> for localization and
+handling translations. Within your Python code you can use four functions
+defined in this module and the loaded locale provided as `i18n.get_translation()`
 
-Within Python code, mark translatable strings using ``ugettext`` or
-``ungettext``:
+Example::
 
-    from i18n import gettext as _, ngettext
+    from i18n import ugettext as _, ungettext
 
-    class MyController:
+    class MyController(object):
         @cherrypy.expose
         def index(self):
             locale = cherrypy.response.i18n.locale
-            s1 = _(u"Translatable string")
-            s2 = ngettext(
-                u"There is one item.",
-                u"There are multiple items.",
-                2
-            )
-            return "<br />".join([s1, s2, locale.display_name])
+            s1 = _(u'Translateable string')
+            s2 = ungettext(u'There is one string.',
+                           u'There are more strings.', 2)
+            return u'<br />'.join([s1, s2, locale.display_name])
 
----------------------------------------------------------------------------
-Lazy translations
----------------------------------------------------------------------------
+If you have code (e.g. database models) that is executed before the response
+object is available, use the *_lazy functions to mark the strings
+translateable. They will be translated later on, when the text is used (and
+hopefully the response object is available then).
 
-If code is executed before a CherryPy response object is available
-(e.g. model definitions or module-level constants), use the ``*_lazy``
-helpers. These defer translation until the value is actually rendered:
+Example::
 
-    from i18n_tool import gettext_lazy
+    from i18n_tool import ugettext_lazy
 
     class Model:
-        name = gettext_lazy(u"Model name")
+        def __init__(self):
+            name = ugettext_lazy(u'Name of the model')
 
----------------------------------------------------------------------------
-Templates
----------------------------------------------------------------------------
+For your templates read the documentation of your template engine how to
+integrate babel with it. I think `Genshi<http://genshi.edgewall.org>`_ and
+`Jinja 2<http://jinja.pocoo.org`_ support it out of the box.
 
-For template rendering, i18n integrate with jinja2.
 
-    {% trans %}Text to translate{% endtrans %}
-    {{ _('Text to translate') }}
-    {{ get_translation().gettext('Text to translate') }}
-    {{ get_translation().locale }}
-    {{ var | format_datetime(format='full') }}
-    {{ var | format_date(format='full') }}
+Settings for the CherryPy configuration::
+
+    [/]
+    tools.i18n.on = True
+    tools.i18n.default = Your language with territory (e.g. 'en_US')
+    tools.i18n.mo_dir = Directory holding the locale directories
+    tools.i18n.domain = Your gettext domain (e.g. application name)
 
----------------------------------------------------------------------------
-Configuration
----------------------------------------------------------------------------
+The mo_dir must contain subdirectories named with the language prefix
+for all translations, containing a LC_MESSAGES dir with the compiled
+catalog file in it.
 
-Example CherryPy configuration:
+Example::
 
     [/]
     tools.i18n.on = True
-    tools.i18n.default = "en_US"
-    tools.i18n.mo_dir = "/path/to/i18n"
-    tools.i18n.domain = "myapp"
+    tools.i18n.default = 'en_US'
+    tools.i18n.mo_dir = '/home/user/web/myapp/i18n'
+    tools.i18n.domain = 'myapp'
 
-The ``mo_dir`` directory must contain subdirectories named after language
-codes (e.g. ``en``, ``fr_CA``), each containing an ``LC_MESSAGES`` directory
-with the compiled ``.mo`` file:
+    Now the tool will look for a file called myapp.mo in
+    /home/user/web/myapp/i18n/en/LC_MESSACES/
+    or generic: <mo_dir>/<language>/LC_MESSAGES/<domain>.mo
 
-    <mo_dir>/<language>/LC_MESSAGES/<domain>.mo
+That's it.
 
+:License: BSD
+:Author: Thorsten Weimann <thorsten.weimann (at) gmx (dot) net>
+:Date: 2010-02-08
 """
 
-import logging
+
 import os
+import threading
 from contextlib import contextmanager
-from contextvars import ContextVar
 from functools import lru_cache
-from gettext import NullTranslations, translation
 
 import cherrypy
 import pytz
 from babel import dates
 from babel.core import Locale, get_global
-from babel.support import LazyProxy, Translations
-
-_preferred_lang = ContextVar('preferred_lang', default=())
-_preferred_timezone = ContextVar('preferred_timezone', default=())
-_translation = ContextVar('translation', default=None)
-_tzinfo = ContextVar('tzinfo', default=None)
-
+from babel.support import LazyProxy, NullTranslations, Translations
 
-def _get_config(key, default=None):
-    """
-    Lookup configuration from request, if available. Fallback to global config.
-    """
-    if getattr(cherrypy, 'request') and getattr(cherrypy.request, 'config') and key in cherrypy.request.config:
-        return cherrypy.request.config[key]
-    return cherrypy.config.get(key, default)
+# Store current translation and preferred_lang
+_current = threading.local()
 
 
 @contextmanager
@@ -134,20 +113,21 @@ def preferred_lang(lang):
     with i18n.preferred_lang('fr'):
         i18n.gettext('some string')
     """
-    if not (lang is None or isinstance(lang, str)):
-        raise ValueError(lang)
+    assert lang is None or isinstance(lang, str)
+    prev_lang = getattr(_current, 'preferred_lang', [])
+    prev_trans = getattr(_current, 'translation', None)
     try:
-        # Update preferred lang and clear translation.
+        # Update prefered lang and clear translation.
         if lang:
-            token_l = _preferred_lang.set((lang,))
-        else:
-            token_l = _preferred_lang.set(tuple())
-        token_t = _translation.set(None)
+            _current.preferred_lang = [lang]
+        elif hasattr(_current, 'preferred_lang'):
+            del _current.preferred_lang
+        _current.translation = None
         yield
     finally:
         # Restore previous value
-        _preferred_lang.reset(token_l)
-        _translation.reset(token_t)
+        _current.preferred_lang = prev_lang
+        _current.translation = prev_trans
 
 
 @contextmanager
@@ -158,24 +138,22 @@ def preferred_timezone(timezone):
     with i18n.preferred_lang('America/Montreal'):
         i18n.format_datetime(...)
     """
-    if not (timezone is None or isinstance(timezone, str)):
-        raise ValueError(timezone)
+    assert timezone is None or isinstance(timezone, str)
+    prev_timezone = getattr(_current, 'preferred_timezone', [])
+    prev_tzinfo = getattr(_current, 'tzinfo', None)
     try:
-        # Update preferred timezone and clear tzinfo.
-        if timezone:
-            token_t = _preferred_timezone.set((timezone,))
-        else:
-            token_t = _preferred_timezone.set(tuple())
-        token_z = _tzinfo.set(None)
+        # Update prefered lang and clear translation.
+        _current.preferred_timezone = [timezone] + prev_timezone
+        _current.tzinfo = None
         yield
     finally:
         # Restore previous value
-        _preferred_timezone.reset(token_t)
-        _tzinfo.reset(token_z)
+        _current.preferred_timezone = prev_timezone
+        _current.tzinfo = prev_tzinfo
 
 
-@lru_cache(maxsize=32)
-def _search_translation(dirname, domain, *locales, sourcecode_lang='en'):
+@lru_cache(maxsize=10)
+def _search_translation(dirname, domain, *langs):
     """
     Loads the first existing translations for known locale.
 
@@ -183,37 +161,22 @@ def _search_translation(dirname, domain, *locales, sourcecode_lang='en'):
         langs : List
             List of languages as returned by `parse_accept_language_header`.
         dirname : String
-            A single directory of the translations (`tools.i18n.mo_dir`).
+            Directory of the translations (`tools.I18nTool.mo_dir`).
+            Might be a list of directories.
         domain : String
-            Gettext domain of the catalog (`tools.i18n.domain`).
+            Gettext domain of the catalog (`tools.I18nTool.domain`).
 
     :returns: Translations, the corresponding Locale object.
     """
-    if not isinstance(locales, (list, tuple)):
-        locales = tuple(locales)
-
-    # Loop on each locales to find the best matching translation.
-    for locale in locales:
-        try:
-            # Use `gettext.translation()` instead of `gettext.find()` to chain translation fr_CA -> fr -> src.
-            t = translation(domain=domain, localedir=dirname, languages=[locale], fallback=True, class_=Translations)
-        except Exception:
-            # If exception occur while loading the translation file. The file is probably corrupted.
-            cherrypy.log(
-                f'failed to load gettext catalog domain={domain} localedir={dirname} locale={locale}',
-                context='I18N',
-                severity=logging.WARNING,
-                traceback=True,
-            )
-            continue
-        if t.__class__ is NullTranslations and not locale.startswith(sourcecode_lang):
-            # Continue searching if translation is not found.
-            continue
-        t.locale = Locale.parse(locale)
-        return t
-    # If translation file not found, return default
-    t = NullTranslations()
-    t.locale = Locale(sourcecode_lang)
+    if not isinstance(langs, (list, tuple)):
+        langs = [langs]
+    t = Translations.load(dirname, langs, domain)
+    # Ignore null translation
+    if t.__class__ is NullTranslations:
+        return None
+    # Get Locale from file name
+    lang = t.files[0].split('/')[-3]
+    t.locale = Locale.parse(lang)
     return t
 
 
@@ -221,37 +184,23 @@ def get_language_name(lang_code):
     """
     Translate the language code into it's language display name.
     """
-    try:
-        locale = Locale.parse(lang_code)
-    except Exception:
-        return lang_code
-    translation = get_translation()
-    return locale.get_language_name(translation.locale)
+    locale = Locale.parse(lang_code)
+    trans = get_translation()
+    return locale.get_language_name(trans.locale)
 
 
 def get_timezone():
     """
     Get the best timezone information for the current context.
-
-    The timezone returned is determined with the following priorities:
-
-    * value of preferred_timezone()
-    * tools.i18n.default_timezone
-    * default server time.
-
     """
     # When tzinfo is defined, use it
-    tzinfo = _tzinfo.get()
+    tzinfo = getattr(_current, 'tzinfo', None)
     if tzinfo is not None:
         return tzinfo
     # Otherwise search for a valid timezone.
-    default = _get_config('tools.i18n.default_timezone')
-    preferred_timezone = _preferred_timezone.get()
-    if default and default not in preferred_timezone:
-        preferred_timezone = (
-            *preferred_timezone,
-            default,
-        )
+    tzinfo = None
+    default_timezone = cherrypy.config.get('tools.i18n.default_timezone')
+    preferred_timezone = getattr(_current, 'preferred_timezone', [default_timezone])
     for timezone in preferred_timezone:
         try:
             tzinfo = dates.get_timezone(timezone)
@@ -261,8 +210,8 @@ def get_timezone():
     # If we can't find a valid timezone using the default and preferred value, fall back to server timezone.
     if tzinfo is None:
         tzinfo = dates.get_timezone(None)
-    _tzinfo.set(tzinfo)
-    return tzinfo
+    _current.tzinfo = tzinfo
+    return _current.tzinfo
 
 
 def get_translation():
@@ -270,48 +219,37 @@ def get_translation():
     Get the best translation for the current context.
     """
     # When translation is defined, use it
-    translation = _translation.get()
+    translation = getattr(_current, 'translation', None)
     if translation is not None:
         return translation
 
     # Otherwise, we need to search the translation.
     # `preferred_lang` should always has a sane value within a cherrypy request because of hooks
     # But we also need to support calls outside cherrypy.
-    sourcecode_lang = _get_config('tools.i18n.sourcecode_lang', 'en')
-    default = _get_config('tools.i18n.default')
-    preferred_lang = _preferred_lang.get()
-    if default and default not in preferred_lang:
-        preferred_lang = (
-            *preferred_lang,
-            default,
-        )
-    mo_dir = _get_config('tools.i18n.mo_dir')
-    domain = _get_config('tools.i18n.domain', 'messages')
-    translation = _search_translation(mo_dir, domain, *preferred_lang, sourcecode_lang=sourcecode_lang)
-    _translation.set(translation)
-    return translation
+    default = cherrypy.config.get('tools.i18n.default')
+    preferred_lang = getattr(_current, 'preferred_lang', [default])
+    mo_dir = cherrypy.config.get('tools.i18n.mo_dir')
+    domain = cherrypy.config.get('tools.i18n.domain')
+    trans = _search_translation(mo_dir, domain, *preferred_lang)
+    if trans is None:
+        trans = NullTranslations()
+        trans.locale = Locale('en')
+    _current.translation = trans
+    return _current.translation
 
 
 def list_available_locales():
     """
     Return a list of available translations.
     """
-    return_value = []
-    # Always return the source code locale.
-    sourcecode_lang = _get_config('tools.i18n.sourcecode_lang', 'en')
-    return_value.append(Locale.parse(sourcecode_lang))
-    # Then scan language directory for more translation.
-    mo_dir = _get_config('tools.i18n.mo_dir')
-    domain = _get_config('tools.i18n.domain', 'messages')
+    mo_dir = cherrypy.config.get('tools.i18n.mo_dir', False)
+    domain = cherrypy.config.get('tools.i18n.domain')
     if not mo_dir:
         return
     for lang in os.listdir(mo_dir):
-        if os.path.exists(os.path.join(mo_dir, lang, 'LC_MESSAGES', f'{domain}.mo')):
-            try:
-                return_value.append(Locale.parse(lang))
-            except Exception:
-                continue
-    return return_value
+        trans = _search_translation(mo_dir, domain, lang)
+        if trans is not None:
+            yield trans.locale
 
 
 def list_available_timezones():
@@ -324,7 +262,7 @@ def list_available_timezones():
 
 
 # Public translation functions
-def gettext(message):
+def ugettext(message):
     """Standard translation function. You can use it in all your exposed
     methods and everywhere where the response object is available.
 
@@ -335,13 +273,13 @@ def gettext(message):
     :returns: The translated message.
     :rtype: Unicode
     """
-    return get_translation().gettext(message)
+    return get_translation().ugettext(message)
 
 
-ugettext = gettext
+gettext = ugettext
 
 
-def ngettext(singular, plural, num):
+def ungettext(singular, plural, num):
     """Like ugettext, but considers plural forms.
 
     :parameters:
@@ -356,29 +294,34 @@ def ngettext(singular, plural, num):
     :returns: The translated message as singular or plural.
     :rtype: Unicode
     """
-    return get_translation().ngettext(singular, plural, num)
+    return get_translation().ungettext(singular, plural, num)
 
 
-ungettext = ngettext
+ngettext = ungettext
 
 
 def gettext_lazy(message):
-    """Like gettext, but lazy.
+    """Like ugettext, but lazy.
 
     :returns: A proxy for the translation object.
     :rtype: LazyProxy
     """
 
     def func():
-        return get_translation().gettext(message)
+        return get_translation().ugettext(message)
 
     return LazyProxy(func, enable_cache=False)
 
 
 def format_datetime(datetime=None, format='medium', tzinfo=None):
     """
-    Wrapper around babel format_datetime to use current locale and current timezone.
+    Wraper arround babel format_datetime to provide a default locale.
+    The timezone used to format the date is determine with the following priorities:
+    * value of tzinfo
+    * value of get_timezone()
+    * default server time.
     """
+    # When formating date or english, let use en_GB as it's to most complete translation.
     return dates.format_datetime(
         datetime=datetime,
         format=format,
@@ -389,19 +332,14 @@ def format_datetime(datetime=None, format='medium', tzinfo=None):
 
 def format_date(datetime=None, format='medium', tzinfo=None):
     """
-    Wrapper around babel format_date to provide a default locale.
+    Wraper arround babel format_date to provide a default locale.
     """
-    # To enforce the timezone and locale, make use of format_datetime for dates.
-    return dates.format_datetime(
-        datetime=datetime,
-        format=dates.get_date_format(format),
-        locale=get_translation().locale,
-        tzinfo=tzinfo or get_timezone(),
-    )
+    return format_datetime(datetime=datetime, format=dates.get_date_format(format), tzinfo=tzinfo)
 
 
-def get_timezone_name(tzinfo, width='long'):
-    return dates.get_timezone_name(tzinfo, width=width, locale=get_translation().locale)
+def get_timezone_name(tzinfo):
+    locale = Locale(get_translation().locale.language)
+    return dates.get_timezone_name(tzinfo, width='long', locale=locale)
 
 
 def _load_default(mo_dir, domain, default, **kwargs):
@@ -409,60 +347,35 @@ def _load_default(mo_dir, domain, default, **kwargs):
     Initialize the language using the default value from the configuration.
     """
     # Clear current translation
-    _preferred_lang.set(tuple())
-    _preferred_timezone.set(tuple())
+    _current.preferred_lang = [default]
+    _current.preferred_timezone = [kwargs['default_timezone']] if 'default_timezone' in kwargs else []
+    cherrypy.request._i18n_lang_func = kwargs.get('lang', kwargs.get('func', False))
+    cherrypy.request._i18n_tzinfo_func = kwargs.get('tzinfo', False)
     # Clear current translation
-    _translation.set(None)
+    _current.translation = None
     # Clear current timezone
-    _tzinfo.set(None)
+    _current.tzinfo = None
 
 
 def _load_accept_language(**kwargs):
     """
-    When running within a request, load the preferred language from Accept-Language header.
-    """
-    if cherrypy.request.headers.elements('Accept-Language'):
-        # Sort language by quality
-        languages = sorted(cherrypy.request.headers.elements('Accept-Language'), key=lambda x: x.qvalue, reverse=True)
-        _preferred_lang.set(tuple(lang.value.replace('-', '_') for lang in languages))
-        # Clear current translation
-        _translation.set(None)
-
-
-def _load_cookie_language(**kwargs):
-    """
-    Load preferred language from a request cookie.
-
-    Expected cookie value formats:
-    - en
-    - en_US
-    - en-US
+    When running within a request, load the prefered language from Accept-Language
     """
-    # Skip this step if cookie name is not defined.
-    cookie_name = _get_config('tools.i18n.cookie_name')
-    if not cookie_name:
-        return
-
-    # Check if value defined in cookie.
-    cookie = cherrypy.request.cookie
-    if cookie_name not in cookie:
-        return
-
-    try:
-        value = cookie[cookie_name].value.replace('-', '_')
-    except Exception:
-        return
 
-    # Set preferred language and clear cached translation
-    _preferred_lang.set((value,))
-    _translation.set(None)
+    if cherrypy.request.headers.elements('Accept-Language'):
+        count = 0
+        for x in cherrypy.request.headers.elements('Accept-Language'):
+            _current.preferred_lang.insert(count, x.value.replace('-', '_'))
+            count += 1
+    # Clear current translation
+    _current.translation = None
 
 
 def _load_func_language(**kwargs):
     """
-    When running a request where a current user is found, load preferred language from user preferences.
+    When running a request where a current user is found, load prefered language from user preferences.
     """
-    func = _get_config('tools.i18n.lang', default=_get_config('tools.i18n.func'))
+    func = getattr(cherrypy.request, '_i18n_lang_func', False)
     if not func:
         return
     try:
@@ -472,16 +385,16 @@ def _load_func_language(**kwargs):
     if not lang:
         return
     # Add custom lang to preferred_lang
-    _preferred_lang.set((lang,))
+    _current.preferred_lang.insert(0, lang)
     # Clear current translation
-    _translation.set(None)
+    _current.translation = None
 
 
 def _load_func_tzinfo(**kwargs):
     """
-    When running a request, load the preferred timezone information from user preferences.
+    When running a request, load the prefered timezone information from user preferences.
     """
-    func = _get_config('tools.i18n.tzinfo')
+    func = getattr(cherrypy.request, '_i18n_tzinfo_func', False)
     if not func:
         return
     try:
@@ -491,9 +404,9 @@ def _load_func_tzinfo(**kwargs):
     if not tzinfo:
         return
     # Add custom lang to preferred_lang
-    _preferred_timezone.set((tzinfo,))
+    _current.preferred_timezone.insert(0, tzinfo)
     # Clear current translation
-    _tzinfo.set(None)
+    _current.tzinfo = None
 
 
 def _set_content_language(**kwargs):
@@ -502,12 +415,7 @@ def _set_content_language(**kwargs):
     language of `cherrypy.response.i18n.locale`.
     """
     if 'Content-Language' not in cherrypy.response.headers:
-        # Only define the content language if the handler uses i18n module.
-        translation = _translation.get()
-        if translation:
-            locale = translation.locale
-            language_tag = f"{locale.language}-{locale.territory}" if locale.territory else locale.language
-            cherrypy.response.headers['Content-Language'] = language_tag
+        cherrypy.response.headers['Content-Language'] = str(get_translation().locale)
 
 
 class I18nTool(cherrypy.Tool):
@@ -520,7 +428,6 @@ class I18nTool(cherrypy.Tool):
         cherrypy.Tool._setup(self)
         # Attach additional hooks as different priority to update preferred lang with more accurate preferences.
         cherrypy.request.hooks.attach('before_handler', _load_accept_language, priority=60)
-        cherrypy.request.hooks.attach('before_handler', _load_cookie_language, priority=70)
         cherrypy.request.hooks.attach('before_handler', _load_func_language, priority=75)
         cherrypy.request.hooks.attach('before_handler', _load_func_tzinfo, priority=75)
         cherrypy.request.hooks.attach('before_finalize', _set_content_language)