aiogram_i18n 1.5__tar.gz

aiogram_i18n-1.5/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: aiogram_i18n
+Version: 1.5
+Summary: Translation tool for aiogram
+Keywords: telegram,bot,api,framework,wrapper,asyncio,i18n,aiogram,fluent,gnutext
+Author: RootShinobi
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+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
+Requires-Dist: aiogram>=3.0.0b8
+Requires-Dist: click==8.*
+Requires-Dist: fluent-compiler~=1.1 ; extra == 'compiler'
+Requires-Dist: isort==8.0.1 ; extra == 'dev'
+Requires-Dist: pre-commit==4.5.1 ; extra == 'dev'
+Requires-Dist: ruff==0.15.5 ; extra == 'dev'
+Requires-Dist: mypy==1.19.1 ; extra == 'dev'
+Requires-Dist: types-polib==1.2.0.20250401 ; extra == 'dev'
+Requires-Dist: sphinx==8.1.3 ; extra == 'docs'
+Requires-Dist: furo==2025.12.19 ; extra == 'docs'
+Requires-Dist: sphinx-autobuild==2024.10.3 ; extra == 'docs'
+Requires-Dist: jinja2~=3.1.4 ; extra == 'jinja2'
+Requires-Dist: fluent-runtime~=0.4.0 ; extra == 'runtime'
+Requires-Dist: pytest==8.4.2 ; extra == 'test'
+Requires-Dist: pytest-cov==7.0.0 ; extra == 'test'
+Requires-Dist: pytest-asyncio==1.2.0 ; extra == 'test'
+Requires-Dist: fluent-runtime==0.4.0 ; extra == 'test'
+Requires-Dist: coverage==7.13.4 ; extra == 'test'
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/aiogram/aiogram_i18n
+Provides-Extra: compiler
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: jinja2
+Provides-Extra: runtime
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# aiogram_i18n
+
+Installation:
+```pip install aiogram_i18n```
+
+To use FluentCompileCore:
+```pip install fluent_compiler```
+
+To use FluentRuntimeCore:
+```pip install fluent.runtime```
+
+```python
+import asyncio
+from contextlib import suppress
+from logging import basicConfig, INFO
+from typing import Any
+
+from aiogram import Router, Dispatcher, Bot
+from aiogram.client.default import DefaultBotProperties
+from aiogram.enums import ParseMode
+from aiogram.filters import CommandStart
+from aiogram.types import Message
+
+from aiogram_i18n import I18nContext, LazyProxy, I18nMiddleware, LazyFilter
+from aiogram_i18n.cores.fluent_runtime_core import FluentRuntimeCore
+from aiogram_i18n.types import (
+    ReplyKeyboardMarkup, KeyboardButton
+    # you should import mutable objects from here if you want to use LazyProxy in them
+)
+
+router = Router(name=__name__)
+rkb = ReplyKeyboardMarkup(
+    keyboard=[
+        [KeyboardButton(text=LazyProxy("help"))]  # or L.help()
+    ], resize_keyboard=True
+)
+
+
+@router.message(CommandStart())
+async def cmd_start(message: Message, i18n: I18nContext) -> Any:
+    name = message.from_user.mention_html()
+    return message.reply(
+        text=i18n.get("hello", user=name),  # or i18n.hello(user=name)
+        reply_markup=rkb
+    )
+
+
+@router.message(LazyFilter("help"))  # or LazyProxy("help") or F.text == LazyProxy("help")
+async def cmd_help(message: Message) -> Any:
+    return message.reply(text="-- " + message.text + " --")
+
+
+async def main() -> None:
+    basicConfig(level=INFO)
+    bot = Bot("42:ABC", default=DefaultBotProperties(parse_mode=ParseMode.HTML))
+    i18n_middleware = I18nMiddleware(
+        core=FluentRuntimeCore(
+            path="locales/{locale}/LC_MESSAGES"
+        )
+    )
+
+    dp = Dispatcher()
+    dp.include_router(router)
+    i18n_middleware.setup(dispatcher=dp)
+
+    await dp.start_polling(bot)
+
+
+if __name__ == "__main__":
+    with suppress(KeyboardInterrupt):
+        asyncio.run(main())
+```

aiogram_i18n-1.5/README.md

