Small performance improvements

 - Less dictionary lookups
 - Better logic in places like checking instance types
 - Overall review of code comments

Author: alganet

apywire/compiler.py

@@ -8,6 +8,7 @@
 from __future__ import annotations
 
 import ast
+from operator import itemgetter
 from types import EllipsisType
 from typing import cast
 
@@ -25,7 +26,6 @@
     _WiredRef,
 )
 
-# Constant for property AST arguments (used in compile methods)
 _PROPERTY_ARGS = ast.arguments(
     posonlyargs=[],
     args=[ast.arg(arg="self")],
@@ -122,17 +122,13 @@ def _compile_property(
                 attr=class_name,
                 ctx=ast.Load(),
             )
-        kwargs: list[ast.keyword] = []
-        # When compiling async accessors we must precompute awaited
-        # referenced attributes into locals so that the constructor
-        # lambda passed to a thread pool executor is pure synchronous.
         pre_statements: list[ast.stmt] = []
 
-        # Counter for generating unique variable names (mutable list)
-        counter = [0]
+        counter = [0]  # For generating unique variable names
 
         args: list[ast.expr] = []
 
+        kwargs: list[ast.keyword] = []
         # Normalize data into args_data (list) and kwargs_data (dict)
         args_data: list[_ResolvedValue] = []
         kwargs_data: dict[str, _ResolvedValue] = {}
@@ -141,12 +137,16 @@ def _compile_property(
             args_data = data
         else:
             data_dict = data
-            int_keys = sorted(k for k in data_dict if isinstance(k, int))
-            str_keys = [k for k in data_dict if isinstance(k, str)]
-            for k_int in int_keys:
-                args_data.append(data_dict[k_int])
-            for k_str in str_keys:
-                kwargs_data[k_str] = data_dict[k_str]
+            # Iterate once over data.items() to separate args and kwargs
+            args_items = []
+            kwargs_data = {}
+            for k, v in data_dict.items():
+                if isinstance(k, int):
+                    args_items.append((k, v))
+                elif isinstance(k, str):
+                    kwargs_data[k] = v
+            args_items.sort(key=itemgetter(0))
+            args_data = [v for _, v in args_items]
 
         # Process positional args
         for i, value in enumerate(args_data):
@@ -189,12 +189,8 @@ def _compile_property(
                 kw_val = raw_val_ast
             kwargs.append(ast.keyword(arg=key, value=kw_val))
 
-        # Build the actual constructor call (module.Class(*args, **kwargs))
         call = ast.Call(func=module_attr, args=args, keywords=kwargs)
 
-        # Cache attribute name like `_name` used to store instantiated
-        # objects on `self` at runtime. The compiled accessor returns
-        # `self._name` when present.
         cache_attr = f"{CACHE_ATTR_PREFIX}{name}"
 
         # if not hasattr(self, '_name'): ...

apywire/constants.py

@@ -8,38 +8,19 @@
 to improve maintainability and reduce duplication.
 """
 
-# Spec parsing constants
-SPEC_KEY_DELIMITER = " "
-"""Delimiter used to separate module.Class from name in spec keys."""
+SPEC_KEY_DELIMITER = " "  # Separates module.Class from name in spec keys
 
-# Placeholder constants
-PLACEHOLDER_START = "{"
-"""Start marker for placeholder references in spec values."""
+PLACEHOLDER_START = "{"  # Start marker for placeholder references
+PLACEHOLDER_END = "}"  # End marker for placeholder references
 
-PLACEHOLDER_END = "}"
-"""End marker for placeholder references in spec values."""
-
-# Placeholder regex pattern (compiled for efficiency)
+# Regex pattern for placeholders like {name}: captures name, no nested braces
 PLACEHOLDER_PATTERN = r"\{([^{}]+)\}"
-"""Regex pattern for matching placeholders like {name}.
-
-Matches placeholder syntax with the following rules:
-- Starts with { and ends with }
-- Captures the placeholder name (group 1)
-- Does not allow nested braces in the name
-- Example: "{host}" matches with name="host"
-"""
-
-SYNTHETIC_CONST = "__sconst__"
-"""Synthetic module name used to represent promoted constants."""
 
-# Cache attribute constants
-CACHE_ATTR_PREFIX = "_"
-"""Prefix for cache attributes on compiled/runtime instances."""
+SYNTHETIC_CONST = "__sconst__"  # Synthetic module for promoted constants
 
-# Compiled code generation constants
-COMPILED_VAR_PREFIX = "__val_"
-"""Prefix for temporary variables in compiled code."""
+CACHE_ATTR_PREFIX = "_"  # Prefix for cache attributes (_name)
 
-COMPILED_ARG_PREFIX = "__arg_"
-"""Prefix for argument variables in compiled code."""
+COMPILED_VAR_PREFIX = "__val_"  # Prefix for temp variables in compiled code
+COMPILED_ARG_PREFIX = (
+    "__arg_"  # Prefix for argument variables in compiled code
+)

apywire/runtime.py

@@ -10,6 +10,7 @@
 import asyncio
 import importlib
 import re
+from operator import itemgetter
 from typing import Awaitable, Callable, Protocol, cast, final
 
 from apywire.constants import SYNTHETIC_CONST
@@ -154,20 +155,17 @@ def _separate_args_kwargs(
         Returns:
             Tuple of (positional_args, keyword_args)
         """
-        args_list: list[tuple[int, object]] = []
-        kwargs_dict: dict[str, object] = {}
-
+        # Iterate once over data.items() to separate args and kwargs
+        args_list = []
+        kwargs_dict = {}
         for k, v in data.items():
             if isinstance(k, int):
                 args_list.append((k, v))
             else:
                 kwargs_dict[k] = v
 
-        # Sort positional args by index
-        def _sort_key(item: tuple[int, object]) -> int:
-            return item[0]
-
-        args_list.sort(key=_sort_key)
+        # Sort positional args by index and extract values
+        args_list.sort(key=itemgetter(0))
         pos_args = [v for _, v in args_list]
 
         return (pos_args, kwargs_dict)
@@ -244,8 +242,6 @@ def _instantiate_impl(self, name: str) -> _RuntimeValue:
                     # All positional arguments
                     instance = constructor(*kwargs)
                 else:
-                    # Should not happen given _ResolvedSpecMapping type,
-                    # but for safety
                     instance = constructor(kwargs)
             except Exception as e:
                 raise WiringError(
@@ -267,9 +263,7 @@ def _resolve_runtime(
         their accessors.
         """
         if isinstance(o, _WiredRef):
-            # Detect when a placeholder reference points to something that
-            # wasn't defined in the spec. This is an unknown placeholder
-            # and should raise a friendly error.
+            # Ensure placeholder was defined in spec
             if o.name not in self._values and o.name not in self._parsed:
                 ctx = f" while instantiating '{context}'" if context else ""
                 raise UnknownPlaceholderError(
@@ -280,11 +274,11 @@ def _resolve_runtime(
             # Call the accessor `self.name()` to get the runtime value.
             return cast(object, getattr(self, o.name)())
 
-        if isinstance(o, dict):
+        elif isinstance(o, dict):
             return {k: self._resolve_runtime(v, context) for k, v in o.items()}
-        if isinstance(o, list):
+        elif isinstance(o, list):
             return [self._resolve_runtime(v, context) for v in o]
-        if isinstance(o, tuple):
+        elif isinstance(o, tuple):
             return tuple(self._resolve_runtime(v, context) for v in o)
         return o
 
@@ -348,11 +342,12 @@ def __init__(self, wiring: WiringRuntime, name: str) -> None:
 
     def __call__(self) -> object:
         """Return the wired object, instantiating it if necessary."""
-        # Fast path: check if already instantiated and cached in _values
-        # or as an attribute on the instance.
-        # We check _values first as it is the canonical storage.
-        if self._name in self._wiring._values:
+        # Fast path: EAFP pattern for cache lookup
+        # Try to get cached value directly (faster than check + get)
+        try:
             return self._wiring._values[self._name]
+        except KeyError:
+            pass
 
         # Not cached, so we need to instantiate it.
         # We use _instantiate_attr which handles thread safety if enabled.
@@ -381,9 +376,11 @@ def __getattr__(self, name: str) -> Callable[[], Awaitable[object]]:
             )
 
         async def _get() -> object:
-            # If already cached, return immediately
-            if name in self._wiring._values:
+            # EAFP: Try cached value first
+            try:
                 return self._wiring._values[name]
+            except KeyError:
+                pass
 
             # If not cached, run instantiation in executor to avoid blocking
             # the event loop.

apywire/threads.py

@@ -20,16 +20,12 @@
 
 
 class _ThreadLocalState(threading.local):
-    """Typed thread-local storage for wiring resolution state.
+    """Thread-local storage for wiring resolution state.
 
-    This class provides properly typed attributes to avoid mypy Any propagation
-    when accessing dynamically-set attributes on threading.local().
-
-    Attributes are lazily initialized per-thread:
-        resolving_stack: Stack of attribute names currently being resolved
-                        in this thread (for circular dependency detection).
-        mode: Current instantiation mode ('optimistic', 'global', or None).
-        held_locks: List of locks currently held by this thread.
+    Provides typed attributes initialized per-thread:
+    - resolving_stack: Stack for circular dependency detection
+    - mode: Current instantiation mode ('optimistic', 'global', or None)
+    - held_locks: Locks held by this thread
     """
 
     def __init__(self) -> None:
@@ -94,7 +90,6 @@ def _check_cache(self, name: str) -> tuple[bool, object | None]:
         """
         cache_attr = f"{CACHE_ATTR_PREFIX}{name}"
 
-        # Check _values dict first (runtime path)
         if hasattr(self, "_values"):
             values_dict = cast(dict[str, object], getattr(self, "_values"))
             if name in values_dict:
@@ -162,9 +157,7 @@ def _instantiate_attr(
                     found, value = self._check_cache(name)
                     if found:
                         return value
-                    # Enter optimistic mode and track held locks to allow
-                    # nested instantiation to detect per-attribute
-                    # conflicts.
+                    # Enter optimistic mode and track held locks
                     self._local.mode = "optimistic"
                     held = self._get_held_locks()
                     held.clear()

apywire/wiring.py

@@ -35,8 +35,6 @@
 )
 
 
-# Marker class for a placeholder reference. Declared before the
-# type aliases so `ResolvedValue` can reference it directly.
 class _WiredRef:
     """Marker for a value that references another wired attribute.
 
@@ -49,9 +47,7 @@ def __init__(self, name: str) -> None:
         self.name = name
 
 
-# Spec value types come from the user-provided `Spec` input. They are
-# primitives or nested containers and may include placeholder strings
-# like "{otherName}".
+# User-provided spec values: primitives, containers, or placeholders
 _SpecValue: TypeAlias = (
     _ConstantValue
     | str
@@ -60,9 +56,7 @@ def __init__(self, name: str) -> None:
     | dict[str | int, "_SpecValue"]
 )
 
-# Resolved values are produced after parsing placeholders; strings of
-# the form "{name}" become `_WiredRef` markers and are resolved at
-# instantiation.
+# After parsing: placeholder strings "{name}" become _WiredRef markers
 _ResolvedValue: TypeAlias = (
     _ConstantValue
     | _WiredRef
@@ -177,8 +171,8 @@ def __init__(
                 # Has placeholders - classify later
                 const_with_refs[key] = (value, placeholder_names)
 
-        # Separate constants with refs into const-only vs wired-object refs
-        # handling transitive promotion
+        # Promote constants to accessors if they reference wired objects:
+        # Transitive: mark direct refs, then propagate to dependents
         const_deps_graph: dict[str, set[str]] = {
             key: placeholder_names
             for key, (value, placeholder_names) in const_with_refs.items()
@@ -308,11 +302,11 @@ def _resolve(self, obj: _SpecValue) -> _ResolvedValue:
                 ref_name = self._extract_placeholder_name(obj)
                 return _WiredRef(ref_name)
             return obj
-        if isinstance(obj, dict):
+        elif isinstance(obj, dict):
             return {k: self._resolve(v) for k, v in obj.items()}
-        if isinstance(obj, list):
+        elif isinstance(obj, list):
             return [self._resolve(v) for v in obj]
-        if isinstance(obj, tuple):
+        elif isinstance(obj, tuple):
             return tuple(self._resolve(v) for v in obj)
         return obj
 
@@ -387,11 +381,12 @@ def _topological_sort(
             CircularWiringError: If circular dependencies detected
         """
         # Calculate in-degree (number of dependencies) for each node
-        # Only count dependencies that are also in the set being sorted
+        # Pre-convert to set for efficient intersection
+        all_nodes = set(dependencies.keys())
         in_degree: dict[str, int] = {}
         for node, deps in dependencies.items():
             # Filter to only dependencies within this set
-            internal_deps = deps & dependencies.keys()
+            internal_deps = deps & all_nodes
             in_degree[node] = len(internal_deps)
 
         # Start with nodes that have no dependencies (within this set)
@@ -459,13 +454,13 @@ def _resolve_constant(
 
             # Handle embedded placeholders via string interpolation
             return self._interpolate_placeholders(value, resolved, "constant")
-        if isinstance(value, dict):
+        elif isinstance(value, dict):
             return {
                 k: self._resolve_constant(v, resolved)
                 for k, v in value.items()
             }
-        if isinstance(value, list):
+        elif isinstance(value, list):
             return [self._resolve_constant(v, resolved) for v in value]
-        if isinstance(value, tuple):
+        elif isinstance(value, tuple):
             return tuple(self._resolve_constant(v, resolved) for v in value)
         return value