kivy-garden-i18n 0.3.0__py3-none-any.whl

kivy_garden/i18n/fontfinder.py

@@ -0,0 +1,168 @@
+__all__ =(
+    "enum_pre_installed_fonts", "default_filter", "enum_langs", "register_lang",
+    "font_provides_glyphs", "font_supports_lang",
+)
+
+from typing import Union
+from collections.abc import Callable, Iterator
+from pathlib import Path, PurePath
+from kivy.core.text import LabelBase, Label as CoreLabel
+
+
+def default_filter(font: PurePath, suffixes={".ttf", ".otf", ".ttc", ".woff", ".woff2"}) -> bool:
+    '''
+    The default filter for :func:`enum_pre_installed_fonts`.
+
+    Returns True if ``font`` has one of the specified suffixes and its filename
+    does not contain ``"fallback"``.
+    '''
+    return font.suffix in suffixes and "fallback" not in font.name.lower()
+
+
+def enum_pre_installed_fonts(*, filter: Callable[[PurePath], bool]=default_filter) -> Iterator[Path]:
+    for dir in LabelBase.get_system_fonts_dir():
+        for child in Path(dir).iterdir():
+            if filter(child):
+                yield child
+
+
+def font_provides_glyphs(font: str | Path, glyphs: str) -> bool:
+    '''
+    Whether a specified ``font`` provides all of the given ``glyphs``.
+
+    :param glyphs: A string consisting of three or more unique characters.
+
+    .. code-block::
+
+        from kivy_garden.i18n.fontfinder import font_provides_glyphs as f
+
+        # Roboto, Kivy's default font, lacks CJK glyphs.
+        assert f("Roboto", "ABC")
+        assert not f("Roboto", "漢字한글ひら")
+        assert not f("Roboto", "漢字한글ひらABC")
+
+        # NotoSerifCJK provides ASCII and CJK glyphs.
+        assert f("NotoSerifCJK-Regular.ttc", "ABC")
+        assert f("NotoSerifCJK-Regular.ttc", "漢字한글ひら")
+        assert f("NotoSerifCJK-Regular.ttc", "漢字한글ひらABC")
+
+        # Fallback fonts may lack ASCII glyphs.
+        assert not f("DroidSansFallbackFull.ttf", "ABC")
+        assert f("DroidSansFallbackFull.ttf", "漢字한글ひら")
+        assert not f("DroidSansFallbackFull.ttf", "漢字한글ひらABC")
+
+    .. warning::
+
+        This function does not produce 100% accurate results.
+        Providing more glyphs improves accuracy at the cost of execution time.
+    '''
+    if not _validate_discriminant(glyphs):
+        raise ValueError(f"'glyphs' must consist of three or more unique characters (was {glyphs!r})")
+    label = CoreLabel()
+    label._size = (16, 16, )
+    label.options['font_name'] = str(font)
+    label.resolve_font_name()
+    rendered_results = set()
+    for c in glyphs:
+        label.text = c
+        label._render_begin()
+        label._render_text(c, 0, 0)
+        pixels = label._render_end().data
+        if pixels in rendered_results:
+            return False
+        rendered_results.add(pixels)
+    return True
+
+
+DISCRIMINANTS = {
+    'ar': 'الجزيرةAB',
+    'hi': 'भारतAB',
+    'ja': (v := '経伝説あAB'),
+    'ja-JP': v,
+    'ja_JP': v,
+    'ko': (v := '안녕조AB'),
+    'ko-KR': v,
+    'ko_KR': v,
+    'zh-Hans': (v := '哪经传说AB'),
+    'zh_Hans': v,
+    'zh-CN': v,
+    'zh_CN': v,
+    'zh-SG': v,
+    'zh_SG': v,
+    'zh-Hant': (v := '哪經傳說AB'),
+    'zh_Hant': v,
+    'zh-TW': v,
+    'zh_TW': v,
+    'zh-HK': v,
+    'zh_HK': v,
+    'zh-MO': v,
+    'zh_MO': v,
+    'zh': '哪經傳說经传说AB',
+}
+'''
+あるフォントがある言語に対応しているか否かを判定するために使われる辞書。
+辞書の値に含まれている文字全てがフォントに含まれている時のみ、そのフォントは対応する鍵の言語に対応していると見做される。
+'''
+
+
+def font_supports_lang(font: Union[str, Path], lang: str) -> bool:
+    '''
+    Whether a specified ``font`` provides the glyphs required for a specified ``lang``.
+
+    .. code-block::
+
+        from kivy_garden.i18n.fontfinder import font_supports_lang as f
+
+        assert not f("Roboto", "zh")
+        assert not f("Roboto", "ko")
+        assert not f("Roboto", "ja")
+
+        assert f("NotoSerifCJK-Regular.ttc", "zh")
+        assert f("NotoSerifCJK-Regular.ttc", "ko")
+        assert f("NotoSerifCJK-Regular.ttc", "ja")
+
+        # A font that lacks ASCII characters is considered unable to support any language.
+        assert not f("DroidSansFallbackFull.ttf", "zh")
+        assert not f("DroidSansFallbackFull.ttf", "ko")
+        assert not f("DroidSansFallbackFull.ttf", "ja")
+
+    .. warning::
+
+        This function does not produce 100% accurate results.
+    '''
+    try:
+        glyphs = DISCRIMINANTS[lang]
+    except KeyError:
+        raise ValueError(f"Unable to check language support: {lang = }.\n"
+                         "Register the language first using 'register_lang' function.")
+    return font_provides_glyphs(font, glyphs)
+
+
+def enum_langs() -> Iterator[str]:
+    '''
+    Available languages for :func:`font_supports_lang`.
+    '''
+    return DISCRIMINANTS.keys()
+
+
+def register_lang(lang: str, discriminant: str):
+    '''
+    Enables a language in the :func:`font_supports_lang`.
+
+    .. code-block::
+
+        register_lang('th', "ราชอAB")  # Thai language
+    '''
+    if not _validate_discriminant(discriminant):
+        raise ValueError(f"'discriminant' must consist of three or more unique characters (was {discriminant!r})")
+    DISCRIMINANTS[lang] = discriminant
+
+
+def _validate_discriminant(discriminant: str, len=len, set=set) -> bool:
+    l = len(discriminant)
+    return l >= 3 and len(set(discriminant)) == l
+
+
+# Aliases for backward compatibility
+can_render_text = font_provides_glyphs
+can_render_lang = font_supports_lang

