cleanup readme

Cleanup docs and logging

Author: markhalka

README.md

@@ -1,6 +1,6 @@
 # numba cfunc compiler
 
-Generic, framework-agnostic infrastructure for compiling Python functions to Numba @cfunc via AST transformation
+Extensible compiler for producing native C-callable functions from Python source with stateful variables, typed containers, and pluggable type systems built on Numba @cfunc
 
 [![Build Status](https://github.com/Point72/numba-cfunc-compiler/actions/workflows/build.yaml/badge.svg?branch=main&event=push)](https://github.com/Point72/numba-cfunc-compiler/actions/workflows/build.yaml)
 [![codecov](https://codecov.io/gh/Point72/numba-cfunc-compiler/branch/main/graph/badge.svg)](https://codecov.io/gh/Point72/numba-cfunc-compiler)
@@ -9,15 +9,14 @@ Generic, framework-agnostic infrastructure for compiling Python functions to Num
 
 ## Overview
 
-Generic, framework-agnostic infrastructure for compiling Python functions to Numba `@cfunc` via AST transformation. All domain-specific behavior is injected through registration APIs.
+A compilation framework that transforms Python functions into native C-callable functions using Numba `@cfunc` and AST rewriting. Unlike using `@cfunc` directly, it provides:
 
-The distribution is published as `numba-cfunc-compiler` and imported in Python as `numba_cfunc_compiler`.
-
-This package is intended for applications that need to:
+- **Stateful variables** — declare persistent state with natural syntax that survives across calls with automatic lifecycle management (start/execute/stop)
+- **Standalone typed containers** — lists and dicts that work inside compiled functions without Numba's runtime overhead
+- **Extensible type resolution** — register custom types that map Python syntax to numba-compatible lowering 
+- **Plugin architecture** — all domain-specific behavior (input handlers, output handlers, AST transforms, type inference) is injected through registration APIs
 
-- transform Python functions into fixed-signature Numba entry points
-- inject domain-specific typing, AST lowering, and runtime behavior through registrations
-- ship a small native runtime alongside the Python package
+The distribution is published as `numba-cfunc-compiler` and imported in Python as `numba_cfunc_compiler`.
 
 ## Installation
 
@@ -301,8 +300,8 @@ Registered by `defaults.register_all()`:
 - **Primitives** — `int` (int64), `float` (float64), `bool` (int8). Support `State[int]`, etc.
 - **DateTime** — Stored as nanoseconds (int64). Constructor calls like `datetime(2020,1,1,tzinfo=timezone.utc)` are lowered to constants at compile time. Must be timezone-aware.
 - **TimeDelta** — Stored as nanoseconds (int64). `timedelta(seconds=5)` lowered to constants.
-- **NumbaList** — NRT-free typed list (`int`/`float`/`bool` elements). Supports `len`, indexing, `append`, `pop`, `clear`, iteration. Created with `create_new_list(int)`.
-- **NumbaDict** — NRT-free typed dict (`int` keys, `int`/`float`/`bool` values). Supports `len`, `[]`, `in`/`not in`, `get`, `pop`, `clear`, `items()`, `keys()`. Created with `create_new_dict(int, float)`.
+- **NumbaList** — Standalone typed list (`int`/`float`/`bool` elements). Supports `len`, indexing, `append`, `pop`, `clear`, iteration. Created with `create_new_list(int)`.
+- **NumbaDict** — Standalone typed dict (`int` keys, `int`/`float`/`bool` values). Supports `len`, `[]`, `in`/`not in`, `get`, `pop`, `clear`, `items()`, `keys()`. Created with `create_new_dict(int, float)`.
 - **Structs** — Opaque void pointers with field metadata. Read/write fields via pointer arithmetic. Base `StructType` must be subclassed with `is_type_supported()`, `_get_struct_fields()`, `_get_struct_size()`.
 
 ## Compilation Options & Post-Compilation Transforms
@@ -323,7 +322,7 @@ result = create_compiled_func(func, *args, options=opts, ...)
 
 **`fastmath`** *(compilation)* — Passes `fastmath=True` to the Numba `@cfunc` decorator, enabling aggressive floating-point optimizations (reassociation, no-NaN, etc.).
 
-**`force_inline`** *(post-compilation)* — Replaces Numba's `noinline` attribute on the cfunc wrapper → native call with `alwaysinline`, letting the LLVM optimizer merge them. Safe with `error_model='numpy'` and `_nrt=False`.
+**`force_inline`** *(post-compilation)* — Replaces Numba's `noinline` attribute on the cfunc wrapper with `alwaysinline`, letting the LLVM optimizer inline the function body into the wrapper and eliminate the extra call.
 
 Regardless of options, the exported wrapper symbol is renamed to `_gc_numba_<semantic_key>`. `result.native_name`, `result.semantic_key`, and `result.llvm_ir` all reflect that final compiled form.
 
@@ -405,6 +404,6 @@ def compiled_func(outputs, output_ticked, state, lifecycle_phase, ...):
         ...
 ```
 
-### NRT-free Containers
+### Standalone Containers
 
 `NumbaList` and `NumbaDict` use standalone C implementations (`numba_rt/_py_nrt_init.so`) instead of Numba's reference-counted runtime. Memory is owned by the host framework via state slots. The C library is loaded lazily on first compilation via `CompilationContext.ensure_nrt_loaded()`.

numba_cfunc_compiler/defaults/struct_support.py

@@ -241,7 +241,7 @@ def register():
 
     Note: Base StructType returns False for is_type_supported(), so it won't
     match any types by default. Client code should register their own StructType
-    subclasses (e.g., CspStructType) for struct support.
+    subclasses for struct support.
     """
     from numba_cfunc_compiler.numba_type_inference import NumbaTypeInference
 

numba_cfunc_compiler/numba_core.py

@@ -2,7 +2,6 @@
 import hashlib
 import inspect
 import json
-import logging
 from dataclasses import dataclass
 from typing import Any, Callable, List, Optional
 
@@ -78,9 +77,6 @@ def __getattr__(self, name: str) -> Any:
         raise AttributeError(f"'{type(self).__name__}' has no attribute '{name}'")
 
 
-logger = logging.getLogger("graph_compute")
-
-
 def _build_semantic_key(
     new_func_code: str,
     cfunc_sig: str,
@@ -231,7 +227,6 @@ def create_compiled_func(
     )
     new_tree = transformer.visit(tree)
     new_func_code = ast.unparse(new_tree)
-    logger.debug(f"generated code for {name}:\n{new_func_code}")
 
     cfunc_sig = SourceRegistry.build_cfunc_signature()
     cfunc_kwargs = "nopython=True, nogil=True, _nrt=False, error_model='numpy'"

numba_cfunc_compiler/post_compilation.py

@@ -9,7 +9,7 @@
     "link_ffi_bitcode",
 ]
 
-logger = logging.getLogger("graph_compute")
+log = logging.getLogger("numba_cfunc_compiler")
 
 
 @dataclass(frozen=True)
@@ -108,6 +108,6 @@ def link_ffi_bitcode(module: Any, bitcode: bytes) -> Any:
         module.verify()
 
     except Exception as e:
-        logger.warning(f"Failed to link FFI bitcode for inlining (falling back to external calls): {e}")
+        log.warning(f"Failed to link FFI bitcode for inlining (falling back to external calls): {e}")
 
     return module

numba_cfunc_compiler/utils/ast.py

@@ -17,14 +17,14 @@
     "AST",
 ]
 
-logger = logging.getLogger("graph_compute")
+log = logging.getLogger("numba_cfunc_compiler")
 
 
 def print_ast(value) -> None:
     ast.fix_missing_locations(value)
     tree = ast.parse(value)
     src = ast.unparse(tree)
-    logger.info(src)
+    log.info(src)
 
 
 def add_statement_to_list(node_list: List[ast.stmt], node: Union[ast.stmt, List[ast.stmt], None]) -> None:

numba_cfunc_compiler/variable_factory.py

@@ -130,7 +130,7 @@ def read(self):
         # ContainerType handles its own read logic (e.g. list/dict from voidptr)
         if isinstance(self.type, ContainerType):
             return self.type.read(self.local_variable_name(), self.name, loaded_value)
-        # Allow types to prepare themselves before reading (e.g., OrderBookType loads from book_ptrs)
+        # Allow types to prepare themselves before reading
         self.type = self.type.prepare_voidptr_read(self)
         value = AST.cast_from_voidptr(loaded_value, self.type.get_numba_type_name())
         return AST.assignment(self.local_variable_name(), value)
@@ -158,7 +158,7 @@ def __init__(self, array_idx: int, type: VariableType, name: str):
     def local_variable_name(self):
         return f"output_{self.array_idx}_ptr"
 
-    def write(self, value: any):
+    def write(self, value: Any):
         """
         Create: output_(output_idx)_ptr[0] = value
         """
@@ -205,7 +205,7 @@ def get(self):
 class LocalConstantSource(VariableSource):
     """Local constants created inside the node (mainly used when returning a constant value)"""
 
-    def __init__(self, type: VariableType, name: str, var_value: any):
+    def __init__(self, type: VariableType, name: str, var_value: Any):
         super().__init__(type, name)
         self.var_value = var_value
 
@@ -321,7 +321,7 @@ def _visit_and_create_temp_var(self, visitor, ast_node, statements: List[ast.stm
         self.add_variable(var)
         return var
 
-    def _get_static_key(self, key_node) -> any:
+    def _get_static_key(self, key_node) -> Any:
         """Extract a static key value from an AST node, or return None if dynamic."""
         if isinstance(key_node, ast.Constant):
             return key_node.value