Remove attrs, type checking

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 4
+insert_final_newline = true
+end_of_line = lf
+
+[*.{yml,yaml}]
+indent_size = 2
+
+
+[*.json]
+indent_size = 2

.pre-commit-config.yaml

@@ -5,7 +5,7 @@ repos:
       - id: trailing-whitespace
       - id: end-of-file-fixer
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.4.5
+    rev: v0.11.4
     hooks:
       - id: ruff
         args: [ --fix, --exit-non-zero-on-fix ]

ARCHITECTURE.rst

@@ -103,6 +103,35 @@ FTL functions.
 Other related level classes for the user are provided in
 ``fluent_compiler.resource`` and ``fluent_compiler.escapers``.
 
+AST Types
+~~~~~~~~~
+
+As we are translating from one language to another, it is easy to get confused
+about types of Abstract Syntax Tree objects in the different languages,
+especially as sometimes we use identical class names. Here is a quick overview:
+
+- FTL (Fluent Translation List) has its own AST types. In the ``compiler.py``
+  module, these are imported as ``fl_ast``. So, for example,
+  ``fl_ast.VariableReference`` is an AST node representing a variable reference
+  in a Fluent document.
+
+- Python AST. This is the end product we generate. It is imported directly into
+  the ``ast_compat.py`` module. From there it is imported into the
+  ``codegen.py`` module as ``py_ast``.
+
+- Codegen AST. We have our own layer of classes for Python code generation which
+  are used by the ``compiler.py`` module, which represent a simplified Python
+  AST with conveniences for easier construction, and eventually emit Python AST.
+  The base classes used here are ``CodeGenAst`` and ``CodeGenAstList``.
+
+  This module is imported into ``compiler.py`` as ``codegen``.
+
+So, for example, in ``compiler.py`` you find both ``fl_ast.VariableReference``
+and ``codegen.VariableReference``. In ``codegen.py`` you find both ``If`` (the
+``If`` AST node defined in the ``codgen.py`` module) and ``py_ast.If`` (the
+Python AST node from Python stdlib). If you get lost remember which module/layer
+you are in.
+
 Tests
 ~~~~~
 

CHANGELOG.rst

@@ -6,6 +6,14 @@ fluent_compiler 1.2 (unreleased)
 
 * Dropped Python 3.7 support
 * Compiler performance improvements - thanks `@leamingrad <https://github.com/leamingrad>`_.
+* Switched from `attrs <https://www.attrs.org/en/stable/index.html>`_ to stdlib
+  `dataclasses <https://docs.python.org/3/library/dataclasses.html>`_, and added
+  lots of type signatures and cleaned up internally.
+  * The documented API is still exactly the same as it was. However, if you were
+    depending on implementation details, like the fact that ``CompiledFtl`` was
+    an attrs dataclass when it is now a stdlib dataclass, there may be some
+    small backwards incompatibilities. In addition if you are running a type
+    checker, you may notice some differences as more things will be checked.
 
 fluent_compiler 1.1 (2024-04-02)
 --------------------------------

docs/escaping.rst

@@ -24,18 +24,19 @@ passed to the ``FluentBundle`` constructor or to ``compile_messages``.
 
 An ``escaper`` is an object that defines the following set of attributes. The
 object could be a module, or a simple namespace object you could create using
-``types.SimpleNamespace``, or an instance of a class with appropriate
-methods defined. The attributes are:
+``types.SimpleNamespace`` or the provided
+:class:`fluent_compiler.escapers.Escaper` dataclass, or an instance of a class
+with appropriate methods defined. The attributes are:
 
-- ``name`` - a simple text value that is used in error messages.
+- ``name: str`` - a simple text value that is used in error messages.
 
 - ``select(**hints)``
 
   A callable that is used to decide whether or not to use this escaper for a
   given message (or message attribute). It is passed a number of hints as
   keyword arguments, currently only the following:
 
-  - ``message_id`` - a string that is the name of the message or term. For terms
+  - ``message_id: str`` - a string that is the name of the message or term. For terms
      it is a string with a leading dash - e.g. ``-brand-name``. For message
      attributes, it is a string in the form ``messsage-name.attribute-name``
 