kivy_garden/i18n/localizer.py

@@ -0,0 +1,237 @@
+__all__ = (
+    # type hints
+    "Translator", "TranslatorFactory", "FontPicker",
+
+    # exceptions
+    "FontNotFoundError",
+
+    # concrete TranslatorFactory
+    "GettextBasedTranslatorFactory", "MappingBasedTranslatorFactory",
+
+    # concrete FontPicker
+    "DefaultFontPicker",
+
+    #
+    "Localizer",
+)
+
+from collections.abc import Callable, Mapping
+from typing import TypeAlias, Union
+import itertools
+from functools import cached_property
+
+from kivy.properties import StringProperty, ObjectProperty
+from kivy.event import EventDispatcher
+from kivy.logger import Logger
+from kivy.uix.label import Label
+
+from .fontfinder import enum_pre_installed_fonts, font_supports_lang
+
+Msgid: TypeAlias = str
+Msgstr: TypeAlias = str
+Lang: TypeAlias = str
+Translator: TypeAlias = Callable[[Msgid], Msgstr]
+TranslatorFactory : TypeAlias = Callable[[Lang], Translator]
+Font: TypeAlias = str
+FontPicker: TypeAlias = Callable[[Lang], Font]
+
+
+class FontNotFoundError(Exception):
+    @cached_property
+    def lang(self) -> Lang:
+        '''The language for which a localizer couldn't find a suitable font.'''
+        return self.args[0]
+
+
+class Localizer(EventDispatcher):
+    lang: Lang = StringProperty()
+    '''
+    The "current language" of this localizer.
+    '''
+
+    _: Translator = ObjectProperty(lambda msgid: msgid)
+    '''
+    (read-only)
+    A callable object that takes a ``msgid``, and returns the corresponging ``msgstr`` according to the "current language".
+
+    .. code-block::
+
+        loc = Localizer(...)
+        loc.lang = "en"
+        print(loc._("app title"))  # => "My First Kivy Program"
+        loc.lang = "ja"
+        print(loc._("app title"))  # => "初めてのKivyプログラム"
+
+    :meta public:
+    '''
+
+    font_name: Font = StringProperty(Label.font_name.defaultvalue)
+    '''
+    (read-only)
+    A font that provides the glyphs required for rendering the "current language".
+
+    .. code-block::
+
+        loc = Localizer(...)
+        loc.lang = "en"
+        print(loc.font_name)  # => "Roboto"
+        loc.lang = "ko"
+        print(loc.font_name)  # => "<a pre-installed Korean font>"
+    '''
+
+    def __init__(self, translator_factory: TranslatorFactory=None, *, lang: Lang='en', font_picker: FontPicker=None):
+        if translator_factory is None:
+            Logger.warning(f"kivy_garden.i18n: No translator_factory was provided. Msgid's themselves will be displayed.")
+            translator_factory = lambda lang: lambda msgid: msgid
+        if font_picker is None:
+            font_picker = DefaultFontPicker()
+        self.translator_factory = translator_factory
+        self.font_picker = font_picker
+        super().__init__(lang=lang)
+
+    def install(self, *, name):
+        '''
+        Makes the localizer accessble from kv without any import-statements.
+
+        .. code-block::
+
+            loc = Localizer(...)
+            loc.install(name='l')
+
+        .. code-block:: yaml
+
+            Label:
+                font_name: l.font_name
+                text: l._("msgid")
+
+        :raises ValueError: if the ``name`` has already been used.
+        '''
+        from kivy.lang import global_idmap
+        if name in global_idmap:
+            raise ValueError(f"The name {name!r} has already been used.")
+        global_idmap[name] = self
+
+    def uninstall(self, *, name):
+        from kivy.lang import global_idmap
+        if name not in global_idmap:
+            raise ValueError(f"The name {name!r} not found.")
+        if global_idmap[name] is not self:
+            raise ValueError(f"The object referenced by {name!r} is not me.")
+        del global_idmap[name]
+
+    @staticmethod
+    def on_lang(self, lang):
+        ''':meta private:'''
+        self._ = self.translator_factory(lang)
+        self.font_name = self.font_picker(lang)
+
+
+class DefaultFontPicker:
+    PRESET = {
+        "en": (v := "Roboto"),
+        "fr": v,
+        "it": v,
+        "pt": v,
+        "ru": v,
+    }
+    ''':meta private:'''
+
+    del v
+
+    def __init__(self, *, fallback: Union[Lang, None]="Roboto"):
+        self._lang2font = self.PRESET.copy()
+        self._fallback = fallback
+
+    def __call__(self, lang: Lang) -> Font:
+        try:
+            return self._lang2font[lang]
+        except KeyError:
+            pass
+
+        name = None
+        for font in enum_pre_installed_fonts():
+            if font_supports_lang(font, lang):
+                name = font.name
+                break
+        if name is None:
+            fallback = self._fallback
+            if fallback is None:
+                raise FontNotFoundError(lang)
+            Logger.warning(f"kivy_garden.i18n: Couldn't find a font for lang '{lang}'. Use {fallback} as a fallback.")
+            name = fallback
+        self._lang2font[lang] = name
+        return name
+
+
+class GettextBasedTranslatorFactory:
+    def __init__(self, domain, localedir):
+        self.domain = domain
+        self.localedir = localedir
+
+    def __call__(self, lang: Lang) -> Translator:
+        from gettext import translation
+        return translation(domain=self.domain, localedir=self.localedir, languages=(lang, )).gettext
+
+
+class MappingBasedTranslatorFactory:
+    def __init__(self, translations: Mapping[Msgid, Mapping[Lang, Msgstr]], /, strict=False):
+        '''
+        :param strict:
+            If False (default), a missing translation falls back to the ``msgid`` itself.
+            If True, a missing translation raises ``ValueError``.
+        '''
+        self._compiled_translations = self._compile_translations(translations, strict=strict)
+
+    def __call__(self, lang: Lang) -> Translator:
+        return self._compiled_translations[lang].__getitem__
+
+    @staticmethod
+    def _compile_translations(d: Mapping[Msgid, Mapping[Lang, Msgstr]], *, strict) -> dict[Lang, dict[Msgid, Msgstr]]:
+        '''
+        アプリ開発者側にとって嬉しいのは次のような形式の翻訳表だと思うが
+
+        .. code-block::
+
+            翻訳表 = {
+                "greeting": {
+                    "ja": "おはよう",
+                    "en": "morning",
+                },
+                "app title": {
+                    "ja": "初めてのKivyプログラム",
+                    "en": "My First Kivy App",
+                },
+            }
+
+        ライブラリが内部で持ちたいのは次の形式の翻訳表である。
+
+        .. code-block::
+
+            翻訳表 = {
+                "ja": {
+                    "greeting": "おはよう",
+                    "app title": "初めてのKivyプログラム",
+                },
+                "en": {
+                    "greeting": "morning",
+                    "app title": "My First Kivy App",
+                },
+            }
+
+        この関数は前者を後者に変換する。
+        '''
+        msgids = tuple(d.keys())
+        langs = set(itertools.chain.from_iterable(d.values()))
+        if strict:
+            try:
+                return {
+                    lang: {msgid: d[msgid][lang] for msgid in msgids}
+                    for lang in langs
+                }
+            except KeyError as e:
+                raise ValueError(f"Msgid '{e.args[0]}' is missing one or more translations") from e
+        else:
+            return {
+                lang: {msgid: d[msgid].get(lang, msgid) for msgid in msgids}
+                for lang in langs
+            }

