fix(examples): make the examples follow the rules they teach, and lint it (#431)

Agents copy these scripts (bmesh-gear is the documented anatomy), but
nothing checked them against the repo's own rules, and they broke them:
53 per-face `use_smooth` loops (three in bmesh-gear), 74 per-vertex
`v.co.z += ...` loops, more per-element material/co writes, and seven
`active_object` reads with no None guard.

- 127 single-statement loops became foreach_set / foreach_get by a
  scripted AST rewrite (inline comments kept); seven more hand-converted
  (constant material indices, uniform co scale/offset, the moka-pot lean).
- Eight loops with genuinely per-element logic (ring/station material
  bands, n-gon marking, ball-surface tests) carry a
  `# foreach-exempt: <why>` marker.
- Seven `X = bpy.context.active_object` reads get `if X is None: raise`.
- tests/check_example_rules.py (Validate) rejects an unmarked
  per-element write in a loop over .polygons/.vertices (Mesh-only names,
  so bmesh code is never hit) and an unguarded active_object read.

Old and new versions of six scripts, run on 5.2.1 across ten paths
including the touched falsifiers, print identical output with identical
exit codes.

Closes #400

Signed-off-by: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: TMHSDigital

.github/workflows/validate.yml

@@ -79,6 +79,9 @@ jobs:
       - name: Showcase helper drift (warn-only report)
         run: python3 tests/check_helper_drift.py
 
+      - name: Examples and showcase follow the repo's own rules
+        run: python3 tests/check_example_rules.py
+
       - name: Check asset_sheet.py can render every showcase piece and reference
         run: python3 tests/check_asset_sheet_select.py
 

docs/new-example-prompt.md

@@ -136,6 +136,12 @@ intentional, important geometry is not clipped, highlights are not blown out,
 lights or helper objects are not visible unintentionally, and materials, lighting,
 background, and camera feel designed rather than left at Blender defaults.
 
+The example must follow the repo's own rules, not just teach them:
+`tests/check_example_rules.py` (run by Validate) rejects a per-element write
+in a loop over `mesh.polygons` / `mesh.vertices` (use `foreach_set`) and an
+`active_object` read with no `None` guard. A loop that really needs per-element
+logic carries `# foreach-exempt: <why>` on or just above its `for` line.
+
 Contact-sheet gate (required before shipping the still): build a composite placing
 the new hero beside the pinned calibration set—canonical membership is in
 `CLAUDE.md` § Quality Gates for Example Runs—and compare stage darkness, wedge

examples/armature-bend/armature_bend.py

@@ -120,8 +120,7 @@ def build_tube():
         bm.to_mesh(me)
     finally:
         bm.free()
-    for poly in me.polygons:
-        poly.use_smooth = True
+    me.polygons.foreach_set("use_smooth", [True] * len(me.polygons))
     # collars keep crisp machined steps; the rubber ribs stay smooth
     me.set_sharp_from_angle(angle=math.radians(50.0))
     obj = bpy.data.objects.new("Tube", me)

examples/bake-normal-high-to-low/bake_normal_high_to_low.py

@@ -140,8 +140,7 @@ def decimate_apply(obj, target_tris):
         object=obj, active_object=obj, selected_objects=[obj]
     ):
         bpy.ops.object.modifier_apply(modifier=mod.name)
-    for poly in obj.data.polygons:
-        poly.use_smooth = True
+    obj.data.polygons.foreach_set("use_smooth", [True] * len(obj.data.polygons))
     obj.data.update()
     return current, evaluated_triangle_count(obj)
 

examples/bmesh-gear/bmesh_gear.py

@@ -290,8 +290,7 @@ def companion_pitch_r(teeth):
 
 def render_still(obj, path, engine):
     scene = bpy.context.scene
-    for poly in obj.data.polygons:
-        poly.use_smooth = False  # crisp machined facets
+    obj.data.polygons.foreach_set("use_smooth", [False] * len(obj.data.polygons))  # crisp machined facets
     brass = machined_brass()
     obj.data.materials.append(brass)
     blued = principled("BluedSteel", (0.07, 0.11, 0.22), 0.26, metal=1.0, noise=3.0)
@@ -329,8 +328,7 @@ def partner(name, teeth, direction, mat, depth, bore=None):
         cy = HERO_C[1] + dist * math.sin(direction)
         me = ring_gear_mesh(name, teeth, pr - ADDENDUM, pr + ADDENDUM, depth, bore=bore)
         me.materials.append(mat)
-        for p in me.polygons:
-            p.use_smooth = False
+        me.polygons.foreach_set("use_smooth", [False] * len(me.polygons))
         ob = bpy.data.objects.new(name, me)
         scene.collection.objects.link(ob)
         # a gap centred on the line of centres, facing the checked gear's tooth
@@ -368,8 +366,7 @@ def web(bm):
     def add(name, build, mat, cx, cy, smooth=False, bevel=0.01):
         me = solid_mesh(name, build)
         me.materials.append(mat)
