syntax: Add type hints

Author: eemeli

fluent.syntax/fluent/syntax/__init__.py

@@ -1,15 +1,17 @@
+from typing import Any
+from .ast import Resource
 from .parser import FluentParser
 from .serializer import FluentSerializer
 
 
-def parse(source, **kwargs):
+def parse(source: str, **kwargs: Any) -> Resource:
     """Create an ast.Resource from a Fluent Syntax source.
     """
     parser = FluentParser(**kwargs)
     return parser.parse(source)
 
 
-def serialize(resource, **kwargs):
+def serialize(resource: Resource, **kwargs: Any) -> str:
     """Serialize an ast.Resource to a unicode string.
     """
     serializer = FluentSerializer(**kwargs)

fluent.syntax/fluent/syntax/ast.py

@@ -1,9 +1,13 @@
 import re
 import sys
 import json
+from typing import Any, Callable, Dict, List, TypeVar, Union, cast
 
+Node = TypeVar('Node', bound='BaseNode')
+ToJsonFn = Callable[[Dict[str, Any]], Any]
 
-def to_json(value, fn=None):
+
+def to_json(value: Any, fn: Union[ToJsonFn, None] = None) -> Any:
     if isinstance(value, BaseNode):
         return value.to_json(fn)
     if isinstance(value, list):
@@ -14,7 +18,7 @@ def to_json(value, fn=None):
         return value
 
 