@@ -0,0 +1,72 @@
+# aiogram_i18n
+
+Installation:
+```pip install aiogram_i18n```
+
+To use FluentCompileCore:
+```pip install fluent_compiler```
+
+To use FluentRuntimeCore:
+```pip install fluent.runtime```
+
+```python
+import asyncio
+from contextlib import suppress
+from logging import basicConfig, INFO
+from typing import Any
+
+from aiogram import Router, Dispatcher, Bot
+from aiogram.client.default import DefaultBotProperties
+from aiogram.enums import ParseMode
+from aiogram.filters import CommandStart
+from aiogram.types import Message
+
+from aiogram_i18n import I18nContext, LazyProxy, I18nMiddleware, LazyFilter
+from aiogram_i18n.cores.fluent_runtime_core import FluentRuntimeCore
+from aiogram_i18n.types import (
+    ReplyKeyboardMarkup, KeyboardButton
+    # you should import mutable objects from here if you want to use LazyProxy in them
+)
+
+router = Router(name=__name__)
+rkb = ReplyKeyboardMarkup(
+    keyboard=[
+        [KeyboardButton(text=LazyProxy("help"))]  # or L.help()
+    ], resize_keyboard=True
+)
+
+
+@router.message(CommandStart())
+async def cmd_start(message: Message, i18n: I18nContext) -> Any:
+    name = message.from_user.mention_html()
+    return message.reply(
+        text=i18n.get("hello", user=name),  # or i18n.hello(user=name)
+        reply_markup=rkb
+    )
+
+
+@router.message(LazyFilter("help"))  # or LazyProxy("help") or F.text == LazyProxy("help")
+async def cmd_help(message: Message) -> Any:
+    return message.reply(text="-- " + message.text + " --")
+
+
+async def main() -> None:
+    basicConfig(level=INFO)
+    bot = Bot("42:ABC", default=DefaultBotProperties(parse_mode=ParseMode.HTML))
+    i18n_middleware = I18nMiddleware(
+        core=FluentRuntimeCore(
+            path="locales/{locale}/LC_MESSAGES"
+        )
+    )
+
+    dp = Dispatcher()
+    dp.include_router(router)
+    i18n_middleware.setup(dispatcher=dp)
+
+    await dp.start_polling(bot)
+
+
+if __name__ == "__main__":
+    with suppress(KeyboardInterrupt):
+        asyncio.run(main())
+```

aiogram_i18n-1.5/pyproject.toml