kivy_garden/i18n/utils/__init__.py

@@ -0,0 +1 @@
+from ._extract_msgids_from_string_literals import extract_msgids_from_string_literals

kivy_garden/i18n/utils/_extract_msgids_from_string_literals.py

@@ -0,0 +1,64 @@
+__all__ = ('extract_msgids_from_string_literals', )
+
+import re
+from typing import Iterator
+
+
+def extract_string_literals(python_code: str) -> Iterator[str]:
+    from ast import parse, walk, Constant
+    str_ = str
+    isinstance_ = isinstance
+    for node in walk(parse(python_code)):
+        if isinstance_(node, Constant) and isinstance_(node.value, str_):
+            yield node.value
+
+
+PATTERN = re.compile(r"""
+    (^|\W)_\("(.*?)"\)  # _("")で括られた文字列
+    |                   # もしくは
+    (^|\W)_\('(.*?)'\)  # _('')で括られた文字列
+""", re.VERBOSE | re.MULTILINE)
+
+
+def extract_msgid(s:str) -> Iterator[str]:
+    for m in PATTERN.finditer(s):
+        yield (m.group(2) or m.group(4))
+
+
+def extract_msgids_from_string_literals(python_code: str) -> Iterator[str]:
+    '''
+    .. code-block::
+
+        msgids = extract_msgids_from_string_literals("""
+            Label:
+                font_name: _("AAA")
+                text: _("BBB")
+            """)
+        assert list(msgids) == ["AAA", "BBB"]
+    '''
+    return (
+        ls
+        for s in extract_string_literals(python_code)
+        for ls in extract_msgid(s)
+    )
+
+
+def cli_main():
+    from textwrap import dedent
+    import sys
+    from pathlib import Path
+    from io import StringIO
+
+    if len(sys.argv) == 1:
+        print(dedent("""
+            Usage:
+                extract-msgids filename1.py filename2.py ...
+            """),
+            file=sys.stderr)
+        return
+    output = StringIO()
+    for file in sys.argv[1:]:
+        for ls in extract_msgids_from_string_literals(Path(file).read_text(encoding='utf-8')):
+            print(ls, file=output)
+    print(output.getvalue())
+    output.close()

