ISSUE-011: Add development examples and README

- Add example scripts: basic_args.py, exceptions.py, classes_methods.py,
  recursion.py, generators_async.py, context_and_closures.py,
  threading.py, imports_side_effects.py, kwargs_nested.py.
- Add examples/README.md with brief descriptions and CLI usage:
  `python -m codetracer_python_recorder --codetracer-format=json examples/<script>.py`.
- Update issues.md to mark ISSUE-011 as Done with summary of changes.

Author: tzanko-matev

examples/README.md

@@ -0,0 +1,20 @@
+Examples for exercising the Rust‑backed recorder during development.
+
+Run any script via the module CLI so tracing is consistently enabled:
+
+  python -m codetracer_python_recorder --codetracer-format=json examples/<script>.py
+
+Scripts
+
+- basic_args.py: Demonstrates positional‑only, pos‑or‑kw, kw‑only, *args, **kwargs.
+- exceptions.py: Raises, catches, and prints an exception in except.
+- classes_methods.py: Instance, @classmethod, @staticmethod, and a property.
+- recursion.py: Direct recursion (factorial) and mutual recursion.
+- generators_async.py: A generator, async function, and async generator.
+- context_and_closures.py: A context manager and a nested closure.
+- threading.py: Two threads invoking traced functions and joining.
+- imports_side_effects.py: Module‑level side effects vs main guard.
+- kwargs_nested.py: Nested kwargs structure to validate structured encoding.
+
+All scripts are deterministic and print minimal output.
+

examples/basic_args.py

@@ -0,0 +1,19 @@
+"""Example: function with all Python argument kinds.
+
+Covers positional-only, positional-or-keyword, keyword-only, *args, **kwargs.
+"""
+
+def f(p, /, q, *args, r, **kwargs):  # noqa: D401 - simple demo
+    """Return a tuple to keep behavior deterministic."""
+    return (p, q, args, r, kwargs)
+
+
+def main() -> None:
+    res = f(1, 2, 3, 4, 5, r=6, a=7, b=8)
+    # Minimal stable output
+    print("ok", res[0], res[1], len(res[2]), res[3], sorted(res[4].items()))
+
+
+if __name__ == "__main__":
+    main()
+

examples/classes_methods.py

@@ -0,0 +1,34 @@
+"""Example: classes, instance/class/static methods, and a property."""
+
+
+class Counter:
+    def __init__(self, start: int = 0) -> None:
+        self._n = start
+
+    def inc(self, by: int = 1) -> int:
+        self._n += by
+        return self._n
+
+    @property
+    def double(self) -> int:
+        return self._n * 2
+
+    @classmethod
+    def start_at(cls, n: int) -> "Counter":
+        return cls(n)
+
+    @staticmethod
+    def add(a: int, b: int) -> int:
+        return a + b
+
+
+def main() -> None:
+    c = Counter.start_at(2)
+    x = c.inc()
+    y = Counter.add(3, 4)
+    print("ok", x, y, c.double)
+
+
+if __name__ == "__main__":
+    main()
+

examples/context_and_closures.py

@@ -0,0 +1,27 @@
+"""Example: context manager and nested closures."""
+
+from contextlib import contextmanager
+
+
+@contextmanager
+def tag(name: str):
+    # Minimal context; no side effects beyond yielding
+    yield f"<{name}>"
+
+
+def make_multiplier(factor: int):
+    def mul(x: int) -> int:
+        return x * factor
+
+    return mul
+
+
+def main() -> None:
+    with tag("x") as t:
+        mul3 = make_multiplier(3)
+        print("ok", t, mul3(5))
+
+
+if __name__ == "__main__":
+    main()
+

examples/exceptions.py

@@ -0,0 +1,21 @@
+"""Example: raising and handling an exception.
+
+Print the exception inside the except block to exercise printing under tracing.
+"""
+
+
+def boom() -> None:
+    raise ValueError("boom!")
+
+
+def main() -> None:
+    try:
+        boom()
+    except Exception as e:  # noqa: BLE001 - intentional for example
+        # Printing inside except triggers additional Python activity
+        print("handled", type(e).__name__)
+
+
+if __name__ == "__main__":
+    main()
+

examples/generators_async.py

@@ -0,0 +1,38 @@
+"""Example: generator, async function, and async generator."""
+
+from __future__ import annotations
+
+import asyncio
+
+
+def gen(n: int):
+    for i in range(n):
+        yield i * i
+
+
+async def async_add(a: int, b: int) -> int:
+    return a + b
+
+
+async def agen(n: int):
+    for i in range(n):
+        yield i + 1
+
+
+def main() -> None:
+    s = sum(gen(5))
+    total = asyncio.run(async_add(3, 4))
+
+    async def consume() -> int:
+        acc = 0
+        async for x in agen(3):
+            acc += x
+        return acc
+
+    acc = asyncio.run(consume())
+    print("ok", s, total, acc)
+
+
+if __name__ == "__main__":
+    main()
+

examples/imports_side_effects.py

@@ -0,0 +1,15 @@
+"""Example: module-level side effects vs main guard.
+
+When imported, this module sets a constant; when run as __main__, it prints.
+"""
+
+SIDE_EFFECT = "loaded"  # module-level assignment (side effect)
+
+
+def main() -> None:
+    print("ok", SIDE_EFFECT)
+
+
+if __name__ == "__main__":
+    main()
+

examples/kwargs_nested.py

@@ -0,0 +1,17 @@
+"""Example: nested kwargs structure for structured encoding validation."""
+
+
+def accept(**kwargs):  # noqa: D401 - simple demo
+    """Return kwargs verbatim to keep behavior observable and stable."""
+    return kwargs
+
+
+def main() -> None:
+    res = accept(a=1, b={"x": [1, 2], "y": {"z": 3}}, c=(4, 5))
+    # Print a stable projection of nested structure
+    print("ok", res["a"], sorted(res["b"].keys()), res["c"][0])
+
+
+if __name__ == "__main__":
+    main()
+

examples/recursion.py

@@ -0,0 +1,22 @@
+"""Example: direct and mutual recursion."""
+
+
+def factorial(n: int) -> int:
+    return 1 if n <= 1 else n * factorial(n - 1)
+
+
+def is_even(n: int) -> bool:
+    return n == 0 or is_odd(n - 1)
+
+
+def is_odd(n: int) -> bool:
+    return n != 0 and is_even(n - 1)
+
+
+def main() -> None:
+    print("ok", factorial(5), is_even(4), is_odd(7))
+
+
+if __name__ == "__main__":
+    main()
+

examples/threading.py

@@ -0,0 +1,23 @@
+"""Example: simple multithreading with join."""
+
+from __future__ import annotations
+
+import threading
+
+
+def worker(name: str, out: list[str]) -> None:
+    out.append(name)
+
+
+def main() -> None:
+    out: list[str] = []
+    t1 = threading.Thread(target=worker, args=("t1", out))
+    t2 = threading.Thread(target=worker, args=("t2", out))
+    t1.start(); t2.start()
+    t1.join(); t2.join()
+    print("ok", sorted(out))
+
+
+if __name__ == "__main__":
+    main()
+