@@ -0,0 +1,204 @@
+[project]
+name = "aiogram_i18n"
+version = "1.5"
+authors = [
+    { name = "RootShinobi" },
+]
+description = "Translation tool for aiogram"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+keywords = [
+    "telegram",
+    "bot",
+    "api",
+    "framework",
+    "wrapper",
+    "asyncio",
+    "i18n",
+    "aiogram",
+    "fluent",
+    "gnutext",
+]
+dependencies = [
+    "aiogram>=3.0.0b8",
+    "click==8.*",
+]
+
+[tool.uv]
+package = true
+
+[build-system]
+requires = ["uv_build>=0.10.7,<0.11.0"]
+build-backend = "uv_build"
+
+[project.urls]
+Repository = "https://github.com/aiogram/aiogram_i18n"
+
+[project.scripts]
+i18n = "aiogram_i18n.__main__:main"
+
+[project.optional-dependencies]
+compiler = [
+    "fluent_compiler~=1.1",
+]
+runtime = [
+    "fluent.runtime~=0.4.0",
+]
+jinja2 = [
+    "jinja2~=3.1.4",
+]
+test = [
+    "pytest==8.4.2",
+    "pytest-cov==7.0.0",
+    "pytest-asyncio==1.2.0",
+    "fluent.runtime==0.4.0",
+    "coverage==7.13.4",
+]
+dev = [
+    "isort==8.0.1",
+    "pre-commit==4.5.1",
+    "ruff==0.15.5",
+    "mypy==1.19.1",
+    "types-polib==1.2.0.20250401",
+]
+docs = [
+    "sphinx==8.1.3",
+    "furo==2025.12.19",
+    "sphinx-autobuild==2024.10.3",
+]
+
+[tool.hatch.envs.dev]
+post-install = [
+    "pre-commit install",
+]
+
+features = [
+    "compiler",
+    "runtime",
+    "jinja2",
+    "dev",
+    "test",
+    "docs",
+]
+
+[tool.isort]
+py_version = 310
+line_length = 99
+multi_line_output = 3
+force_grid_wrap = 0
+include_trailing_comma = true
+split_on_trailing_comma = false
+single_line_exclusions = ["."]
+sections = ["FUTURE", "STDLIB", "THIRDPARTY", "FIRSTPARTY", "LOCALFOLDER"]
+skip_gitignore = true
+extend_skip = ["__pycache__"]
+
+[tool.ruff]
+src = ["src", "tests"]
+line-length = 99
+exclude = [
+    ".git",
+    ".mypy_cache",
+    ".ruff_cache",
+    "__pypackages__",
+    "__pycache__",
+    "venv",
+    ".venv",
+    "tests/.files",
+    "tests/files/py",
+    "dist",
+    "build",
+]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "A002",
+    "ANN001", "ANN003", "ANN204", "ANN401",
+    "COM812",
+    "CPY001",
+    "D",
+    "DOC",
+    "FBT001", "FBT002",
+    "N805",
+    "PLC0415",
+    "PLR0913", "PLR0917", "PLR1702", "PLR6301",
+    "PLW2901",
+    "RUF052", "RUF067",
+    "TC006",
+    "TID252",
+]
+unfixable = []
+exclude = [
+    "examples"
+]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.lint.per-file-ignores]
+# Tests can use magic values, assertions, and relative imports
+"tests/**/*" = ["PLR2004", "S101", "TID252"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.mypy]
+mypy_path = "src"
+packages = ["aiogram_i18n"]
+plugins = ["pydantic.mypy"]
+allow_redefinition = true
+check_untyped_defs = true
+disallow_any_generics = true
+disallow_incomplete_defs = true
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+extra_checks = true
+follow_imports = "skip"
+follow_imports_for_stubs = false
+ignore_missing_imports = false
+namespace_packages = true
+no_implicit_optional = true
+no_implicit_reexport = true
+pretty = true
+show_absolute_path = true
+show_error_codes = true
+show_error_context = true
+warn_unused_configs = true
+warn_unused_ignores = true
+disable_error_code = [
+    "no-redef",
+]
+exclude = [
+    "\\.?venv",
+    "\\.idea",
+    "\\.tests?",
+]
+
+[[tool.mypy.overrides]]
+module = "mre"
+strict_optional = false
+
+[[tool.mypy.overrides]]
+module = "aiogram_i18n.types"
+disable_error_code = ["arg-type", "assignment"]
+
+[[tool.mypy.overrides]]
+module = [
+    "redis.*", "fluent_compiler.*"
+]
+ignore_missing_imports = true

aiogram_i18n-1.5/src/aiogram_i18n/__init__.py

@@ -0,0 +1,15 @@
+from .__version__ import __version__
+from .context import I18nContext
+from .lazy import LazyFactory, LazyFilter, LazyProxy
+from .middleware import I18nMiddleware
+
+L = LazyFactory()
+
+__all__ = (
+    "I18nContext",
+    "I18nMiddleware",
+    "L",
+    "LazyFilter",
+    "LazyProxy",
+    "__version__",
+)

aiogram_i18n-1.5/src/aiogram_i18n/__main__.py

@@ -0,0 +1,4 @@
+from aiogram_i18n.utils.cli import main
+
+if __name__ == "__main__":
+    main()

aiogram_i18n-1.5/src/aiogram_i18n/__version__.py

@@ -0,0 +1,3 @@
+import importlib.metadata
+
+__version__ = importlib.metadata.version(__package__)