kivy_garden_i18n-0.3.0.dist-info/METADATA

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: kivy-garden-i18n
+Version: 0.3.0
+Summary: i18n for Kivy
+Keywords: kivy
+Author: Nattōsai Mitō
+Author-email: Nattōsai Mitō <flow4re2c@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10, <4.0
+Project-URL: Repository, https://github.com/gottadiveintopython/i18n
+Project-URL: Documentation, https://gottadiveintopython.github.io/i18n/
+Description-Content-Type: text/markdown
+
+# kivy_garden.i18n
+
+Internationalization support for Kivy applications.
+
+```python
+from kivy_garden.i18n.localizer import MappingBasedTranslatorFactory, Localizer
+
+translations = {
+    "greeting": {
+        "ja": "おはよう",
+        "en": "morning",
+    },
+    "app title": {
+        "ja": "初めてのKivyプログラム",
+        "en": "My First Kivy App",
+    },
+}
+localizer = Localizer(MappingBasedTranslatorFactory(translations))
+
+l = localizer
+l.lang = "en"  # Set the "current language" to "en"
+assert l.font_name == "Roboto"
+assert l._("greeting") == "morning"
+assert l._("app title") == "My First Kivy App"
+
+l.lang = "ja"
+assert l.font_name == "<a pre-installed Japanese font>"
+assert l._("greeting") == "おはよう"
+assert l._("app title") == "初めてのKivyプログラム"
+```
+
+Bindings:
+
+```python
+from kivy.lang import Builder
+
+localizer.install(name="l")
+label = Builder.load_string("""
+Label:
+    font_name: l.font_name
+    text: l._("greeting")
+""")
+localizer.lang = "en"
+assert label.font_name == "Roboto"
+assert label.text == "morning"
+localizer.lang = "ja"
+assert label.font_name == "<a pre-installed Japanese font>"
+assert label.text == "おはよう"
+```
+
+# Installation
+
+Pin the minor version.
+
+```
+pip install "kivy-garden-i18n>=0.3,<0.4"
+```
+
+# Tested on
+
+- CPython 3.10 + Kivy 2.3
+- CPython 3.11 + Kivy 2.3
+- CPython 3.12 + Kivy 2.3
+- CPython 3.13 + Kivy 2.3