@@ -48,10 +49,10 @@ methods defined. The attributes are:
   ``select`` callable of each escaper in the list of escapers is tried in turn,
   and the first to return ``True`` is used.
 
-- ``output_type`` - the type of values that are returned by ``escape``,
+- ``output_type: type`` - the type of values that are returned by ``escape``,
   ``mark_escape``, and ``join``, and therefore by the whole message.
 
-- ``escape(text_to_be_escaped)``
+- ``escape(text_to_be_escaped: str)``
 
   A callable that will escape the passed in text. It must return a value that is
   an instance of ``output_type`` (or a subclass).
@@ -64,24 +65,24 @@ methods defined. The attributes are:
   A callable that marks the passed in text as markup i.e. already escaped. It
   must return a value that is an instance of ``output_type`` (or a subclass).
 
-- ``join(parts)``
+- ``join(parts: Iterable)``
 
   A callable that accepts an iterable of components, each of type
   ``output_type``, and combines them into a larger value of the same type.
 
-- ``use_isolating``
+- ``use_isolating: bool | None``
 
   A boolean that determines whether the normal bidi isolating characters should
   be inserted. If it is ``None`` the value from the ``FluentBundle`` will be
   used, otherwise use ``True`` or ``False`` to override.
 
 The escaping functions need to obey some rules:
 
-- escape must be idempotent:
+- ``escape`` must be idempotent:
 
   ``escape(escape(text)) == escape(text)``
 
-- escape must be a no-op on the output of ``mark_escaped``:
+- ``escape`` must be a no-op on the output of ``mark_escaped``:
 
   ``escape(mark_escaped(text)) == mark_escaped(text)``
 
@@ -101,13 +102,13 @@ This example is for
 
 .. code-block:: python
 
-   from fluent_compiler.utils import SimpleNamespace
+   from fluent_compiler.escapers import Escaper
    from markupsafe import Markup, escape
 
    empty_markup = Markup('')
 