aiogram_i18n-1.5/src/aiogram_i18n/context.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import TYPE_CHECKING, Any
+
+from aiogram_i18n.utils.context_instance import ContextInstanceMixin
+from aiogram_i18n.utils.magic_proxy import MagicProxy
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from aiogram_i18n.cores.base import BaseCore
+    from aiogram_i18n.managers.base import BaseManager
+
+
+class I18nContext(ContextInstanceMixin["I18nContext"]):
+    locale: str
+    core: BaseCore[Any]
+    manager: BaseManager
+    data: dict[str, Any]
+    key_separator: str
+    context: dict[str, Any]
+
+    def __init__(
+        self,
+        locale: str,
+        core: BaseCore[Any],
+        manager: BaseManager,
+        data: dict[str, Any],
+        key_separator: str = "-",
+    ) -> None:
+        self.locale = locale
+        self.core = core
+        self.manager = manager
+        self.data = data
+        self.key_separator = key_separator
+        self.context = {}
+
+    def get(self, key: str, locale: str | None = None, /, **kwargs: Any) -> str:
+        return self.core.get(key, locale or self.locale, **kwargs)
+
+    __call__ = get
+
+    def __getattr__(self, item: str) -> MagicProxy[str]:
+        proxy = MagicProxy(self, key_separator=self.key_separator)
+        return proxy.__getattr__(item)
+
+    async def set_locale(self, locale: str, **kwargs: Any) -> None:
+        kwargs.update(self.data, core=self.core)
+        await self.manager.locale_setter(locale, **kwargs)
+        self.locale = locale
+
+    @contextmanager
+    def use_locale(self, locale: str) -> Generator[I18nContext, None, None]:
+        old_locale = self.locale
+        self.locale = locale
+        try:
+            yield self
+        finally:
+            self.locale = old_locale
+
+    @contextmanager
+    def use_context(self, **kwargs: Any) -> Generator[I18nContext, None, None]:
+        old_context = self.context
+        self.context = kwargs
+        try:
+            yield self
+        finally:
+            self.context = old_context
+
+    def set_context(self, **kwargs: Any) -> None:
+        self.context = kwargs

aiogram_i18n-1.5/src/aiogram_i18n/cores/__init__.py

@@ -0,0 +1,32 @@
+from importlib import import_module
+from typing import TYPE_CHECKING, Any, cast
+
+from .base import BaseCore
+
+if TYPE_CHECKING:
+    from .fluent_compile_core import FluentCompileCore
+    from .fluent_runtime_core import FluentRuntimeCore
+    from .gnu_text_core import GNUTextCore
+    from .jinja2_core import Jinja2Core
+
+
+__cores__ = {
+    "GNUTextCore": ".gnu_text_core",
+    "FluentRuntimeCore": ".fluent_runtime_core",
+    "FluentCompileCore": ".fluent_compile_core",
+    "Jinja2Core": ".jinja2_core",
+}
+
+__all__ = (
+    "BaseCore",
+    "FluentCompileCore",
+    "FluentRuntimeCore",
+    "GNUTextCore",
+    "Jinja2Core",
+)
+
+
+def __getattr__(name: str) -> BaseCore[Any]:
+    if name not in __all__:
+        raise AttributeError
+    return cast(BaseCore[Any], getattr(import_module(__cores__[name], "aiogram_i18n.cores"), name))

aiogram_i18n-1.5/src/aiogram_i18n/cores/base.py

