fluent-codegen 0.1.0__tar.gz

fluent_codegen-0.1.0/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Luke Plant
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

fluent_codegen-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: fluent-codegen
+Version: 0.1.0
+Summary: A Python library for generating Python code via AST construction.
+Author-email: Luke Plant <luke@lukeplant.me.uk>
+License-Expression: Apache-2.0
+Project-URL: Repository, https://github.com/spookylukey/fluent-codegen
+Keywords: codegen,code-generation,ast,python,metaprogramming
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Dynamic: license-file
+
+fluent-codegen
+==============
+
+A Python library for generating Python code via AST construction.
+
+Overview
+--------
+
+``fluent-codegen`` provides a set of classes that represent simplified
+Python constructs (functions, assignments, expressions, control flow,
+etc.) and can generate real Python ``ast`` nodes. This lets you build
+correct Python code programmatically without manipulating raw AST or
+worrying about string interpolation pitfalls.
+
+Originally extracted from
+`fluent-compiler <https://github.com/django-ftl/fluent-compiler>`__,
+where it was used to compile Fluent localization files into Python
+bytecode.
+
+Key features
+------------
+
+-  **Safe by construction** — builds AST, not strings, eliminating
+   injection bugs
+-  **Scope management** — automatic name deduplication and scope
+   tracking
+-  **Simplified API** — high-level classes (``Function``, ``If``,
+   ``Try``, ``StringJoin``, etc.) that map to Python constructs without
+   requiring knowledge of the raw ``ast`` module
+-  **Security guardrails** — blocks calls to sensitive builtins
+   (``exec``, ``eval``, etc.)
+
+Installation
+------------
+
+.. code:: bash
+
+   pip install fluent-codegen
+
+Requires Python 3.12+.
+
+Quick example
+-------------
+
+This builds a FizzBuzz function entirely via the codegen API, using
+fluent method-chaining for expressions:
+
+.. code:: python
+
+   from fluent_codegen import codegen
+
+   # 1. Create a module and a function inside it
+   module = codegen.Module()
+   func, _ = module.create_function("fizzbuzz", args=["n"])
+
+   # 2. A Name reference to the "n" parameter (Function *is* a Scope)
+   n = codegen.Name("n", func)
+
+   # 3. Build an if / elif / else chain
+   if_stmt = func.body.create_if()
+
+   #    if n % 15 == 0: return "FizzBuzz"   — fluent chaining
+   branch = if_stmt.create_if_branch(n.mod(codegen.Number(15)).eq(codegen.Number(0)))
+   branch.create_return(codegen.String("FizzBuzz"))
+
+   #    elif n % 3 == 0: return "Fizz"
+   branch = if_stmt.create_if_branch(n.mod(codegen.Number(3)).eq(codegen.Number(0)))
+   branch.create_return(codegen.String("Fizz"))
+
+   #    elif n % 5 == 0: return "Buzz"
+   branch = if_stmt.create_if_branch(n.mod(codegen.Number(5)).eq(codegen.Number(0)))
+   branch.create_return(codegen.String("Buzz"))
+
+   #    else: return str(n)
+   if_stmt.else_block.create_return(codegen.function_call("str", [n], {}, func))
+
+   # 4. Inspect the generated source
+   print(module.as_python_source())
+   # def fizzbuzz(n):
+   #     if n % 15 == 0:
+   #         return 'FizzBuzz'
+   #     elif n % 3 == 0:
+   #         return 'Fizz'
+   #     elif n % 5 == 0:
+   #         return 'Buzz'
+   #     else:
+   #         return str(n)
+
+   # 5. Compile, execute, and call the generated function
+   code = compile(module.as_ast(), "<fizzbuzz>", "exec")
+   ns: dict[str, object] = {}
+   exec(code, ns)
+   fizzbuzz = ns["fizzbuzz"]
+   assert fizzbuzz(15) == "FizzBuzz"
+   assert fizzbuzz(9)  == "Fizz"
+   assert fizzbuzz(10) == "Buzz"
+   assert fizzbuzz(7)  == "7"
+
+License
+-------
+
+Apache License 2.0