-def from_json(value):
+def from_json(value: Any) -> Any:
     if isinstance(value, dict):
         cls = getattr(sys.modules[__name__], value['type'])
         args = {
@@ -29,7 +33,7 @@ def from_json(value):
         return value
 
 
-def scalars_equal(node1, node2, ignored_fields):
+def scalars_equal(node1: Any, node2: Any, ignored_fields: List[str]) -> bool:
     """Compare two nodes which are not lists."""
 
     if type(node1) != type(node2):
@@ -38,7 +42,7 @@ def scalars_equal(node1, node2, ignored_fields):
     if isinstance(node1, BaseNode):
         return node1.equals(node2, ignored_fields)
 
-    return node1 == node2
+    return cast(bool, node1 == node2)
 
 
 class BaseNode:
@@ -48,9 +52,9 @@ class BaseNode:
     Annotation.  Implements __str__, to_json and traverse.
     """
 
-    def clone(self):
+    def clone(self: Node) -> Node:
         """Create a deep clone of the current node."""
-        def visit(value):
+        def visit(value: Any) -> Any:
             """Clone node and its descendants."""
             if isinstance(value, BaseNode):
                 return value.clone()
@@ -65,7 +69,7 @@ def visit(value):
             **{name: visit(value) for name, value in vars(self).items()}
         )
 
-    def equals(self, other, ignored_fields=['span']):
+    def equals(self, other: 'BaseNode', ignored_fields: List[str] = ['span']) -> bool:
         """Compare two nodes.
 
         Nodes are deeply compared on a field by field basis. If possible, False
@@ -104,7 +108,7 @@ def equals(self, other, ignored_fields=['span']):
 
         return True
 
-    def to_json(self, fn=None):
+    def to_json(self, fn: Union[ToJsonFn, None] = None) -> Any:
         obj = {
             name: to_json(value, fn)
             for name, value in vars(self).items()
@@ -114,23 +118,23 @@ def to_json(self, fn=None):
         )
         return fn(obj) if fn else obj
 
-    def __str__(self):
+    def __str__(self) -> str:
         return json.dumps(self.to_json())
 
 
 class SyntaxNode(BaseNode):
     """Base class for AST nodes which can have Spans."""
 
-    def __init__(self, span=None, **kwargs):
+    def __init__(self, span: Union['Span', None] = None, **kwargs: Any):
         super().__init__(**kwargs)
         self.span = span
 
-    def add_span(self, start, end):
+    def add_span(self, start: int, end: int) -> None:
         self.span = Span(start, end)
 
 
 class Resource(SyntaxNode):
-    def __init__(self, body=None, **kwargs):
+    def __init__(self, body: Union[List['EntryType'], None] = None, **kwargs: Any):
         super().__init__(**kwargs)
         self.body = body or []
 
@@ -140,8 +144,12 @@ class Entry(SyntaxNode):
 
 
 class Message(Entry):
-    def __init__(self, id, value=None, attributes=None,
-                 comment=None, **kwargs):
+    def __init__(self,
+                 id: 'Identifier',
+                 value: Union['Pattern', None] = None,
+                 attributes: Union[List['Attribute'], None] = None,
+                 comment: Union['Comment', None] = None,
+                 **kwargs: Any):
         super().__init__(**kwargs)
         self.id = id
         self.value = value
@@ -150,8 +158,8 @@ def __init__(self, id, value=None, attributes=None,
 
 
 class Term(Entry):
-    def __init__(self, id, value, attributes=None,
-                 comment=None, **kwargs):
+    def __init__(self, id: 'Identifier', value: 'Pattern', attributes: Union[List['Attribute'], None] = None,
+                 comment: Union['Comment', None] = None, **kwargs: Any):
         super().__init__(**kwargs)
         self.id = id
         self.value = value
@@ -160,7 +168,7 @@ def __init__(self, id, value, attributes=None,
 
 
 class Pattern(SyntaxNode):
-    def __init__(self, elements, **kwargs):
+    def __init__(self, elements: List[Union['TextElement', 'Placeable']], **kwargs: Any):
         super().__init__(**kwargs)
         self.elements = elements
 
@@ -170,13 +178,15 @@ class PatternElement(SyntaxNode):
 
 
 class TextElement(PatternElement):
-    def __init__(self, value, **kwargs):
+    def __init__(self, value: str, **kwargs: Any):
         super().__init__(**kwargs)
         self.value = value
 
 
 class Placeable(PatternElement):
-    def __init__(self, expression, **kwargs):
+    def __init__(self,
+                 expression: Union['InlineExpression', 'Placeable', 'SelectExpression'],
+                 **kwargs: Any):
         super().__init__(**kwargs)
         self.expression = expression
 
@@ -187,20 +197,21 @@ class Expression(SyntaxNode):
 
 class Literal(Expression):
     """An abstract base class for literals."""
-    def __init__(self, value, **kwargs):
+
+    def __init__(self, value: str, **kwargs: Any):
         super().__init__(**kwargs)
         self.value = value
 
-    def parse(self):
+    def parse(self) -> Dict[str, Any]:
         return {'value': self.value}
 
 
 class StringLiteral(Literal):
-    def parse(self):
-        def from_escape_sequence(matchobj):
+    def parse(self) -> Dict[str, str]:
+        def from_escape_sequence(matchobj: Any) -> str:
             c, codepoint4, codepoint6 = matchobj.groups()
             if c:
-                return c
+                return cast(str, c)
             codepoint = int(codepoint4 or codepoint6, 16)
             if codepoint <= 0xD7FF or 0xE000 <= codepoint:
                 return chr(codepoint)
@@ -218,7 +229,7 @@ def from_escape_sequence(matchobj):
 
 
 class NumberLiteral(Literal):
-    def parse(self):
+    def parse(self) -> Dict[str, Union[float, int]]:
         value = float(self.value)
         decimal_position = self.value.find('.')
         precision = 0
@@ -231,116 +242,135 @@ def parse(self):
 
 
 class MessageReference(Expression):
-    def __init__(self, id, attribute=None, **kwargs):
+    def __init__(self, id: 'Identifier', attribute: Union['Identifier', None] = None, **kwargs: Any):
         super().__init__(**kwargs)
         self.id = id
         self.attribute = attribute
 
 
 class TermReference(Expression):
-    def __init__(self, id, attribute=None, arguments=None, **kwargs):
+    def __init__(self,
+                 id: 'Identifier',
+                 attribute: Union['Identifier', None] = None,
+                 arguments: Union['CallArguments', None] = None,
+                 **kwargs: Any):
         super().__init__(**kwargs)
         self.id = id
         self.attribute = attribute
         self.arguments = arguments
 
 
 class VariableReference(Expression):
-    def __init__(self, id, **kwargs):
+    def __init__(self, id: 'Identifier', **kwargs: Any):
         super().__init__(**kwargs)
         self.id = id
 
 
 class FunctionReference(Expression):
-    def __init__(self, id, arguments, **kwargs):
+    def __init__(self, id: 'Identifier', arguments: 'CallArguments', **kwargs: Any):
         super().__init__(**kwargs)
         self.id = id
         self.arguments = arguments
 
 
 class SelectExpression(Expression):
-    def __init__(self, selector, variants, **kwargs):
+    def __init__(self, selector: 'InlineExpression', variants: List['Variant'], **kwargs: Any):
         super().__init__(**kwargs)
         self.selector = selector
         self.variants = variants
 
 
 class CallArguments(SyntaxNode):
-    def __init__(self, positional=None, named=None, **kwargs):
+    def __init__(self,
+                 positional: Union[List[Union['InlineExpression', Placeable]], None] = None,
+                 named: Union[List['NamedArgument'], None] = None,
+                 **kwargs: Any):
         super().__init__(**kwargs)
         self.positional = [] if positional is None else positional
         self.named = [] if named is None else named
 
 
 class Attribute(SyntaxNode):
-    def __init__(self, id, value, **kwargs):
+    def __init__(self, id: 'Identifier', value: Pattern, **kwargs: Any):
         super().__init__(**kwargs)
         self.id = id
         self.value = value
 
 
 class Variant(SyntaxNode):
-    def __init__(self, key, value, default=False, **kwargs):
+    def __init__(self, key: Union['Identifier', NumberLiteral], value: Pattern, default: bool = False, **kwargs: Any):
         super().__init__(**kwargs)
         self.key = key
         self.value = value
         self.default = default
 
 
 class NamedArgument(SyntaxNode):
-    def __init__(self, name, value, **kwargs):
+    def __init__(self, name: 'Identifier', value: Union[NumberLiteral, StringLiteral], **kwargs: Any):
         super().__init__(**kwargs)
         self.name = name
         self.value = value
 
 
 class Identifier(SyntaxNode):
-    def __init__(self, name, **kwargs):
+    def __init__(self, name: str, **kwargs: Any):
         super().__init__(**kwargs)
         self.name = name
 
 
 class BaseComment(Entry):
-    def __init__(self, content=None, **kwargs):
+    def __init__(self, content: Union[str, None] = None, **kwargs: Any):
         super().__init__(**kwargs)
         self.content = content
 
 
 class Comment(BaseComment):
-    def __init__(self, content=None, **kwargs):
+    def __init__(self, content: Union[str, None] = None, **kwargs: Any):
         super().__init__(content, **kwargs)
 
 
 class GroupComment(BaseComment):
-    def __init__(self, content=None, **kwargs):
+    def __init__(self, content: Union[str, None] = None, **kwargs: Any):
         super().__init__(content, **kwargs)
 
 
 class ResourceComment(BaseComment):
-    def __init__(self, content=None, **kwargs):
+    def __init__(self, content: Union[str, None] = None, **kwargs: Any):
         super().__init__(content, **kwargs)
 
 
 class Junk(SyntaxNode):
-    def __init__(self, content=None, annotations=None, **kwargs):
+    def __init__(self,
+                 content: Union[str, None] = None,
+                 annotations: Union[List['Annotation'], None] = None,
+                 **kwargs: Any):
         super().__init__(**kwargs)
         self.content = content
         self.annotations = annotations or []
 
-    def add_annotation(self, annot):
+    def add_annotation(self, annot: 'Annotation') -> None:
         self.annotations.append(annot)
 
 
 class Span(BaseNode):
-    def __init__(self, start, end, **kwargs):
+    def __init__(self, start: int, end: int, **kwargs: Any):
         super().__init__(**kwargs)
         self.start = start
         self.end = end
 
 
 class Annotation(SyntaxNode):
-    def __init__(self, code, arguments=None, message=None, **kwargs):
+    def __init__(self,
+                 code: str,
+                 arguments: Union[List[Any], None] = None,
+                 message: Union[str, None] = None,
+                 **kwargs: Any):
         super().__init__(**kwargs)
         self.code = code
         self.arguments = arguments or []
         self.message = message
+
+
+EntryType = Union[Message, Term, Comment, GroupComment, ResourceComment, Junk]
+InlineExpression = Union[NumberLiteral, StringLiteral, MessageReference,
+                         TermReference, VariableReference, FunctionReference]

fluent.syntax/fluent/syntax/errors.py

@@ -1,11 +1,14 @@
+from typing import Tuple, Union
+
+
 class ParseError(Exception):
-    def __init__(self, code, *args):
+    def __init__(self, code: str, *args: Union[str, None]):
         self.code = code
         self.args = args
         self.message = get_error_message(code, args)
 
 
-def get_error_message(code, args):
+def get_error_message(code: str, args: Tuple[Union[str, None], ...]) -> str:
     if code == 'E00001':
         return 'Generic error'
     if code == 'E0002':