kivy_garden_i18n-0.3.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+kivy_garden/i18n/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kivy_garden/i18n/fontfinder.py,sha256=aQkQcKPM3dFWugwVK1qUYiY3pS2crmuTM_jGaBvIkPY,5474
+kivy_garden/i18n/localizer.py,sha256=956llaf2yk09cN7EjWVWf7sJD9LyMGUJmgXkCh_UFCI,7350
+kivy_garden/i18n/utils/__init__.py,sha256=EaG7vkSf72tc6GAV_v0TqA2urlMOyKaXsF48zuS4afA,86
+kivy_garden/i18n/utils/_extract_msgids_from_string_literals.py,sha256=min0LFN3XZ9RAP-4F-c7js9EHeZxSBCDYt_IMrRVyG0,1708
+kivy_garden_i18n-0.3.0.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
+kivy_garden_i18n-0.3.0.dist-info/entry_points.txt,sha256=1HK5Z_gLLUsXJIYxBV3Zbjk7z2rRR14OUT6us33SkQI,105
+kivy_garden_i18n-0.3.0.dist-info/METADATA,sha256=XtJk6YimSzIRs4ApJ_NFu0nKPUp4GhiuUUsxYX1kuBU,2342
+kivy_garden_i18n-0.3.0.dist-info/RECORD,,

kivy_garden_i18n-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.26
+Root-Is-Purelib: true
+Tag: py3-none-any

kivy_garden_i18n-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+extract-msgids = kivy_garden.i18n.utils._extract_msgids_from_string_literals:cli_main
+