fluent_codegen-0.1.0/README.rst

@@ -0,0 +1,102 @@
+fluent-codegen
+==============
+
+A Python library for generating Python code via AST construction.
+
+Overview
+--------
+
+``fluent-codegen`` provides a set of classes that represent simplified
+Python constructs (functions, assignments, expressions, control flow,
+etc.) and can generate real Python ``ast`` nodes. This lets you build
+correct Python code programmatically without manipulating raw AST or
+worrying about string interpolation pitfalls.
+
+Originally extracted from
+`fluent-compiler <https://github.com/django-ftl/fluent-compiler>`__,
+where it was used to compile Fluent localization files into Python
+bytecode.
+
+Key features
+------------
+
+-  **Safe by construction** — builds AST, not strings, eliminating
+   injection bugs
+-  **Scope management** — automatic name deduplication and scope
+   tracking
+-  **Simplified API** — high-level classes (``Function``, ``If``,
+   ``Try``, ``StringJoin``, etc.) that map to Python constructs without
+   requiring knowledge of the raw ``ast`` module
+-  **Security guardrails** — blocks calls to sensitive builtins
+   (``exec``, ``eval``, etc.)
+
+Installation
+------------
+
+.. code:: bash
+
+   pip install fluent-codegen
+
+Requires Python 3.12+.
+
+Quick example
+-------------
+
+This builds a FizzBuzz function entirely via the codegen API, using
+fluent method-chaining for expressions:
+
+.. code:: python
+
+   from fluent_codegen import codegen
+
+   # 1. Create a module and a function inside it
+   module = codegen.Module()
+   func, _ = module.create_function("fizzbuzz", args=["n"])
+
+   # 2. A Name reference to the "n" parameter (Function *is* a Scope)
+   n = codegen.Name("n", func)
+
+   # 3. Build an if / elif / else chain
+   if_stmt = func.body.create_if()
+
+   #    if n % 15 == 0: return "FizzBuzz"   — fluent chaining
+   branch = if_stmt.create_if_branch(n.mod(codegen.Number(15)).eq(codegen.Number(0)))
+   branch.create_return(codegen.String("FizzBuzz"))
+
+   #    elif n % 3 == 0: return "Fizz"
+   branch = if_stmt.create_if_branch(n.mod(codegen.Number(3)).eq(codegen.Number(0)))
+   branch.create_return(codegen.String("Fizz"))
+
+   #    elif n % 5 == 0: return "Buzz"
+   branch = if_stmt.create_if_branch(n.mod(codegen.Number(5)).eq(codegen.Number(0)))
+   branch.create_return(codegen.String("Buzz"))
+
+   #    else: return str(n)
+   if_stmt.else_block.create_return(codegen.function_call("str", [n], {}, func))
+
+   # 4. Inspect the generated source
+   print(module.as_python_source())
+   # def fizzbuzz(n):
+   #     if n % 15 == 0:
+   #         return 'FizzBuzz'
+   #     elif n % 3 == 0:
+   #         return 'Fizz'
+   #     elif n % 5 == 0:
+   #         return 'Buzz'
+   #     else:
+   #         return str(n)
+
+   # 5. Compile, execute, and call the generated function
+   code = compile(module.as_ast(), "<fizzbuzz>", "exec")
+   ns: dict[str, object] = {}
+   exec(code, ns)
+   fizzbuzz = ns["fizzbuzz"]
+   assert fizzbuzz(15) == "FizzBuzz"
+   assert fizzbuzz(9)  == "Fizz"
+   assert fizzbuzz(10) == "Buzz"
+   assert fizzbuzz(7)  == "7"
+
+License
+-------
+
+Apache License 2.0

fluent_codegen-0.1.0/pyproject.toml

