fluent-codegen 0.1.0__tar.gz → 0.2__tar.gz

{fluent_codegen-0.1.0/src/fluent_codegen.egg-info → fluent_codegen-0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fluent-codegen
-Version: 0.1.0
+Version: 0.2
 Summary: A Python library for generating Python code via AST construction.
 Author-email: Luke Plant <luke@lukeplant.me.uk>
 License-Expression: Apache-2.0
@@ -76,7 +76,7 @@ fluent method-chaining for expressions:
    func, _ = module.create_function("fizzbuzz", args=["n"])
 
    # 2. A Name reference to the "n" parameter (Function *is* a Scope)
-   n = codegen.Name("n", func)
+   n = func.name("n")
 
    # 3. Build an if / elif / else chain
    if_stmt = func.body.create_if()
@@ -94,7 +94,7 @@ fluent method-chaining for expressions:
    branch.create_return(codegen.String("Buzz"))
 
    #    else: return str(n)
-   if_stmt.else_block.create_return(codegen.function_call("str", [n], {}, func))
+   if_stmt.else_block.create_return(module.scope.name("str").call([n]))
 
    # 4. Inspect the generated source
    print(module.as_python_source())

{fluent_codegen-0.1.0 → fluent_codegen-0.2}/README.rst

@@ -54,7 +54,7 @@ fluent method-chaining for expressions:
    func, _ = module.create_function("fizzbuzz", args=["n"])
 
    # 2. A Name reference to the "n" parameter (Function *is* a Scope)
-   n = codegen.Name("n", func)
+   n = func.name("n")
 
    # 3. Build an if / elif / else chain
    if_stmt = func.body.create_if()
@@ -72,7 +72,7 @@ fluent method-chaining for expressions:
    branch.create_return(codegen.String("Buzz"))
 
    #    else: return str(n)
-   if_stmt.else_block.create_return(codegen.function_call("str", [n], {}, func))
+   if_stmt.else_block.create_return(module.scope.name("str").call([n]))
 
    # 4. Inspect the generated source
    print(module.as_python_source())

{fluent_codegen-0.1.0 → fluent_codegen-0.2}/pyproject.toml

@@ -24,8 +24,7 @@ classifiers = [
   "Topic :: Software Development :: Code Generators",
   "Topic :: Software Development :: Libraries :: Python Modules",
 ]
-dynamic = ["version"]
-
+version = "0.2"
 dependencies = []
 
 [project.urls]
@@ -48,8 +47,6 @@ include-package-data = false
 where = ["src"]
 namespaces = false
 
-[tool.setuptools.dynamic]
-version = {attr = "fluent_codegen.__version__"}
 
 [tool.ruff]
 line-length = 120

{fluent_codegen-0.1.0 → fluent_codegen-0.2}/src/fluent_codegen/ast_compat.py

@@ -11,6 +11,7 @@ from typing import TypedDict
 
 Add = ast.Add
 And = ast.And
+Assert = ast.Assert
 Assign = ast.Assign
 AnnAssign = ast.AnnAssign
 BoolOp = ast.BoolOp
@@ -77,6 +78,12 @@ alias = ast.alias
 # It's hard to get something sensible we can put for line/col numbers so we put arbitrary values.
 
 
+try:
+    _Unparser = ast._Unparser  # type: ignore
+except AttributeError:  # pragma: no cover
+    from _ast_unparse import Unparser as _Unparser  # pragma: no cover   # type: ignore
+
+
 class DefaultAstArgs(TypedDict):
     lineno: int
     col_offset: int
@@ -91,3 +98,31 @@ DEFAULT_AST_ARGS_ARGUMENTS: dict[str, object] = dict()
 
 def subscript_slice_object[T](value: T) -> T:
     return value
+
+
+class CommentNode(ast.stmt):
+    """Custom AST statement node representing a comment.
+
+    This is not a standard Python AST node. It is ignored by ``compile()``
+    (callers must strip it first, which ``as_ast()`` does automatically),
+    but is rendered by :func:`unparse_with_comments`.
+    """
+
+    _fields = ("text",)
+
+    def __init__(self, text: str, **kwargs: int) -> None:
+        self.text = text
+        super().__init__(**kwargs)  # type: ignore[reportCallIssue]
+
+
+class _CommentUnparser(_Unparser):  # type: ignore[reportAttributeAccessIssue]
+    """An unparser that knows how to render :class:`CommentNode`."""
+
+    def visit_CommentNode(self, node: CommentNode) -> None:
+        self.fill("# " + node.text)  # type: ignore[reportAttributeAccessIssue]
+
+
+def unparse_with_comments(node: ast.AST) -> str:
+    """Like :func:`ast.unparse`, but also renders :class:`CommentNode` nodes."""
+    unparser = _CommentUnparser()
+    return unparser.visit(node)  # type: ignore[reportUnknownMemberType,reportUnknownVariableType]

{fluent_codegen-0.1.0 → fluent_codegen-0.2}/src/fluent_codegen/codegen.py

@@ -8,6 +8,7 @@ import builtins
 import enum
 import keyword
 import re
+import textwrap
 from abc import ABC, abstractmethod
 from collections.abc import Callable, Sequence
 from dataclasses import dataclass
@@ -19,9 +20,14 @@ from .ast_compat import (
     DEFAULT_AST_ARGS_ADD,
     DEFAULT_AST_ARGS_ARGUMENTS,
     DEFAULT_AST_ARGS_MODULE,
+    CommentNode,
+    unparse_with_comments,
 )
 from .utils import allowable_keyword_arg_name, allowable_name
 
+#: Type alias for comment strings stored in :attr:`Block.statements`.
+Comment = str
+
 # This module provides simple utilities for building up Python source code.
 # The design originally came from fluent-compiler, so had the following aims
 # and constraints:
@@ -61,15 +67,6 @@ from .utils import allowable_keyword_arg_name, allowable_name
 # which have similar aims.
 
 
-PROPERTY_TYPE = "PROPERTY_TYPE"
-PROPERTY_RETURN_TYPE = "PROPERTY_RETURN_TYPE"
-# UNKNOWN_TYPE is just an alias for `object` for clarity.
-UNKNOWN_TYPE: type = object
-# It is important for our usage of it that UNKNOWN_TYPE is a `type`,
-# and the most general `type`.
-assert isinstance(UNKNOWN_TYPE, type)
-
-
 SENSITIVE_FUNCTIONS = {
     # builtin functions that we should never be calling from our code
     # generation. This is a defense-in-depth mechansim to stop our code
@@ -103,15 +100,15 @@ class CodeGenAst(ABC):
     """
 
     @abstractmethod
-    def as_ast(self) -> py_ast.AST: ...
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.AST: ...
 
     child_elements: ClassVar[list[str]]
 
     def as_python_source(self) -> str:
         """Return the Python source code for this AST node."""
-        node = self.as_ast()
+        node = self.as_ast(include_comments=True)
         py_ast.fix_missing_locations(node)
-        return py_ast.unparse(node)
+        return unparse_with_comments(node)
 
 
 class CodeGenAstList(ABC):
@@ -121,15 +118,15 @@ class CodeGenAstList(ABC):
     """
 
     @abstractmethod
-    def as_ast_list(self, allow_empty: bool = True) -> list[py_ast.stmt]: ...
+    def as_ast_list(self, allow_empty: bool = True, *, include_comments: bool = False) -> list[py_ast.stmt]: ...
 
     child_elements: ClassVar[list[str]]
 
     def as_python_source(self) -> str:
         """Return the Python source code for this AST list."""
-        mod = py_ast.Module(body=self.as_ast_list(), type_ignores=[], **DEFAULT_AST_ARGS_MODULE)
+        mod = py_ast.Module(body=self.as_ast_list(include_comments=True), type_ignores=[], **DEFAULT_AST_ARGS_MODULE)
         py_ast.fix_missing_locations(mod)
-        return py_ast.unparse(mod)
+        return unparse_with_comments(mod)
 
 
 CodeGenAstType = CodeGenAst | CodeGenAstList
@@ -204,7 +201,7 @@ class Scope:
             return not self.is_name_reserved(name)
 
         while not _is_name_allowed(attempt):
-            attempt = cleaned + str(count)
+            attempt = cleaned + "_" + str(count)
             count += 1
 
         return _add(attempt)
@@ -270,7 +267,7 @@ class _Annotation(Statement):
         self.name = name
         self.annotation = annotation
 
-    def as_ast(self):
+    def as_ast(self, *, include_comments: bool = False):
         if not allowable_name(self.name):
             raise AssertionError(f"Expected {self.name} to be a valid Python identifier")
         return py_ast.AnnAssign(
@@ -293,7 +290,7 @@ class _Assignment(Statement):
         self.value = value
         self.type_hint = type_hint
 
-    def as_ast(self):
+    def as_ast(self, *, include_comments: bool = False):
         if not allowable_name(self.name):
             raise AssertionError(f"Expected {self.name} to be a valid Python identifier")
         if self.type_hint is None:
@@ -320,32 +317,56 @@ class Block(CodeGenAstList):
 
     def __init__(self, scope: Scope, parent_block: Block | None = None):
         self.scope = scope
-        # We all `Expression` here for things like MethodCall which
-        # are bare expressions that are still useful for side effects
-        self.statements: list[Block | Statement | Expression] = []
+        # We allow `Expression` here for things like MethodCall which
+        # are bare expressions that are still useful for side effects.
+        # `Comment` (str) entries are rendered as ``# text`` comments.
+        self.statements: list[Block | Statement | Expression | Comment] = []
         self.parent_block = parent_block
 
-    def as_ast_list(self, allow_empty: bool = True) -> list[py_ast.stmt]:
+    def as_ast_list(self, allow_empty: bool = True, *, include_comments: bool = False) -> list[py_ast.stmt]:
         retval: list[py_ast.stmt] = []
         for s in self.statements:
+            if isinstance(s, str):
+                # Comment
+                if include_comments:
+                    retval.append(CommentNode(s, **DEFAULT_AST_ARGS))  # type: ignore[reportArgumentType]
+                continue
             if isinstance(s, CodeGenAstList):
-                retval.extend(s.as_ast_list(allow_empty=True))
+                retval.extend(s.as_ast_list(allow_empty=True, include_comments=include_comments))
+            elif isinstance(s, Statement):
+                ast_obj = s.as_ast(include_comments=include_comments)
+                assert isinstance(ast_obj, py_ast.stmt), (
+                    "Statement object return {ast_obj} which is not a subclass of py_ast.stmt"
+                )
+                retval.append(ast_obj)
             else:
-                if isinstance(s, Statement):
-                    ast_obj = s.as_ast()
-                    assert isinstance(ast_obj, py_ast.stmt), (
-                        "Statement object return {ast_obj} which is not a subclass of py_ast.stmt"
-                    )
-                    retval.append(ast_obj)
-                else:
-                    # Things like bare function/method calls need to be wrapped
-                    # in `Expr` to match the way Python parses.
-                    retval.append(py_ast.Expr(s.as_ast(), **DEFAULT_AST_ARGS))
+                # Things like bare function/method calls need to be wrapped
+                # in `Expr` to match the way Python parses.
+                retval.append(py_ast.Expr(s.as_ast(include_comments=include_comments), **DEFAULT_AST_ARGS))
 
         if len(retval) == 0 and not allow_empty:
             return [py_ast.Pass(**DEFAULT_AST_ARGS)]
         return retval
 
+    def add_comment(self, text: str, *, wrap: int | None = None) -> None:
+        """Add a ``# text`` comment line at the current position in the block.
+
+        If *wrap* is given as an integer, long lines are wrapped at word
+        boundaries so that no comment line exceeds *wrap* characters
+        (including the ``# `` prefix).
+        """
+        if wrap is not None:
+            # Account for the "# " prefix (2 chars) that will be added during rendering.
+            effective_width = max(wrap - 2, 1)
+            lines = textwrap.wrap(text, width=effective_width)
+            if not lines:
+                # Empty or whitespace-only text – preserve as a single blank comment.
+                lines = [""]
+            for line in lines:
+                self.statements.append(line)
+        else:
+            self.statements.append(text)
+
     def add_statement(self, statement: Statement | Block | Expression) -> None:
         self.statements.append(statement)
         if isinstance(statement, Block):
@@ -509,6 +530,9 @@ class Block(CodeGenAstList):
     def create_return(self, value: Expression) -> None:
         self.add_statement(Return(value))
 
+    def create_assert(self, test: Expression, msg: Expression | None = None) -> None:
+        self.add_statement(Assert(test, msg))
+
     def create_if(self) -> If:
         """
         Create an If statement, add it to this block, and return it.
@@ -552,18 +576,16 @@ class Module(Block, CodeGenAst):
             for name in dir(builtins):
                 scope.reserve_name(name, is_builtin=True)
         Block.__init__(self, scope)
-        self.file_comments: list[str] = []
 
-    def as_ast(self) -> py_ast.Module:
-        return py_ast.Module(body=self.as_ast_list(), type_ignores=[], **DEFAULT_AST_ARGS_MODULE)
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.Module:
+        return py_ast.Module(
+            body=self.as_ast_list(include_comments=include_comments), type_ignores=[], **DEFAULT_AST_ARGS_MODULE
+        )
 
     def as_python_source(self) -> str:
-        main = super().as_python_source()
-        file_comments = "".join(f"# {comment}\n" for comment in self.file_comments)
-        return file_comments + main
-
-    def add_file_comment(self, comment: str) -> None:
-        self.file_comments.append(comment)
+        mod = self.as_ast(include_comments=True)
+        py_ast.fix_missing_locations(mod)
+        return unparse_with_comments(mod)
 
 
 class ArgKind(enum.Enum):
@@ -677,7 +699,7 @@ class Function(Scope, Statement):
             self.reserve_name(arg.name, function_arg=True)
         self._args = combined
 
-    def as_ast(self) -> py_ast.stmt:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.stmt:
         if not allowable_name(self.func_name):
             raise AssertionError(f"Expected '{self.func_name}' to be a valid Python identifier")
         for arg in self._args:
@@ -716,7 +738,7 @@ class Function(Scope, Statement):
                 defaults=defaults,
                 **DEFAULT_AST_ARGS_ARGUMENTS,
             ),
-            body=self.body.as_ast_list(allow_empty=False),
+            body=self.body.as_ast_list(allow_empty=False, include_comments=include_comments),
             decorator_list=[d.as_ast() for d in self.decorators],
             type_params=[],
             returns=self.return_type.as_ast() if self.return_type is not None else None,
@@ -743,14 +765,14 @@ class Class(Scope, Statement):
         self.bases: list[Expression] = list(bases) if bases else []
         self.decorators: list[Expression] = list(decorators) if decorators else []
 
-    def as_ast(self) -> py_ast.stmt:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.stmt:
         if not allowable_name(self.class_name):
             raise AssertionError(f"Expected '{self.class_name}' to be a valid Python identifier")
         return py_ast.ClassDef(
             name=self.class_name,
             bases=[b.as_ast() for b in self.bases],
             keywords=[],
-            body=self.body.as_ast_list(allow_empty=False),
+            body=self.body.as_ast_list(allow_empty=False, include_comments=include_comments),
             decorator_list=[d.as_ast() for d in self.decorators],
             type_params=[],
             **DEFAULT_AST_ARGS,
@@ -763,13 +785,34 @@ class Return(Statement):
     def __init__(self, value: Expression):
         self.value = value
 
-    def as_ast(self):
+    def as_ast(self, *, include_comments: bool = False):
         return py_ast.Return(self.value.as_ast(), **DEFAULT_AST_ARGS)
 
     def __repr__(self):
         return f"Return({repr(self.value)}"
 
 
+class Assert(Statement):
+    """An ``assert`` statement with an optional message."""
+
+    child_elements = ["test", "msg"]
+
+    def __init__(self, test: Expression, msg: Expression | None = None):
+        self.test = test
+        self.msg = msg
+
+    def as_ast(self, *, include_comments: bool = False):
+        msg_ast = self.msg.as_ast() if self.msg is not None else None
+        return py_ast.Assert(
+            test=self.test.as_ast(),
+            msg=msg_ast,
+            **DEFAULT_AST_ARGS,
+        )
+
+    def __repr__(self):
+        return f"Assert({repr(self.test)}, {repr(self.msg)})"
+
+
 class If(Statement):
     child_elements = ["if_blocks", "conditions", "else_block"]
 
@@ -801,7 +844,7 @@ class If(Statement):
             return self.else_block
         return self
 
-    def as_ast(self) -> py_ast.If:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.If:
         if len(self.if_blocks) == 0:
             raise AssertionError("Should have called `finalize` on If")
         if_ast = empty_If()
@@ -809,7 +852,7 @@ class If(Statement):
         previous_if = None
         for condition, if_block in zip(self.conditions, self.if_blocks):
             current_if.test = condition.as_ast()
-            current_if.body = if_block.as_ast_list()
+            current_if.body = if_block.as_ast_list(include_comments=include_comments)
             if previous_if is not None:
                 previous_if.orelse.append(current_if)
 
@@ -818,7 +861,7 @@ class If(Statement):
 
         if self.else_block.statements:
             assert previous_if is not None
-            previous_if.orelse = self.else_block.as_ast_list()
+            previous_if.orelse = self.else_block.as_ast_list(include_comments=include_comments)
 
         return if_ast
 
@@ -840,7 +883,7 @@ class With(Statement):
         self._parent_block = parent_block
         self.body = Block(parent_scope, parent_block=parent_block)
 
-    def as_ast(self) -> py_ast.With:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.With:
         optional_vars = None
         if self.target is not None:
             optional_vars = py_ast.Name(id=self.target.name, ctx=py_ast.Store(), **DEFAULT_AST_ARGS)
@@ -852,7 +895,7 @@ class With(Statement):
                     optional_vars=optional_vars,
                 )
             ],
-            body=self.body.as_ast_list(allow_empty=False),
+            body=self.body.as_ast_list(allow_empty=False, include_comments=include_comments),
             **DEFAULT_AST_ARGS,
         )
 
@@ -866,9 +909,9 @@ class Try(Statement):
         self.except_block = Block(parent_scope)
         self.else_block = Block(parent_scope)
 
-    def as_ast(self) -> py_ast.Try:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.Try:
         return py_ast.Try(
-            body=self.try_block.as_ast_list(allow_empty=False),
+            body=self.try_block.as_ast_list(allow_empty=False, include_comments=include_comments),
             handlers=[
                 py_ast.ExceptHandler(
                     type=(
@@ -881,11 +924,11 @@ class Try(Statement):
                         )
                     ),
                     name=None,
-                    body=self.except_block.as_ast_list(allow_empty=False),
+                    body=self.except_block.as_ast_list(allow_empty=False, include_comments=include_comments),
                     **DEFAULT_AST_ARGS,
                 )
             ],
-            orelse=self.else_block.as_ast_list(allow_empty=True),
+            orelse=self.else_block.as_ast_list(allow_empty=True, include_comments=include_comments),
             finalbody=[],
             **DEFAULT_AST_ARGS,
         )
@@ -916,7 +959,7 @@ class Import(Statement):
         self.module = module
         self.as_ = as_
 
-    def as_ast(self) -> py_ast.AST:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.AST:
         if self.as_ is None:
             # No alias needed:
             return py_ast.Import(names=[py_ast.alias(name=self.module)], **DEFAULT_AST_ARGS)
@@ -941,7 +984,7 @@ class ImportFrom(Statement):
         self.import_ = import_
         self.as_ = as_
 
-    def as_ast(self) -> py_ast.AST:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.AST:
         if self.as_ is None:
             # No alias needed:
             return py_ast.ImportFrom(
@@ -961,7 +1004,7 @@ class ImportFrom(Statement):
 
 class Expression(CodeGenAst):
     @abstractmethod
-    def as_ast(self) -> py_ast.expr: ...
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr: ...
 
     # Some utilities for easy chaining:
 
@@ -983,6 +1026,9 @@ class Expression(CodeGenAst):
     ) -> Call:
         return self.attr(attribute).call(args, kwargs)
 
+    def subscript(self, slice: Expression, /) -> Subscript:
+        return Subscript(self, slice)
+
     # Arithmetic operators
 
     def add(self, other: Expression, /) -> Add:
@@ -1054,12 +1100,10 @@ class Expression(CodeGenAst):
 class String(Expression):
     child_elements = []
 
-    type = str
-
     def __init__(self, string_value: str):
         self.string_value = string_value
 
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         return py_ast.Constant(
             self.string_value,
             kind=None,  # 3.8, indicates no prefix, needed only for tests
@@ -1076,12 +1120,10 @@ class String(Expression):
 class Bool(Expression):
     child_elements = []
 
-    type = bool
-
     def __init__(self, value: bool):
         self.value = value
 
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         return py_ast.Constant(self.value, **DEFAULT_AST_ARGS)
 
     def __repr__(self):
@@ -1091,12 +1133,10 @@ class Bool(Expression):
 class Bytes(Expression):
     child_elements = []
 
-    type = bytes
-
     def __init__(self, value: bytes):
         self.value = value
 
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         return py_ast.Constant(self.value, **DEFAULT_AST_ARGS)
 
     def __repr__(self):
@@ -1109,7 +1149,7 @@ class Number(Expression):
     def __init__(self, number: int | float):
         self.number = number
 
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         return py_ast.Constant(self.number, **DEFAULT_AST_ARGS)
 
     def __repr__(self):
@@ -1122,7 +1162,7 @@ class List(Expression):
     def __init__(self, items: list[Expression]):
         self.items = items
 
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         return py_ast.List(elts=[i.as_ast() for i in self.items], ctx=py_ast.Load(), **DEFAULT_AST_ARGS)
 
 
@@ -1132,7 +1172,7 @@ class Tuple(Expression):
     def __init__(self, items: Sequence[Expression]):
         self.items = items
 
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         return py_ast.Tuple(elts=[i.as_ast() for i in self.items], ctx=py_ast.Load(), **DEFAULT_AST_ARGS)
 
 
@@ -1142,7 +1182,7 @@ class Set(Expression):
     def __init__(self, items: Sequence[Expression]):
         self.items = items
 
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         if len(self.items) == 0:
             # {} is a dict literal in Python, so empty sets must use set([])
             return py_ast.Call(
@@ -1160,7 +1200,7 @@ class Dict(Expression):
     def __init__(self, pairs: Sequence[tuple[Expression, Expression]]):
         self.pairs = pairs
 
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         return py_ast.Dict(
             keys=[k.as_ast() for k, _ in self.pairs],
             values=[v.as_ast() for _, v in self.pairs],
@@ -1171,8 +1211,6 @@ class Dict(Expression):
 class StringJoinBase(Expression):
     child_elements = ["parts"]
 
-    type = str
-
     def __init__(self, parts: Sequence[Expression]):
         self.parts = parts
 
@@ -1202,7 +1240,7 @@ class StringJoinBase(Expression):
 
 
 class FStringJoin(StringJoinBase):
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         # f-strings
         values: list[py_ast.expr] = []
         for part in self.parts:
@@ -1221,7 +1259,7 @@ class FStringJoin(StringJoinBase):
 
 
 class ConcatJoin(StringJoinBase):
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         # Concatenate with +
         left = self.parts[0].as_ast()
         for part in self.parts[1:]:
@@ -1249,7 +1287,7 @@ class Name(Expression):
             raise AssertionError(f"Cannot refer to undefined name '{name}'")
         self.name = name
 
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         if not allowable_name(self.name, allow_builtin=True):
             raise AssertionError(f"Expected {self.name} to be a valid Python identifier")
         return py_ast.Name(id=self.name, ctx=py_ast.Load(), **DEFAULT_AST_ARGS)
@@ -1270,7 +1308,7 @@ class Attr(Expression):
             raise AssertionError(f"Expected {attribute} to be a valid Python identifier")
         self.attribute = attribute
 
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         return py_ast.Attribute(value=self.value.as_ast(), attr=self.attribute, **DEFAULT_AST_ARGS)
 
 
@@ -1280,7 +1318,7 @@ class Starred(Expression):
     def __init__(self, value: Expression):
         self.value = value
 
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         return py_ast.Starred(value=self.value.as_ast(), ctx=py_ast.Load(), **DEFAULT_AST_ARGS)
 
     def __repr__(self):
@@ -1314,7 +1352,7 @@ class Call(Expression):
         self.args = list(args)
         self.kwargs = kwargs
 
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
 
         for name in self.kwargs.keys():
             if not allowable_keyword_arg_name(name):
@@ -1373,17 +1411,17 @@ def method_call(
     return obj.attr(method_name).call(args=args, kwargs=kwargs)
 
 
-class DictLookup(Expression):
-    child_elements = ["lookup_obj", "lookup_arg"]
+class Subscript(Expression):
+    child_elements = ["value", "slice"]
 
-    def __init__(self, lookup_obj: Expression, lookup_arg: Expression):
-        self.lookup_obj = lookup_obj
-        self.lookup_arg = lookup_arg
+    def __init__(self, value: Expression, slice: Expression):
+        self.value = value
+        self.slice = slice
 
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         return py_ast.Subscript(
-            value=self.lookup_obj.as_ast(),
-            slice=py_ast.subscript_slice_object(self.lookup_arg.as_ast()),
+            value=self.value.as_ast(),
+            slice=py_ast.subscript_slice_object(self.slice.as_ast()),
             ctx=py_ast.Load(),
             **DEFAULT_AST_ARGS,
         )
@@ -1393,9 +1431,7 @@ create_class_instance = function_call
 
 
 class NoneExpr(Expression):
-    type = type(None)
-
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         return py_ast.Constant(value=None, **DEFAULT_AST_ARGS)
 
 
@@ -1412,7 +1448,7 @@ class ArithOp(BinaryOperator, ABC):
 
     op: ClassVar[type[py_ast.operator]]
 
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         return py_ast.BinOp(
             left=self.left.as_ast(),
             op=self.op(**DEFAULT_AST_ARGS_ADD),
@@ -1456,10 +1492,9 @@ class MatMul(ArithOp):
 class CompareOp(BinaryOperator, ABC):
     """Comparison operator (ast.Compare)."""
 
-    type = bool
     op: ClassVar[type[py_ast.cmpop]]
 
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         return py_ast.Compare(
             left=self.left.as_ast(),
             comparators=[self.right.as_ast()],
@@ -1501,10 +1536,9 @@ class NotIn(CompareOp):
 
 
 class BoolOp(BinaryOperator, ABC):
-    type = bool
     op: ClassVar[type[py_ast.boolop]]
 
-    def as_ast(self) -> py_ast.expr:
+    def as_ast(self, *, include_comments: bool = False) -> py_ast.expr:
         return py_ast.BoolOp(
             op=self.op(),
             values=[self.left.as_ast(), self.right.as_ast()],
@@ -1631,7 +1665,7 @@ def auto(value: PythonObj) -> Expression:
     elif isinstance(value, (int, float)):
         return Number(value)
     elif value is None:
-        return NoneExpr()
+        return constants.None_
     elif isinstance(value, list):
         return List([auto(item) for item in value])
     elif isinstance(value, tuple):
@@ -1648,6 +1682,6 @@ class constants:
     Useful pre-made Expression constants
     """
 
-    None_: NoneExpr = auto(None)
+    None_: NoneExpr = NoneExpr()
     True_: Bool = auto(True)
     False_: Bool = auto(False)

{fluent_codegen-0.1.0 → fluent_codegen-0.2/src/fluent_codegen.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fluent-codegen
-Version: 0.1.0
+Version: 0.2
 Summary: A Python library for generating Python code via AST construction.
 Author-email: Luke Plant <luke@lukeplant.me.uk>
 License-Expression: Apache-2.0
@@ -76,7 +76,7 @@ fluent method-chaining for expressions:
    func, _ = module.create_function("fizzbuzz", args=["n"])
 
    # 2. A Name reference to the "n" parameter (Function *is* a Scope)
-   n = codegen.Name("n", func)
+   n = func.name("n")
 
    # 3. Build an if / elif / else chain
    if_stmt = func.body.create_if()
@@ -94,7 +94,7 @@ fluent method-chaining for expressions:
    branch.create_return(codegen.String("Buzz"))
 
    #    else: return str(n)
-   if_stmt.else_block.create_return(codegen.function_call("str", [n], {}, func))
+   if_stmt.else_block.create_return(module.scope.name("str").call([n]))
 
    # 4. Inspect the generated source
    print(module.as_python_source())

{fluent_codegen-0.1.0 → fluent_codegen-0.2}/tests/test_codegen.py

@@ -41,7 +41,7 @@ def test_reserve_name():
     name2 = scope.reserve_name("name")
     assert name1 == "name"
     assert name1 != name2
-    assert name2 == "name2"
+    assert name2 == "name_2"
 
 
 def test_reserve_name_function_arg_disallowed():
@@ -81,7 +81,7 @@ def test_reserve_name_after_reserve_function_arg():
     scope = codegen.Scope()
     scope.reserve_function_arg_name("my_arg")
     name = scope.reserve_name("my_arg")
-    assert name == "my_arg2"
+    assert name == "my_arg_2"
 
 
 def test_reserve_function_arg_after_reserve_name():
@@ -127,6 +127,47 @@ def test_function_return():
     )
 
 
+def test_create_assert():
+    module = codegen.Module()
+    func = codegen.Function("myfunc", args=["x"], parent_scope=module.scope)
+    func.body.create_assert(func.name("x"))
+    assert_code_equal(
+        func,
+        """
+        def myfunc(x):
+            assert x
+        """,
+    )
+
+
+def test_create_assert_with_message():
+    module = codegen.Module()
+    func = codegen.Function("myfunc", args=["x"], parent_scope=module.scope)
+    func.body.create_assert(func.name("x"), codegen.String("x must be truthy"))
+    assert_code_equal(
+        func,
+        """
+        def myfunc(x):
+            assert x, 'x must be truthy'
+        """,
+    )
+
+
+def test_assert_class_directly():
+    assert_stmt = codegen.Assert(codegen.Number(1))
+    assert_code_equal(assert_stmt, "assert 1")
+
+
+def test_assert_class_with_message_directly():
+    assert_stmt = codegen.Assert(codegen.Number(0), codegen.String("fail"))
+    assert_code_equal(assert_stmt, "assert 0, 'fail'")
+
+
+def test_assert_repr():
+    assert_stmt = codegen.Assert(codegen.Number(1))
+    assert "Assert(" in repr(assert_stmt)
+
+
 def test_function_bad_name():
     module = codegen.Module()
     func = codegen.Function("my func", args=[], parent_scope=module.scope)
@@ -390,7 +431,7 @@ def test_create_annotation_duplicate_name_gets_renamed():
     module = codegen.Module()
     module.create_annotation("x", module.scope.name("int"))
     name2 = module.create_annotation("x", module.scope.name("str"))
-    assert_code_equal(name2, "x2")
+    assert_code_equal(name2, "x_2")
 
 
 def test_create_annotation_bad_name():
@@ -470,7 +511,7 @@ def test_create_field_duplicate_name_gets_renamed():
     module = codegen.Module()
     module.create_field("x", module.scope.name("int"))
     name2 = module.create_field("x", module.scope.name("str"))
-    assert_code_equal(name2, "x2")
+    assert_code_equal(name2, "x_2")
 
 
 # --- Function call tests ---
@@ -713,7 +754,7 @@ def test_if_scope():
     assert if_block.scope.is_name_in_use("myvalue")
 
     name_in_if_block = if_block.scope.reserve_name("myvalue")
-    assert name_in_if_block == "myvalue2"
+    assert name_in_if_block == "myvalue_2"
 
 
 def test_block_create_if():
@@ -1043,10 +1084,10 @@ def test_string_join_collapse_strings():
     assert_code_equal(join1, "'hello there ' + tmp + ' how are you?'")
 
 
-def test_dict_lookup():
+def test_subscript():
     scope = codegen.Scope()
     var = scope.create_name("tmp")
-    lookup = codegen.DictLookup(var, codegen.String("x"))
+    lookup = var.subscript(codegen.String("x"))
     assert_code_equal(lookup, "tmp['x']")
 
 
@@ -1108,7 +1149,7 @@ def test_reserve_name_keyword_avoidance():
     scope = codegen.Scope()
     # 'class' is a keyword, so reserve_name should avoid it
     name = scope.reserve_name("class")
-    assert name == "class2"  # skips 'class' because it's a keyword
+    assert name == "class_2"  # skips 'class' because it's a keyword
 
 
 def test_block_add_statement_bare_expression():
@@ -1172,7 +1213,6 @@ def test_dict_expression():
 
 def test_none_expr():
     n = codegen.NoneExpr()
-    assert n.type is type(None)
     assert_code_equal(n, "None")
 
 
@@ -1266,32 +1306,6 @@ def test_morph_into():
     assert s1.number == 42
 
 
-def test_codegen_ast_not_implemented():
-    """Test that abstract methods raise NotImplementedError."""
-
-    class DummyAst(codegen.CodeGenAst):
-        child_elements = []
-
-        def as_ast(self):
-            raise NotImplementedError(f"{self.__class__!r}.as_ast()")
-
-    d = DummyAst()
-    with pytest.raises(NotImplementedError):
-        d.as_ast()
-
-
-def test_codegen_ast_list_not_implemented():
-    class DummyAstList(codegen.CodeGenAstList):
-        child_elements = []
-
-        def as_ast_list(self, allow_empty=True):
-            raise NotImplementedError(f"{self.__class__!r}.as_ast_list()")
-
-    d = DummyAstList()
-    with pytest.raises(NotImplementedError):
-        d.as_ast_list()
-
-
 def test_block_as_ast_list_with_codegen_ast_list():
     """Test that Block handles CodeGenAstList sub-statements."""
     module = codegen.Module()
@@ -1406,13 +1420,11 @@ def test_auto_unsupported_type():
 
 def test_bool_true():
     b = codegen.Bool(True)
-    assert b.type is bool
     assert_code_equal(b, "True")
 
 
 def test_bool_false():
     b = codegen.Bool(False)
-    assert b.type is bool
     assert_code_equal(b, "False")
 
 
@@ -1438,7 +1450,6 @@ def test_auto_bool_false():
 
 def test_bytes():
     b = codegen.Bytes(b"hello")
-    assert b.type is bytes
     assert_code_equal(b, "b'hello'")
 
 
@@ -1522,29 +1533,6 @@ def test_auto_frozenset():
 # The classes are tested indirectly by the utilty methods on `Expression`,
 # we don't really need separate tests.
 
-# --- Comparison operator type ---
-
-
-def test_comparison_ops_have_bool_type():
-    a, b = codegen.Number(1), codegen.Number(2)
-    for cls in (
-        codegen.Equals,
-        codegen.NotEquals,
-        codegen.Lt,
-        codegen.Gt,
-        codegen.LtE,
-        codegen.GtE,
-        codegen.In,
-        codegen.NotIn,
-    ):
-        assert cls(a, b).type is bool
-
-
-def test_boolean_ops_have_bool_type():
-    a, b = codegen.Bool(True), codegen.Bool(False)
-    assert codegen.And(a, b).type is bool
-    assert codegen.Or(a, b).type is bool
-
 
 # --- Expression utility method tests ---
 
@@ -2653,9 +2641,9 @@ def test_module_reserves_builtins_by_default():
     assert mod.scope.is_name_reserved("str")
 
 
-def test_module_comment():
+def test_block_add_comment():
     mod = codegen.Module()
-    mod.add_file_comment("Hello")
+    mod.add_comment("Hello")
     mod.create_import("foo")
     assert_code_equal(
         mod,
@@ -2664,3 +2652,160 @@ def test_module_comment():
         import foo
         """,
     )
+
+
+def test_comment_in_function_body():
+    mod = codegen.Module()
+    func, _ = mod.create_function("my_func", args=["x"])
+    func.body.add_comment("Process the value")
+    x = codegen.Name("x", func)
+    func.body.create_return(x)
+    assert_code_equal(
+        mod,
+        """
+        def my_func(x):
+            # Process the value
+            return x
+        """,
+    )
+
+
+def test_comment_in_class_body():
+    mod = codegen.Module()
+    cls, _ = mod.create_class("MyClass")
+    cls.body.add_comment("Class fields")
+    cls.body.create_field("name", codegen.Name("str", mod.scope))
+    assert_code_equal(
+        mod,
+        """
+        class MyClass:
+            # Class fields
+            name: str
+        """,
+    )
+
+
+def test_multiple_comments():
+    mod = codegen.Module()
+    mod.add_comment("First comment")
+    mod.add_comment("Second comment")
+    mod.create_import("foo")
+    assert_code_equal(
+        mod,
+        """
+        # First comment
+        # Second comment
+        import foo
+        """,
+    )
+
+
+def test_comment_compile_constraint():
+    """Comments must not affect compile() — as_ast() must return a compilable AST."""
+    mod = codegen.Module()
+    mod.add_comment("This is a comment")
+    func, _ = mod.create_function("greet", args=["name"])
+    func.body.add_comment("Return greeting")
+    func.body.create_return(codegen.String("hello"))
+
+    # as_ast() must be compilable
+    ast_tree = mod.as_ast()
+    code = compile(ast_tree, "<test>", "exec")
+    ns: dict[str, object] = {}
+    exec(code, ns)
+    assert ns["greet"]("world") == "hello"  # type: ignore
+
+
+def test_comment_source_constraint():
+    """as_python_source() must include the comments."""
+    mod = codegen.Module()
+    mod.add_comment("File header")
+    mod.create_import("os")
+    source = mod.as_python_source()
+    assert "# File header" in source
+    assert "import os" in source
+
+
+def test_comment_interleaved_with_statements():
+    mod = codegen.Module()
+    mod.create_import("os")
+    mod.add_comment("Now import sys")
+    mod.create_import("sys")
+    assert_code_equal(
+        mod,
+        """
+        import os
+        # Now import sys
+        import sys
+        """,
+    )
+
+
+def test_comment_only_block():
+    """A block with only comments should compile (comments stripped = empty body)."""
+    mod = codegen.Module()
+    mod.add_comment("Just a comment")
+    ast_tree = mod.as_ast()
+    code = compile(ast_tree, "<test>", "exec")
+    ns: dict[str, object] = {}
+    exec(code, ns)
+    # Should execute without error
+
+
+def test_add_comment_wrap_basic():
+    mod = codegen.Module()
+    mod.add_comment("This is a long comment that should be wrapped into multiple lines", wrap=40)
+    mod.create_import("foo")
+    assert_code_equal(
+        mod,
+        """
+        # This is a long comment that should be
+        # wrapped into multiple lines
+        import foo
+        """,
+    )
+
+
+def test_add_comment_wrap_short_text_unchanged():
+    """Text shorter than wrap width should remain a single comment."""
+    mod = codegen.Module()
+    mod.add_comment("Short", wrap=80)
+    assert_code_equal(
+        mod,
+        """
+        # Short
+        """,
+    )
+
+
+def test_add_comment_wrap_none_default():
+    """Without wrap, long text stays on one line."""
+    mod = codegen.Module()
+    long_text = "word " * 30
+    mod.add_comment(long_text.strip())
+    source = mod.as_python_source()
+    comment_lines = [line for line in source.splitlines() if line.startswith("#")]
+    assert len(comment_lines) == 1
+
+
+def test_add_comment_wrap_in_function_body():
+    mod = codegen.Module()
+    func, _ = mod.create_function("f", args=[])
+    func.body.add_comment("This is a very detailed explanation of what the function does", wrap=40)
+    func.body.create_return(codegen.Number(1))
+    assert_code_equal(
+        mod,
+        """
+        def f():
+            # This is a very detailed explanation of
+            # what the function does
+            return 1
+        """,
+    )
+
+
+def test_add_comment_wrap_empty_string():
+    mod = codegen.Module()
+    mod.add_comment("", wrap=40)
+    source = mod.as_python_source()
+    assert "#" in source

{fluent_codegen-0.1.0 → fluent_codegen-0.2}/tests/test_fizzbuzz_example.py

@@ -12,7 +12,7 @@ def _build_fizzbuzz_module() -> codegen.Module:
     module = codegen.Module()
     func, _ = module.create_function("fizzbuzz", args=["n"])
 
-    n = codegen.Name("n", func)
+    n = func.name("n")
 
     if_stmt = func.body.create_if()
 
@@ -29,7 +29,7 @@ def _build_fizzbuzz_module() -> codegen.Module:
     branch_5.create_return(codegen.String("Buzz"))
 
     # else: return str(n)
-    if_stmt.else_block.create_return(codegen.function_call("str", [n], {}, func))
+    if_stmt.else_block.create_return(module.scope.name("str").call([n]))
 
     return module
 

fluent_codegen-0.1.0/src/fluent_codegen/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.1.0"