@@ -0,0 +1,109 @@
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Generic, TypeVar, cast
+
+from aiogram_i18n import I18nContext
+from aiogram_i18n.exceptions import NoLocalesError, NoLocalesFoundError, NoTranslateFileExistsError
+
+Translator = TypeVar("Translator")
+
+
+class BaseCore(ABC, Generic[Translator]):
+    """
+    Is an abstract base class for implementing core functionality for translation.
+    """
+
+    default_locale: str | None
+    locales: dict[str, Translator]
+    locales_map: dict[str, str]
+
+    def __init__(
+        self,
+        path: str | Path,
+        default_locale: str | None = None,
+        locales_map: dict[str, str] | None = None,
+    ) -> None:
+        """
+
+        :param default_locale: The default locale to be used for translations.
+            If not provided, it will default to None.
+        """
+        self.path = path if isinstance(path, Path) else Path(path)
+        self.default_locale = default_locale
+        self.locales = {}
+        self.locales_map = locales_map or {}
+
+    @abstractmethod
+    def get(self, message: str, locale: str | None = None, /, **kwargs: Any) -> str:
+        pass
+
+    def nget(
+        self,
+        singular: str,
+        plural: str | None = None,  # noqa: ARG002
+        n: int = 1,  # noqa: ARG002
+        locale: str | None = None,
+        /,
+        **kwargs: Any,
+    ) -> str:
+        return self.get(singular, locale, **kwargs)
+
+    def get_translator(self, locale: str) -> Translator:
+        return self.locales[locale]
+
+    def get_locale(self, locale: str | None = None) -> str:
+        if locale is None:
+            locale = I18nContext.get_current(no_error=False).locale
+        if locale not in self.locales:
+            locale = cast(str, self.default_locale)
+        return locale
+
+    async def startup(self) -> None:
+        self.locales.update(self.find_locales())
+
+    async def shutdown(self) -> None:
+        self.locales.clear()
+
+    @staticmethod
+    def _extract_locales(path: Path) -> list[str]:
+        if "{locale}" in path.parts:
+            path = Path(*path.parts[: path.parts.index("{locale}")])
+
+        locales: list[str] = [file_path.name for file_path in path.iterdir() if file_path.is_dir()]
+
+        if not locales:
+            raise NoLocalesFoundError(locales=[], path=path.as_posix())
+
+        return locales
+
+    @staticmethod
+    def _find_locales(
+        path: Path, locales: list[str], ext: str | None = None
+    ) -> dict[str, list[Path]]:
+        if not locales:
+            raise NoLocalesError
+
+        paths: dict[str, list[Path]] = {}
+
+        if "{locale}" not in path.as_posix():
+            path = path.joinpath("{locale}")
+
+        for locale in locales:
+            locale_path = Path(path.as_posix().format(locale=locale))
+            recursive_paths = locale_path.rglob(f"*{ext}")  # Will recursively search for files
+            paths.setdefault(locale, []).extend(recursive_paths)
+
+            if not paths[locale]:
+                raise NoTranslateFileExistsError(ext=ext, locale_path=locale_path.as_posix())
+        if not paths:
+            raise NoLocalesFoundError(locales=locales, path=path.as_posix())
+
+        return paths
+
+    @abstractmethod
+    def find_locales(self) -> dict[str, Translator]:
+        pass
+
+    @property
+    def available_locales(self) -> tuple[str, ...]:
+        return tuple(self.locales.keys())

aiogram_i18n-1.5/src/aiogram_i18n/cores/fluent_compile_core.py

@@ -0,0 +1,70 @@
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, cast
+
+from aiogram_i18n.exceptions import FluentMessageError, KeyNotFoundError, NoModuleError
+from aiogram_i18n.utils.text_decorator import td
+
+try:
+    from fluent_compiler.bundle import FluentBundle
+except ImportError as e:
+    raise NoModuleError(name="FluentCompileCore", module_name="fluent_compiler") from e
+
+from aiogram_i18n.cores.base import BaseCore
+
+
+class FluentCompileCore(BaseCore[FluentBundle]):
+    def __init__(
+        self,
+        path: str | Path,
+        default_locale: str | None = None,
+        use_isolating: bool = False,
+        functions: dict[str, Callable[..., Any]] | None = None,
+        raise_key_error: bool = True,
+        use_td: bool = True,
+        locales_map: dict[str, str] | None = None,
+    ) -> None:
+        super().__init__(path=path, default_locale=default_locale, locales_map=locales_map)
+        self.use_isolating = use_isolating
+        self.functions = functions or {}
+        if use_td:
+            self.functions.update(td.functions)
+        self.raise_key_error = raise_key_error
+
+    def get(self, message: str, locale: str | None = None, /, **kwargs: Any) -> str:
+        locale = self.get_locale(locale=locale)
+        translator: FluentBundle = self.get_translator(locale=locale)
+        try:
+            text, errors = translator.format(message_id=message, args=kwargs)
+        except KeyError:
+            locale: str | None = self.locales_map.get(locale)
+            if locale is not None:
+                return self.get(message, locale, **kwargs)
+            if self.raise_key_error:
+                raise KeyNotFoundError(message) from None
+            return message
+        if errors:
+            raise FluentMessageError(message_id=message, errors=errors)
+        return cast(str, text)  # 'cause fluent_compiler type-ignored
+
+    def find_locales(self) -> dict[str, FluentBundle]:
+        """
+        Load all compiled locales from path
+
+        :return: dict with locales
+        """
+        translations: dict[str, FluentBundle] = {}
+        locales = self._extract_locales(self.path)
+        for locale, paths in self._find_locales(self.path, locales, ".ftl").items():
+            texts = []
+            for path in paths:
+                with path.open("r", encoding="utf8") as fp:
+                    texts.append(fp.read())
+            translations[locale] = FluentBundle.from_string(
+                text="\n".join(texts),
+                locale=locale,
+                use_isolating=self.use_isolating,
+                functions=self.functions,
+            )
+
+        return translations