@@ -0,0 +1,84 @@
+[project]
+name = "fluent-codegen"
+description = "A Python library for generating Python code via AST construction."
+license = "Apache-2.0"
+authors = [
+    { name = "Luke Plant", email = "luke@lukeplant.me.uk" }
+]
+requires-python = ">=3.12"
+keywords = [
+  "codegen",
+  "code-generation",
+  "ast",
+  "python",
+  "metaprogramming",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Topic :: Software Development :: Code Generators",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dynamic = ["version"]
+
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/spookylukey/fluent-codegen"
+
+
+[project.readme]
+file = "README.rst"
+content-type = "text/x-rst"
+
+[build-system]
+requires = ["setuptools>=61.2"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+include-package-data = false
+
+[tool.setuptools.packages.find]
+where = ["src"]
+namespaces = false
+
+[tool.setuptools.dynamic]
+version = {attr = "fluent_codegen.__version__"}
+
+[tool.ruff]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+ignore = ["E501", "E731"]
+extend-select = [
+  "UP",
+  "I",
+  "FLY",
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["fluent_codegen"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--cov=fluent_codegen --cov-fail-under=100"
+
+[dependency-groups]
+dev = [
+    "hypothesis>=4.9.0",
+    "pre-commit>=4.5.1",
+    "pyright==1.1.406",
+    "pytest>=7.4.4",
+    "pytest-cov>=7.0.0",
+    "ruff>=0.4.0",
+    "tox>=4.36.0",
+    "tox-uv>=1.29.0",
+]
+

fluent_codegen-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fluent_codegen-0.1.0/src/fluent_codegen/__init__.py

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

fluent_codegen-0.1.0/src/fluent_codegen/ast_compat.py

@@ -0,0 +1,93 @@
+"""Compatibility module for generating Python AST.
+
+Provides a curated subset of the stdlib `ast` module used by the codegen module.
+"""
+
+import ast
+from typing import TypedDict
+
+# This is a very limited subset of Python AST:
+# - only the things needed by codegen.py
+
+Add = ast.Add
+And = ast.And
+Assign = ast.Assign
+AnnAssign = ast.AnnAssign
+BoolOp = ast.BoolOp
+BinOp = ast.BinOp
+Compare = ast.Compare
+Dict = ast.Dict
+Div = ast.Div
+Eq = ast.Eq
+ExceptHandler = ast.ExceptHandler
+Expr = ast.Expr
+FloorDiv = ast.FloorDiv
+Gt = ast.Gt
+GtE = ast.GtE
+If = ast.If
+In = ast.In
+List = ast.List
+Load = ast.Load
+Lt = ast.Lt
+LtE = ast.LtE
+Mod = ast.Mod
+Module = ast.Module
+Mult = ast.Mult
+MatMult = ast.MatMult
+NotEq = ast.NotEq
+NotIn = ast.NotIn
+Or = ast.Or
+Pow = ast.Pow
+Sub = ast.Sub
+boolop = ast.boolop
+cmpop = ast.cmpop
+operator = ast.operator
+Pass = ast.Pass
+Return = ast.Return
+Set = ast.Set
+Starred = ast.Starred
+Store = ast.Store
+Subscript = ast.Subscript
+Tuple = ast.Tuple
+arguments = ast.arguments
+JoinedStr = ast.JoinedStr
+FormattedValue = ast.FormattedValue
+Attribute = ast.Attribute
+Call = ast.Call
+FunctionDef = ast.FunctionDef
+Name = ast.Name
+Try = ast.Try
+With = ast.With
+withitem = ast.withitem
+arg = ast.arg
+keyword = ast.keyword
+ClassDef = ast.ClassDef
+walk = ast.walk
+fix_missing_locations = ast.fix_missing_locations
+unparse = ast.unparse
+Constant = ast.Constant
+AST = ast.AST
+stmt = ast.stmt
+expr = ast.expr
+Import = ast.Import
+ImportFrom = ast.ImportFrom
+alias = ast.alias
+
+# `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[str, object] = dict()
+DEFAULT_AST_ARGS_ADD: dict[str, object] = dict()
+DEFAULT_AST_ARGS_ARGUMENTS: dict[str, object] = dict()
+
+
+def subscript_slice_object[T](value: T) -> T:
+    return value