-        for p in me.polygons:
-            p.use_smooth = smooth
+        me.polygons.foreach_set("use_smooth", [smooth] * len(me.polygons))
         ob = bpy.data.objects.new(name, me)
         scene.collection.objects.link(ob)
         place(ob, cx, cy)

examples/boolean-exact-volume/boolean_exact_volume.py

@@ -288,8 +288,7 @@ def tube_mesh(name, segments, radius, sides=10):
         bm.to_mesh(me)
     finally:
         bm.free()
-    for p in me.polygons:
-        p.use_smooth = True
+    me.polygons.foreach_set("use_smooth", [True] * len(me.polygons))
     return me
 
 
@@ -357,8 +356,7 @@ def add(name, me, mat, mw=None):
         # the boolean output carries the operands' (empty) material slots;
         # start clean so every face takes the finish below
         shown.materials.clear()
-        for poly in shown.polygons:
-            poly.material_index = 0
+        shown.polygons.foreach_set("material_index", [0] * len(shown.polygons))
         ob = add(f"{op.title()}Shown", shown, finishes[op], res.matrix_world.copy())
         bev = ob.modifiers.new("MachinedChamfer", 'BEVEL')
         bev.width = 0.012

examples/car-mirror-symmetry/car_mirror_symmetry.py

@@ -396,6 +396,7 @@ def _assign_body_materials(body):
     are glass exactly where the cabin factor ramps (windshield, hatch)."""
     PAINT, GLASS, TRIM, CHROME = (MATERIALS.index(m)
                                   for m in ("Paint", "Glass", "Trim", "Chrome"))
+    # foreach-exempt: per-face material from the face's ring/station index
     for poly in body.data.polygons:
         i, k = divmod(poly.index, RING - 1)
         if i >= N_ST - 1:            # cap ngons (front/rear fascia)

examples/collision-hull-proxy/collision_hull_proxy.py

@@ -223,6 +223,7 @@ def build_hydrant():
     body = lathe_object("Body", BODY_PROFILE, SEGMENTS)
     body.data.materials.append(red)
     body.data.materials.append(yellow)
+    # foreach-exempt: conditional per-face material by face height
     for p in body.data.polygons:  # the bonnet dome is the yellow profile tail
         if p.center.z > 1.09:
             p.material_index = 1
@@ -384,8 +385,7 @@ def render_still(groups, pieces, path, engine):
     scene = bpy.context.scene
     for g in groups:
         for o in g["render"]:
-            for p in o.data.polygons:
-                p.use_smooth = True
+            o.data.polygons.foreach_set("use_smooth", [True] * len(o.data.polygons))
     for g in groups:  # cages exist only to build hulls; never rendered
         for o in g["cage"]:
             o.hide_render = True
@@ -415,8 +415,7 @@ def render_still(groups, pieces, path, engine):
 
     for name, hull, _ in pieces:
         hull.data.materials.append(shell)
-        for p in hull.data.polygons:
-            p.use_smooth = False                # facets must read as facets
+        hull.data.polygons.foreach_set("use_smooth", [False] * len(hull.data.polygons))  # facets must read as facets
         hull.data.materials.append(wire_mat)
         wire = bpy.data.objects.new(f"{name}Wire", hull.data)
         mod = wire.modifiers.new("Wire", 'WIREFRAME')
@@ -521,8 +520,9 @@ def main():
     for g in groups:
         hull = build_hull(f"{g['name']}Hull", collect_points(g["cage"]))
         if args.shrink_hull:
-            for v in hull.data.vertices:
-                v.co *= 0.5
+            co = [0.0] * (len(hull.data.vertices) * 3)
+            hull.data.vertices.foreach_get("co", co)
+            hull.data.vertices.foreach_set("co", [c * 0.5 for c in co])
             hull.data.update()
         pieces.append((g["name"], hull, collect_points(g["render"])))
     code = check(pieces)

examples/color-attribute-wheel/color_attribute_wheel.py

@@ -259,8 +259,7 @@ def _mat(name, base, rough, metal=0.0, noise=None, coat=0.0):
 def render_still(obj, path, engine):
     scene = bpy.context.scene
     me = obj.data
-    for poly in me.polygons:
-        poly.use_smooth = True
+    me.polygons.foreach_set("use_smooth", [True] * len(me.polygons))
 
     mat = build_material()
     if mat is None:

examples/compositor-glare/compositor_glare.py

@@ -127,10 +127,11 @@ def build_scene():
             major_segments=64, minor_segments=16,
             location=(x, y, RING_Z), rotation=(math.radians(90), 0.0, 0.0))
         ring = bpy.context.active_object
+        if ring is None:
+            raise RuntimeError("the add operator left no active object")
         ring.name = name
         ring.data.materials.append(make_emissive(f"Neon{name[4:]}", color, strength))
-        for poly in ring.data.polygons:
-            poly.use_smooth = True
+        ring.data.polygons.foreach_set("use_smooth", [True] * len(ring.data.polygons))
 
     world = bpy.data.worlds.new("World")
     world.use_nodes = True