runtime: Add type hints

Author: eemeli

fluent.runtime/fluent/runtime/__init__.py

@@ -1,4 +1,5 @@
 from fluent.syntax import FluentParser
+from fluent.syntax.ast import Resource
 
 from .bundle import FluentBundle
 from .fallback import FluentLocalization, AbstractResourceLoader, FluentResourceLoader
@@ -13,6 +14,6 @@
 ]
 
 
-def FluentResource(source):
+def FluentResource(source: str) -> Resource:
     parser = FluentParser()
     return parser.parse(source)

fluent.runtime/fluent/runtime/builtins.py

@@ -1,10 +1,11 @@
-from .types import fluent_date, fluent_number
+from typing import Any, Callable, Dict
+from .types import FluentType, fluent_date, fluent_number
 
 NUMBER = fluent_number
 DATETIME = fluent_date
 
 
-BUILTINS = {
+BUILTINS: Dict[str, Callable[[Any], FluentType]] = {
     'NUMBER': NUMBER,
     'DATETIME': DATETIME,
 }

fluent.runtime/fluent/runtime/bundle.py

@@ -1,14 +1,20 @@
 import babel
 import babel.numbers
 import babel.plural
+from typing import Any, Callable, Dict, List, Literal, TYPE_CHECKING, Tuple, Union, cast
 
-from fluent.syntax.ast import Message, Term
+from fluent.syntax import ast as FTL
 
 from .builtins import BUILTINS
 from .prepare import Compiler
-from .resolver import ResolverEnvironment, CurrentEnvironment
+from .resolver import CurrentEnvironment, Message, Pattern, ResolverEnvironment
 from .utils import native_to_fluent
 
+if TYPE_CHECKING:
+    from .types import FluentNone, FluentType
+
+PluralCategory = Literal['zero', 'one', 'two', 'few', 'many', 'other']
+
 
 class FluentBundle:
     """
@@ -25,37 +31,42 @@ class FluentBundle:
     See the documentation of the Fluent syntax for more information.
     """
 
-    def __init__(self, locales, functions=None, use_isolating=True):
+    def __init__(self,
+                 locales: List[str],
+                 functions: Union[Dict[str, Callable[[Any], 'FluentType']], None] = None,
+                 use_isolating: bool = True):
         self.locales = locales
         _functions = BUILTINS.copy()
         if functions:
             _functions.update(functions)
         self._functions = _functions
         self.use_isolating = use_isolating
-        self._messages = {}
-        self._terms = {}
-        self._compiled = {}
-        self._compiler = Compiler()
+        self._messages: Dict[str, Union[FTL.Message, FTL.Term]] = {}
+        self._terms: Dict[str, Union[FTL.Message, FTL.Term]] = {}
+        self._compiled: Dict[str, Message] = {}
+        # The compiler is not typed, and this cast is only valid for the public API
+        self._compiler = cast(Callable[[Union[FTL.Message, FTL.Term]], Message], Compiler())
         self._babel_locale = self._get_babel_locale()
-        self._plural_form = babel.plural.to_python(self._babel_locale.plural_form)
+        self._plural_form = cast(Callable[[Any], Callable[[Union[int, float]], PluralCategory]],
+                                 babel.plural.to_python)(self._babel_locale.plural_form)
 
-    def add_resource(self, resource, allow_overrides=False):
+    def add_resource(self, resource: FTL.Resource, allow_overrides: bool = False) -> None:
         # TODO - warn/error about duplicates
         for item in resource.body:
-            if not isinstance(item, (Message, Term)):
+            if not isinstance(item, (FTL.Message, FTL.Term)):
                 continue
-            map_ = self._messages if isinstance(item, Message) else self._terms
+            map_ = self._messages if isinstance(item, FTL.Message) else self._terms
             full_id = item.id.name
             if full_id not in map_ or allow_overrides:
                 map_[full_id] = item
 
-    def has_message(self, message_id):
+    def has_message(self, message_id: str) -> bool:
         return message_id in self._messages
 
-    def get_message(self, message_id):
+    def get_message(self, message_id: str) -> Message:
         return self._lookup(message_id)
 
-    def _lookup(self, entry_id, term=False):
+    def _lookup(self, entry_id: str, term: bool = False) -> Message:
         if term:
             compiled_id = '-' + entry_id
         else:
@@ -68,7 +79,10 @@ def _lookup(self, entry_id, term=False):
         self._compiled[compiled_id] = self._compiler(entry)
         return self._compiled[compiled_id]
 
-    def format_pattern(self, pattern, args=None):
+    def format_pattern(self,
+                       pattern: Pattern,
+                       args: Union[Dict[str, Any], None] = None
+                       ) -> Tuple[Union[str, 'FluentNone'], List[Exception]]:
         if args is not None:
             fluent_args = {
                 argname: native_to_fluent(argvalue)
@@ -77,7 +91,7 @@ def format_pattern(self, pattern, args=None):
         else:
             fluent_args = {}
 
-        errors = []
+        errors: List[Exception] = []
         env = ResolverEnvironment(context=self,
                                   current=CurrentEnvironment(args=fluent_args),
                                   errors=errors)
@@ -86,9 +100,9 @@ def format_pattern(self, pattern, args=None):
         except ValueError as e:
             errors.append(e)
             result = '{???}'
-        return [result, errors]
+        return (result, errors)
 
-    def _get_babel_locale(self):
+    def _get_babel_locale(self) -> babel.Locale:
         for lc in self.locales:
             try:
                 return babel.Locale.parse(lc.replace('-', '_'))

fluent.runtime/fluent/runtime/errors.py

@@ -1,7 +1,9 @@
+from typing import cast
+
+
 class FluentFormatError(ValueError):
-    def __eq__(self, other):
-        return ((other.__class__ == self.__class__) and
-                other.args == self.args)
+    def __eq__(self, other: object) -> bool:
+        return ((other.__class__ == self.__class__) and cast(ValueError, other).args == self.args)
 
 
 class FluentReferenceError(FluentFormatError):

fluent.runtime/fluent/runtime/fallback.py

@@ -1,5 +1,14 @@
 import codecs
 import os
+from typing import Any, Callable, Dict, Generator, List, TYPE_CHECKING, Type, Union, cast
+
+from fluent.syntax import FluentParser
+
+from .bundle import FluentBundle
+
+if TYPE_CHECKING:
+    from fluent.syntax.ast import Resource
+    from .types import FluentType
 
 
 class FluentLocalization:
@@ -9,41 +18,42 @@ class FluentLocalization:
     This handles language fallback, bundle creation and string localization.
     It uses the given resource loader to load and parse Fluent data.
     """
+
     def __init__(
-        self, locales, resource_ids, resource_loader,
-        use_isolating=False,
-        bundle_class=None, functions=None,
+        self,
+        locales: List[str],
+        resource_ids: List[str],
+        resource_loader: 'AbstractResourceLoader',
+        use_isolating: bool = False,
+        bundle_class: Type[FluentBundle] = FluentBundle,
+        functions: Union[Dict[str, Callable[[Any], 'FluentType']], None] = None,
     ):
         self.locales = locales
         self.resource_ids = resource_ids
         self.resource_loader = resource_loader
         self.use_isolating = use_isolating
-        if bundle_class is None:
-            from fluent.runtime import FluentBundle
-            self.bundle_class = FluentBundle
-        else:
-            self.bundle_class = bundle_class
+        self.bundle_class = bundle_class
         self.functions = functions
-        self._bundle_cache = []
+        self._bundle_cache: List[FluentBundle] = []
         self._bundle_it = self._iterate_bundles()
 
-    def format_value(self, msg_id, args=None):
+    def format_value(self, msg_id: str, args: Union[Dict[str, Any], None] = None) -> str:
         for bundle in self._bundles():
             if not bundle.has_message(msg_id):
                 continue
             msg = bundle.get_message(msg_id)
             if not msg.value:
                 continue
-            val, errors = bundle.format_pattern(msg.value, args)
-            return val
+            val, _errors = bundle.format_pattern(msg.value, args)
+            return cast(str, val)  # Never FluentNone when format_pattern called externally
         return msg_id
 
-    def _create_bundle(self, locales):
+    def _create_bundle(self, locales: List[str]) -> FluentBundle:
         return self.bundle_class(
             locales, functions=self.functions, use_isolating=self.use_isolating
         )
 
-    def _bundles(self):
+    def _bundles(self) -> Generator[FluentBundle, None, None]:
         bundle_pointer = 0
         while True:
             if bundle_pointer == len(self._bundle_cache):
@@ -54,7 +64,7 @@ def _bundles(self):
             yield self._bundle_cache[bundle_pointer]
             bundle_pointer += 1
 
-    def _iterate_bundles(self):
+    def _iterate_bundles(self) -> Generator[FluentBundle, None, None]:
         for first_loc in range(0, len(self.locales)):
             locs = self.locales[first_loc:]
             for resources in self.resource_loader.resources(locs[0], self.resource_ids):
@@ -68,7 +78,8 @@ class AbstractResourceLoader:
     """
     Interface to implement for resource loaders.
     """
-    def resources(self, locale, resource_ids):
+
+    def resources(self, locale: str, resource_ids: List[str]) -> Generator[List['Resource'], None, None]:
         """
         Yield lists of FluentResource objects, corresponding to
         each of the resource_ids.
@@ -89,26 +100,26 @@ class FluentResourceLoader(AbstractResourceLoader):
     This loader does not support loading resources for one bundle from
     different roots.
     """
-    def __init__(self, roots):
+
+    def __init__(self, roots: Union[str, List[str]]):
         """
         Create a resource loader. The roots may be a string for a single
         location on disk, or a list of strings.
         """
         self.roots = [roots] if isinstance(roots, str) else roots
-        from fluent.runtime import FluentResource
         self.Resource = FluentResource
 
-    def resources(self, locale, resource_ids):
+    def resources(self, locale: str, resource_ids: List[str]) -> Generator[List['Resource'], None, None]:
         for root in self.roots:
-            resources = []
+            resources: List[Any] = []
             for resource_id in resource_ids:
                 path = self.localize_path(os.path.join(root, resource_id), locale)
                 if not os.path.isfile(path):
                     continue
                 content = codecs.open(path, 'r', 'utf-8').read()
-                resources.append(self.Resource(content))
+                resources.append(FluentParser().parse(content))
             if resources:
                 yield resources
 
-    def localize_path(self, path, locale):
+    def localize_path(self, path: str, locale: str) -> str:
         return path.format(locale=locale)

fluent.runtime/fluent/runtime/prepare.py

@@ -1,38 +1,36 @@
+from typing import Any, Dict, List
 from fluent.syntax import ast as FTL
 from . import resolver
 
 
 class Compiler:
-    def __call__(self, item):
+    def __call__(self, item: Any) -> Any:
         if isinstance(item, FTL.BaseNode):
             return self.compile(item)
         if isinstance(item, (tuple, list)):
             return [self(elem) for elem in item]
         return item
 
-    def compile(self, node):
-        nodename = type(node).__name__
+    def compile(self, node: Any) -> Any:
+        nodename: str = type(node).__name__
         if not hasattr(resolver, nodename):
             return node
-        kwargs = vars(node).copy()
+        kwargs: Dict[str, Any] = vars(node).copy()
         for propname, propvalue in kwargs.items():
             kwargs[propname] = self(propvalue)
         handler = getattr(self, 'compile_' + nodename, self.compile_generic)
         return handler(nodename, **kwargs)
 
-    def compile_generic(self, nodename, **kwargs):
+    def compile_generic(self, nodename: str, **kwargs: Any) -> Any:
         return getattr(resolver, nodename)(**kwargs)
 
-    def compile_Placeable(self, _, expression, **kwargs):
+    def compile_Placeable(self, _: Any, expression: Any, **kwargs: Any) -> Any:
         if isinstance(expression, resolver.Literal):
             return expression
         return resolver.Placeable(expression=expression, **kwargs)
 
-    def compile_Pattern(self, _, elements, **kwargs):
-        if (
-            len(elements) == 1 and
-            isinstance(elements[0], resolver.Placeable)
-        ):
+    def compile_Pattern(self, _: Any, elements: List[Any], **kwargs: Any) -> Any:
+        if len(elements) == 1 and isinstance(elements[0], resolver.Placeable):
             # Don't isolate isolated placeables
             return resolver.NeverIsolatingPlaceable(elements[0].expression)
         if any(