-   html_escaper = SimpleNamespace(
-       select=lambda message_id=None, **hints: message_id.endswith('-html'),
+   html_escaper = Escaper(
+       select=lambda message_id, **hints: message_id.endswith('-html'),
        output_type=Markup,
        mark_escaped=Markup,
        escape=escape,

pyproject.toml

@@ -35,10 +35,11 @@ classifiers = [
 dynamic = ["version"]
 
 dependencies = [
-    "attrs>=19.3.0",
     "babel>=2.12.0",
+    "backports-strenum>=1.2.4 ; python_full_version < '3.11'",
     "fluent-syntax>=0.14",
     "pytz>=2025.2",
+    "typing-extensions>=4.13.0 ; python_full_version < '3.10'",
 ]
 
 [project.urls]
@@ -75,7 +76,8 @@ target-version = ['py39']
 
 [tool.ruff]
 line-length = 120
-target-version = 'py37'
+target-version = 'py38'
+
 
 [tool.ruff.lint]
 ignore = ["E501","E731"]
@@ -92,11 +94,14 @@ known-first-party = ["fluent_compiler"]
 dev = [
     "ast-decompiler>=0.8",
     "beautifulsoup4>=4.7.1",
+    "fluent-runtime>=0.4.0",
     "hypothesis>=4.9.0",
+    "ipython>=8.12.3",
     "markdown>=3.0.1",
     "markupsafe>=1.1.1",
     "pre-commit>=3.5.0",
     "pytest>=7.4.4",
-    "tox-uv>=1.13.1",
+    "pytest-benchmark>=4.0.0",
     "tox>=4.25.0",
+    "tox-uv>=1.13.1",
 ]

src/fluent_compiler/ast_compat.py

@@ -25,6 +25,7 @@ def NewAst(...):
 """
 import ast
 import sys
+from typing import TypedDict, TypeVar
 
 # This is a very limited subset of Python AST:
 # - only the things needed by codegen.py
@@ -61,21 +62,36 @@ def NewAst(...):
 arg = ast.arg
 keyword = ast.keyword
 walk = ast.walk
+Constant = ast.Constant
+AST = ast.AST
+stmt = ast.stmt
+expr = ast.expr
 
 
-if sys.version_info >= (3, 8):
-    Constant = ast.Constant
+# `compile` builtin needs these attributes on AST nodes.
+# It's hard to get something sensible we can put for line/col numbers so we put arbitrary values.
+
+
+class DefaultAstArgs(TypedDict):
+    lineno: int
+    col_offset: int
+
+
+DEFAULT_AST_ARGS: DefaultAstArgs = {"lineno": 1, "col_offset": 1}
+# Some AST types have different requirements:
+DEFAULT_AST_ARGS_MODULE = dict()
+DEFAULT_AST_ARGS_ADD = dict()
+DEFAULT_AST_ARGS_ARGUMENTS = dict()
+
+T = TypeVar("T")
+
+
+if sys.version_info < (3, 9):
+    # Old versions need an `Index` object here:
+    def subscript_slice_object(value: T) -> T:
+        return ast.Index(value, **DEFAULT_AST_ARGS)
+
 else:
-    # For Python 3.7, in terms of runtime behaviour we could also use
-    # Constant for Str/Num, but this seems to trigger bugs when decompiling with
-    # ast_decompiler, which is needed by tests. So we use the more normal
-    # ast that Python 3.7 use for this code.
-    def Constant(arg, **kwargs):
-        if isinstance(arg, str):
-            return ast.Str(arg, **kwargs)
-        elif isinstance(arg, (int, float)):
-            return ast.Num(arg, **kwargs)
-        elif arg is None:
-            return ast.NameConstant(arg, **kwargs)
-        else:
-            raise NotImplementedError(f"Constant not implemented for args of type {type(arg)}")
+    # New versions need nothing.
+    def subscript_slice_object(value: T) -> T:
+        return value

src/fluent_compiler/bundle.py

@@ -1,4 +1,10 @@
-from .compiler import compile_messages
+from __future__ import annotations
+
+from typing import Any, Callable, Sequence
+
+from fluent_compiler.escapers import IsEscaper
+
+from .compiler import CompilationErrorItem, compile_messages
 from .resource import FtlResource
 from .utils import ATTRIBUTE_SEPARATOR, TERM_SIGIL
 
@@ -16,7 +22,14 @@ class FluentBundle:
 
     """
 
-    def __init__(self, locale, resources, functions=None, use_isolating=True, escapers=None):
+    def __init__(
+        self,
+        locale: str,
+        resources: Sequence[FtlResource],
+        functions: dict[str, Callable] | None = None,
+        use_isolating: bool = True,
+        escapers: Sequence[IsEscaper] | None = None,
+    ):
         self.locale = locale
         compiled_ftl = compile_messages(
             locale,
@@ -29,7 +42,14 @@ def __init__(self, locale, resources, functions=None, use_isolating=True, escape
         self._compilation_errors = compiled_ftl.errors
 
     @classmethod
-    def from_string(cls, locale, text, functions=None, use_isolating=True, escapers=None):
+    def from_string(
+        cls,
+        locale: str,
+        text: str,
+        functions: dict[str, Callable] | None = None,
+        use_isolating: bool = True,
+        escapers: Sequence[IsEscaper] | None = None,
+    ) -> FluentBundle:
         return cls(
             locale,
             [FtlResource.from_string(text)],
@@ -48,14 +68,14 @@ def from_files(cls, locale, filenames, functions=None, use_isolating=True, escap
             escapers=escapers,
         )
 
-    def has_message(self, message_id):
+    def has_message(self, message_id: str) -> bool:
         if message_id.startswith(TERM_SIGIL) or ATTRIBUTE_SEPARATOR in message_id:
             return False
         return message_id in self._compiled_messages
 
-    def format(self, message_id, args=None):
+    def format(self, message_id: str, args: Any | None = None) -> Any:
         errors = []
         return self._compiled_messages[message_id](args, errors), errors
 
-    def check_messages(self):
+    def check_messages(self) -> list[CompilationErrorItem]:
         return self._compilation_errors