checkpointer 2.11.2__tar.gz → 2.12.0__tar.gz

checkpointer-2.12.0/ATTRIBUTION.md

@@ -0,0 +1,33 @@
+# Attribution and License Notices
+
+This project includes code copied or adapted from third-party open-source projects. The following acknowledges the original sources and complies with their licensing requirements.
+
+---
+
+## Third-Party Code
+
+### more-itertools
+- **Source:** https://github.com/more-itertools/more-itertools
+- **Author:** Erik Rose
+- **Copyright:** (c) 2012 Erik Rose
+- **License:** MIT (https://github.com/more-itertools/more-itertools/blob/master/LICENSE)
+
+### colored
+- **Source:** https://gitlab.com/dslackw/colored
+- **Author:** Dimitris Zlatanidis
+- **Copyright:** (c) 2014-2025 Dimitris Zlatanidis
+- **License:** MIT (https://gitlab.com/dslackw/colored/-/blob/master/LICENSE.txt)
+
+---
+
+## License
+
+This project is licensed under the MIT License. See the `LICENSE` file for details.
+
+---
+
+## Notes
+
+- Third-party code is included under their original MIT licenses.
+- This file documents those license notices, fulfilling attribution obligations.
+- Source files with copied code may omit individual license headers in favor of this centralized attribution.

{checkpointer-2.11.2 → checkpointer-2.12.0}/LICENSE

@@ -1,3 +1,5 @@
+MIT License
+
 Copyright 2018-2025 Hampus Hallman
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

{checkpointer-2.11.2 → checkpointer-2.12.0}/PKG-INFO

@@ -1,17 +1,13 @@
 Metadata-Version: 2.4
 Name: checkpointer
-Version: 2.11.2
+Version: 2.12.0
 Summary: checkpointer adds code-aware caching to Python functions, maintaining correctness and speeding up execution as your code changes.
 Project-URL: Repository, https://github.com/Reddan/checkpointer.git
 Author: Hampus Hallman
-License: Copyright 2018-2025 Hampus Hallman
-        
-        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
-        
-        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-        
-        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+License-Expression: MIT
+License-File: ATTRIBUTION.md
 License-File: LICENSE
+Keywords: async,cache,caching,code-aware,decorator,fast,hashing,invalidation,memoization,memoize,memory,optimization,performance,workflow
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13

{checkpointer-2.11.2 → checkpointer-2.12.0}/checkpointer/__init__.py

@@ -1,10 +1,10 @@
 import gc
 import tempfile
 from typing import Callable
-from .checkpoint import CachedFunction, Checkpointer, CheckpointError
+from .checkpoint import CachedFunction, Checkpointer, CheckpointError, FunctionIdent
 from .object_hash import ObjectHash
 from .storages import MemoryStorage, PickleStorage, Storage
-from .types import AwaitableValue, HashBy, NoHash
+from .types import AwaitableValue, Captured, CapturedOnce, CaptureMe, CaptureMeOnce, HashBy, NoHash
 
 checkpoint = Checkpointer()
 capture_checkpoint = Checkpointer(capture=True)

{checkpointer-2.11.2 → checkpointer-2.12.0}/checkpointer/checkpoint.py

@@ -2,29 +2,26 @@ from __future__ import annotations
 import re
 from datetime import datetime
 from functools import cached_property, update_wrapper
-from inspect import Parameter, Signature, iscoroutine, signature
+from inspect import Parameter, iscoroutine, signature, unwrap
+from itertools import chain
 from pathlib import Path
 from typing import (
-  Annotated, Callable, Concatenate, Coroutine, Generic,
-  Iterable, Literal, Self, Type, TypedDict,
-  Unpack, cast, get_args, get_origin, overload,
+  Callable, Concatenate, Coroutine, Generic, Iterable,
+  Literal, Self, Type, TypedDict, Unpack, cast, overload,
 )
-from .fn_ident import RawFunctionIdent, get_fn_ident
+from .fn_ident import Capturable, RawFunctionIdent, get_fn_ident
 from .object_hash import ObjectHash
 from .print_checkpoint import print_checkpoint
-from .storages import STORAGE_MAP, Storage
-from .types import AwaitableValue, C, Coro, Fn, HashBy, P, R
-from .utils import unwrap_fn
+from .storages import STORAGE_MAP, Storage, StorageType
+from .types import AwaitableValue, C, Coro, Fn, P, R, hash_by_from_annotation
 
 DEFAULT_DIR = Path.home() / ".cache/checkpoints"
 
-empty_set = cast(set, frozenset())
-
 class CheckpointError(Exception):
   pass
 
 class CheckpointerOpts(TypedDict, total=False):
-  format: Type[Storage] | Literal["pickle", "memory", "bcolz"]
+  format: Type[Storage] | StorageType
   root_path: Path | str | None
   when: bool
   verbosity: Literal[0, 1, 2]
@@ -63,28 +60,52 @@ class FunctionIdent:
     self.__dict__.clear()
     self.cached_fn = cached_fn
 
+  def reset(self):
+    self.__init__(self.cached_fn)
+
+  def is_static(self) -> bool:
+    return self.cached_fn.checkpointer.fn_hash_from is not None
+
   @cached_property
   def raw_ident(self) -> RawFunctionIdent:
-    return get_fn_ident(unwrap_fn(self.cached_fn.fn), self.cached_fn.checkpointer.capture)
+    return get_fn_ident(unwrap(self.cached_fn.fn), self.cached_fn.checkpointer.capture)
 
   @cached_property
   def fn_hash(self) -> str:
-    if (hash_from := self.cached_fn.checkpointer.fn_hash_from) is not None:
-      return str(ObjectHash(hash_from, digest_size=16))
-    deep_hashes = [depend.ident.raw_ident.fn_hash for depend in self.cached_fn.deep_depends()]
+    if self.is_static():
+      return str(ObjectHash(self.cached_fn.checkpointer.fn_hash_from, digest_size=16))
+    depends = self.deep_idents(past_static=False)
+    deep_hashes = [d.fn_hash if d.is_static() else d.raw_ident.fn_hash for d in depends]
     return str(ObjectHash(digest_size=16).write_text(iter=deep_hashes))
 
   @cached_property
-  def captured_hash(self) -> str:
-    deep_hashes = [depend.ident.raw_ident.captured_hash for depend in self.cached_fn.deep_depends()]
-    return str(ObjectHash().write_text(iter=deep_hashes))
+  def capturables(self) -> list[Capturable]:
+    return sorted({
+      capturable.key: capturable
+      for depend in self.deep_idents()
+      for capturable in depend.raw_ident.capturables
+    }.values())
+
+  def deep_depends(self, past_static=True, visited: set[Callable] = set()) -> Iterable[Callable]:
+    if self.cached_fn not in visited:
+      yield self.cached_fn
+      visited = visited or set()
+      visited.add(self.cached_fn)
+      stop = not past_static and self.is_static()
+      depends = [] if stop else self.raw_ident.depends
+      for depend in depends:
+        if isinstance(depend, CachedFunction):
+          yield from depend.ident.deep_depends(past_static, visited)
+        elif depend not in visited:
+          yield depend
+          visited.add(depend)
 
-  def reset(self):
-    self.__init__(self.cached_fn)
+  def deep_idents(self, past_static=True) -> Iterable[FunctionIdent]:
+    return (fn.ident for fn in self.deep_depends(past_static) if isinstance(fn, CachedFunction))
 
 class CachedFunction(Generic[Fn]):
   def __init__(self, checkpointer: Checkpointer, fn: Fn):
-    wrapped = unwrap_fn(fn)
+    wrapped = unwrap(fn)
     fn_file = Path(wrapped.__code__.co_filename).name
     fn_name = re.sub(r"[^\w.]", "", wrapped.__qualname__)
     Storage = STORAGE_MAP[checkpointer.format] if isinstance(checkpointer.format, str) else checkpointer.format
@@ -95,20 +116,14 @@ class CachedFunction(Generic[Fn]):
     self.storage = Storage(self)
     self.cleanup = self.storage.cleanup
     self.bound = ()
-    self.attrname: str | None = None
 
-    sig = signature(wrapped)
-    params = list(sig.parameters.items())
+    params = list(signature(wrapped).parameters.values())
     pos_params = (Parameter.POSITIONAL_ONLY, Parameter.POSITIONAL_OR_KEYWORD)
-    self.arg_names = [name for name, param in params if param.kind in pos_params]
-    self.default_args = {name: param.default for name, param in params if param.default is not Parameter.empty}
-    self.hash_by_map = get_hash_by_map(sig)
+    self.arg_names = [param.name for param in params if param.kind in pos_params]
+    self.default_args = {param.name: param.default for param in params if param.default is not Parameter.empty}
+    self.hash_by_map = get_hash_by_map(params)
     self.ident = FunctionIdent(self)
 
-  def __set_name__(self, _, name: str):
-    assert self.attrname is None
-    self.attrname = name
-
   @overload
   def __get__(self: Self, instance: None, owner: Type[C]) -> Self: ...
   @overload
@@ -116,12 +131,9 @@ class CachedFunction(Generic[Fn]):
   def __get__(self, instance, owner):
     if instance is None:
       return self
-    assert self.attrname is not None
     bound_fn = object.__new__(CachedFunction)
     bound_fn.__dict__ |= self.__dict__
     bound_fn.bound = (instance,)
-    if hasattr(instance, "__dict__"):
-      setattr(instance, self.attrname, bound_fn)
     return bound_fn
 
   @property
@@ -129,12 +141,12 @@ class CachedFunction(Generic[Fn]):
     return self.ident.raw_ident.depends
 
   def reinit(self, recursive=False) -> CachedFunction[Fn]:
-    depend_idents = [depend.ident for depend in self.deep_depends()] if recursive else [self.ident]
+    depend_idents = list(self.ident.deep_idents()) if recursive else [self.ident]
     for ident in depend_idents: ident.reset()
     for ident in depend_idents: ident.fn_hash
     return self
 
-  def get_call_hash(self, args: tuple, kw: dict[str, object]) -> str:
+  def _get_call_hash(self, args: tuple, kw: dict[str, object]) -> str:
     args = self.bound + args
     pos_args = args[len(self.arg_names):]
     named_pos_args = dict(zip(self.arg_names, args))
@@ -145,8 +157,17 @@ class CachedFunction(Generic[Fn]):
         if hash_by := hash_by_map.get(key, rest_hash_by):
           named_args[key] = hash_by(value)
       if pos_hash_by := hash_by_map.get(b"*"):
-        pos_args = tuple(map(pos_hash_by, pos_args))
-    return str(ObjectHash(named_args, pos_args, self.ident.captured_hash, digest_size=16))
+        pos_args = map(pos_hash_by, pos_args)
+    named_args_iter = chain.from_iterable(sorted(named_args.items()))
+    captured = chain.from_iterable(capturable.capture() for capturable in self.ident.capturables)
+    obj_hash = ObjectHash(digest_size=16) \
+      .update(iter=named_args_iter, header="NAMED") \
+      .update(iter=pos_args, header="POS") \
+      .update(iter=captured, header="CAPTURED")
+    return str(obj_hash)
+
+  def get_call_hash(self: CachedFunction[Callable[P, R]], *args: P.args, **kw: P.kwargs) -> str:
+    return self._get_call_hash(args, kw)
 
   async def _resolve_coroutine(self, call_hash: str, coroutine: Coroutine):
     return self.storage.store(call_hash, AwaitableValue(await coroutine)).value
@@ -157,7 +178,7 @@ class CachedFunction(Generic[Fn]):
     if not params.when:
       return self.fn(*full_args, **kw)
 
-    call_hash = self.get_call_hash(args, kw)
+    call_hash = self._get_call_hash(args, kw)
     call_id = f"{self.storage.fn_id()}/{call_hash}"
     refresh = rerun \
       or not self.storage.exists(call_hash) \
@@ -186,17 +207,17 @@ class CachedFunction(Generic[Fn]):
     return self._call(args, kw, True)
 
   def exists(self: CachedFunction[Callable[P, R]], *args: P.args, **kw: P.kwargs) -> bool:
-    return self.storage.exists(self.get_call_hash(args, kw))
+    return self.storage.exists(self._get_call_hash(args, kw))
 
   def delete(self: CachedFunction[Callable[P, R]], *args: P.args, **kw: P.kwargs):
-    self.storage.delete(self.get_call_hash(args, kw))
+    self.storage.delete(self._get_call_hash(args, kw))
 
   @overload
   def get(self: Callable[P, Coro[R]], *args: P.args, **kw: P.kwargs) -> R: ...
   @overload
   def get(self: Callable[P, R], *args: P.args, **kw: P.kwargs) -> R: ...
   def get(self, *args, **kw):
-    call_hash = self.get_call_hash(args, kw)
+    call_hash = self._get_call_hash(args, kw)
     try:
       data = self.storage.load(call_hash)
       return data.value if isinstance(data, AwaitableValue) else data
@@ -208,30 +229,15 @@ class CachedFunction(Generic[Fn]):
   @overload
   def set(self: Callable[P, R], value: R, *args: P.args, **kw: P.kwargs): ...
   def set(self, value, *args, **kw):
-    self.storage.store(self.get_call_hash(args, kw), value)
+    self.storage.store(self._get_call_hash(args, kw), value)
 
   def __repr__(self) -> str:
     return f"<CachedFunction {self.fn.__name__} {self.ident.fn_hash[:6]}>"
 
-  def deep_depends(self, visited: set[CachedFunction] = empty_set) -> Iterable[CachedFunction]:
-    if self not in visited:
-      yield self
-      visited = visited or set()
-      visited.add(self)
-      for depend in self.depends:
-        if isinstance(depend, CachedFunction):
-          yield from depend.deep_depends(visited)
-
-def hash_by_from_annotation(annotation: type) -> Callable[[object], object] | None:
-  if get_origin(annotation) is Annotated:
-    args = get_args(annotation)
-    metadata = args[1] if len(args) > 1 else None
-    if get_origin(metadata) is HashBy:
-      return get_args(metadata)[0]
-
-def get_hash_by_map(sig: Signature) -> dict[str | bytes, Callable[[object], object]]:
+def get_hash_by_map(params: list[Parameter]) -> dict[str | bytes, Callable[[object], object]]:
   hash_by_map = {}
-  for name, param in sig.parameters.items():
+  for param in params:
+    name = param.name
     if param.kind == Parameter.VAR_POSITIONAL:
       name = b"*"
     elif param.kind == Parameter.VAR_KEYWORD:

checkpointer-2.12.0/checkpointer/fn_ident.py

@@ -0,0 +1,159 @@
+import dis
+from inspect import Parameter, getmodule, signature, unwrap
+from types import CodeType, MethodType, ModuleType
+from typing import Annotated, Callable, Iterable, NamedTuple, Type, get_args, get_origin
+from .import_mappings import resolve_annotation
+from .object_hash import ObjectHash
+from .types import hash_by_from_annotation, is_capture_me, is_capture_me_once, to_none
+from .utils import (
+  AttrDict, cwd, distinct, get_cell_contents,
+  get_file, is_class, is_user_fn, seekable, takewhile,
+)
+
+AttrPath = tuple[str, ...]
+CapturableByFn = dict[Callable, list["Capturable"]]
+
+class RawFunctionIdent(NamedTuple):
+  fn_hash: str
+  depends: list[Callable]
+  capturables: set["Capturable"]
+
+class Capturable(NamedTuple):
+  key: str
+  module: ModuleType
+  attr_path: AttrPath
+  hash_by: Callable | None
+  hash: str | None = None
+
+  def capture(self) -> tuple[str, object]:
+    if obj := self.hash:
+      return self.key, obj
+    obj = AttrDict.get_at(self.module, *self.attr_path)
+    obj = self.hash_by(obj) if self.hash_by else obj
+    return self.key, obj
+
+  @staticmethod
+  def new(module: ModuleType, attr_path: AttrPath, hash_by: Callable | None, capture_once: bool) -> "Capturable":
+    file = str(get_file(module).relative_to(cwd))
+    key = "-".join((file, *attr_path))
+    cap = Capturable(key, module, attr_path, hash_by)
+    if not capture_once:
+      return cap
+    obj_hash = str(ObjectHash(cap.capture()[1]))
+    return Capturable(key, module, attr_path, None, obj_hash)
+
+def extract_classvars(code: CodeType, scope_vars: AttrDict) -> dict[str, dict[str, Type]]:
+  attr_path = AttrPath(())
+  scope_obj = None
+  classvars: dict[str, dict[str, Type]] = {}
+  instructs = seekable(dis.get_instructions(code))
+  for instr in instructs:
+    if instr.opname in scope_vars and not attr_path:
+      attrs = takewhile((x.opname == "LOAD_ATTR", x.argval) for x in instructs)
+      attr_path = AttrPath((instr.opname, instr.argval, *attrs))
+      instructs.step(-1)
+    elif instr.opname == "CALL":
+      obj = scope_vars.get_at(*attr_path)
+      attr_path = AttrPath(())
+      if is_class(obj):
+        scope_obj = obj
+    elif instr.opname in ("STORE_FAST", "STORE_DEREF") and scope_obj:
+      load_key = instr.opname.replace("STORE", "LOAD")
+      classvars.setdefault(load_key, {})[instr.argval] = scope_obj
+      scope_obj = None
+  return classvars
+
+def extract_scope_values(code: CodeType, scope_vars: AttrDict) -> Iterable[tuple[AttrPath, object]]:
+  classvars = extract_classvars(code, scope_vars)
+  scope_vars = scope_vars.set({k: scope_vars[k].set(v) for k, v in classvars.items()})
+  instructs = seekable(dis.get_instructions(code))
+  for instr in instructs:
+    if instr.opname in scope_vars:
+      attrs = takewhile((x.opname in ("LOAD_ATTR", "LOAD_METHOD"), x.argval) for x in instructs)
+      attr_path = AttrPath((instr.opname, instr.argval, *attrs))
+      parent_path = attr_path[:-1]
+      instructs.step(-1)
+      obj = scope_vars.get_at(*attr_path)
+      if obj is not None:
+        yield attr_path, obj
+      if callable(obj) and parent_path[1:]:
+        parent_obj = scope_vars.get_at(*parent_path)
+        yield parent_path, parent_obj
+  for const in code.co_consts:
+    if isinstance(const, CodeType):
+      next_deref = scope_vars.LOAD_DEREF.set(scope_vars.LOAD_FAST)
+      next_scope_vars = AttrDict({**scope_vars, "LOAD_FAST": {}, "LOAD_DEREF": next_deref})
+      yield from extract_scope_values(const, next_scope_vars)
+
+def resolve_class_annotations(anno: object) -> Type | None:
+  if anno in (None, Annotated):
+    return None
+  elif is_class(anno):
+    return anno
+  elif get_origin(anno) is Annotated:
+    return resolve_class_annotations(next(iter(get_args(anno)), None))
+  return resolve_class_annotations(get_origin(anno))
+
+def get_self_value(fn: Callable) -> type | object | None:
+  if isinstance(fn, MethodType):
+    return fn.__self__
+  parts = fn.__qualname__.split(".")[:-1]
+  cls = parts and AttrDict(fn.__globals__).get_at(*parts)
+  if is_class(cls):
+    return cls
+
+def get_capturables(fn: Callable, capture: bool, captured_vars: dict[AttrPath, object]) -> Iterable[Capturable]:
+  module = getmodule(fn)
+  if not module or not is_user_fn(fn):
+    return
+  for (instruct, *attr_path), obj in captured_vars.items():
+    attr_path = AttrPath(attr_path)
+    if instruct == "LOAD_GLOBAL" and not callable(obj) and not isinstance(obj, ModuleType):
+      anno = resolve_annotation(module, ".".join(attr_path))
+      if capture or is_capture_me(anno) or is_capture_me_once(anno):
+        hash_by = hash_by_from_annotation(anno)
+        if hash_by is not to_none:
+          yield Capturable.new(module, attr_path, hash_by, is_capture_me_once(anno))
+
+def get_fn_captures(fn: Callable, capture: bool) -> tuple[list[Callable], list[Capturable]]:
+  sig_scope = {
+    param.name: class_anno
+    for param in signature(fn).parameters.values()
+    if param.annotation is not Parameter.empty
+    if param.kind not in (Parameter.VAR_POSITIONAL, Parameter.VAR_KEYWORD)
+    if (class_anno := resolve_class_annotations(param.annotation))
+  }
+  self_value = get_self_value(fn)
+  scope_vars = AttrDict({
+    "LOAD_FAST": AttrDict({**sig_scope, "self": self_value} if self_value else sig_scope),
+    "LOAD_DEREF": AttrDict(get_cell_contents(fn)),
+    "LOAD_GLOBAL": AttrDict(fn.__globals__),
+  })
+  captured_vars = dict(extract_scope_values(fn.__code__, scope_vars))
+  captured_callables = [obj for obj in captured_vars.values() if callable(obj)]
+  capturables = list(get_capturables(fn, capture, captured_vars))
+  return captured_callables, capturables
+
+def get_depend_fns(fn: Callable, capture: bool, capturable_by_fn: CapturableByFn = {}) -> CapturableByFn:
+  from .checkpoint import CachedFunction
+  captured_callables, capturables = get_fn_captures(fn, capture)
+  capturable_by_fn = capturable_by_fn or {}
+  capturable_by_fn[fn] = capturables
+  for depend_fn in captured_callables:
+    depend_fn = unwrap(depend_fn, stop=lambda f: isinstance(f, CachedFunction))
+    if isinstance(depend_fn, CachedFunction):
+      capturable_by_fn[depend_fn] = []
+    elif depend_fn not in capturable_by_fn and is_user_fn(depend_fn):
+      get_depend_fns(depend_fn, capture, capturable_by_fn)
+  return capturable_by_fn
+
+def get_fn_ident(fn: Callable, capture: bool) -> RawFunctionIdent:
+  from .checkpoint import CachedFunction
+  capturable_by_fn = get_depend_fns(fn, capture)
+  capturables = {capt for capts in capturable_by_fn.values() for capt in capts}
+  depends = capturable_by_fn.keys()
+  depends = distinct(fn.__func__ if isinstance(fn, MethodType) else fn for fn in depends)
+  unwrapped_depends = [fn for fn in depends if not isinstance(fn, CachedFunction)]
+  assert fn == unwrapped_depends[0]
+  fn_hash = str(ObjectHash(iter=unwrapped_depends))
+  return RawFunctionIdent(fn_hash, depends, capturables)

checkpointer-2.12.0/checkpointer/import_mappings.py

@@ -0,0 +1,47 @@
+import ast
+import inspect
+import sys
+from types import ModuleType
+from typing import Iterable, Type
+from .utils import cwd, get_file, is_user_file
+
+ImportTarget = tuple[str, str | None]
+
+cache: dict[tuple[str, int], dict[str, ImportTarget]] = {}
+
+def generate_import_mappings(module: ModuleType) -> Iterable[tuple[str, ImportTarget]]:
+  mod_path = get_file(module)
+  if not is_user_file(mod_path):
+    return
+  mod_parts = list(mod_path.with_suffix("").relative_to(cwd).parts)
+  source = inspect.getsource(module)
+  tree = ast.parse(source)
+  for node in ast.walk(tree):
+    if isinstance(node, ast.Import):
+      for alias in node.names:
+        yield (alias.asname or alias.name, (alias.name, None))
+    elif isinstance(node, ast.ImportFrom):
+      target_mod = node.module or ""
+      if node.level > 0:
+        target_mod_parts = target_mod.split(".") * bool(target_mod)
+        target_mod_parts = mod_parts[:-node.level] + target_mod_parts
+        target_mod = ".".join(target_mod_parts)
+      for alias in node.names:
+        yield (alias.asname or alias.name, (target_mod, alias.name))
+
+def get_import_mappings(module: ModuleType) -> dict[str, ImportTarget]:
+  cache_key = (module.__name__, id(module))
+  if cached := cache.get(cache_key):
+    return cached
+  import_mappings = dict(generate_import_mappings(module))
+  return cache.setdefault(cache_key, import_mappings)
+
+def resolve_annotation(module: ModuleType, attr_name: str | None) -> Type | None:
+  if not attr_name:
+    return None
+  if anno := module.__annotations__.get(attr_name):
+    return anno
+  if next_pair := get_import_mappings(module).get(attr_name):
+    next_module_name, next_attr_name = next_pair
+    if next_module := sys.modules.get(next_module_name):
+      return resolve_annotation(next_module, next_attr_name)

{checkpointer-2.11.2 → checkpointer-2.12.0}/checkpointer/object_hash.py

@@ -12,7 +12,7 @@ from io import StringIO
 from itertools import chain
 from pickle import HIGHEST_PROTOCOL as PICKLE_PROTOCOL
 from types import BuiltinFunctionType, FunctionType, GeneratorType, MethodType, ModuleType, UnionType
-from typing import Callable, TypeVar
+from typing import Callable, Self, TypeVar
 from .utils import ContextVar
 
 np, torch = None, None
@@ -43,14 +43,14 @@ class ObjectHashError(Exception):
     self.obj = obj
 
 class ObjectHash:
-  def __init__(self, *objs: object, iter: Iterable[object] = (), digest_size=64, tolerate_errors=False) -> None:
+  def __init__(self, *objs: object, iter: Iterable[object] = (), digest_size=64, tolerable=False) -> None:
     self.hash = hashlib.blake2b(digest_size=digest_size)
     self.current: dict[int, int] = {}
-    self.tolerate_errors = ContextVar(tolerate_errors)
+    self.tolerable = ContextVar(tolerable)
     self.update(iter=chain(objs, iter))
 
   def copy(self) -> "ObjectHash":
-    new = ObjectHash(tolerate_errors=self.tolerate_errors.value)
+    new = ObjectHash(tolerable=self.tolerable.value)
     new.hash = self.hash.copy()
     return new
 
@@ -63,26 +63,29 @@ class ObjectHash:
     return isinstance(value, ObjectHash) and str(self) == str(value)
 
   def nested_hash(self, *objs: object) -> str:
-    return ObjectHash(iter=objs, tolerate_errors=self.tolerate_errors.value).hexdigest()
+    return ObjectHash(iter=objs, tolerable=self.tolerable.value).hexdigest()
 
-  def write_bytes(self, *data: bytes, iter: Iterable[bytes] = ()) -> "ObjectHash":
+  def write_bytes(self, *data: bytes, iter: Iterable[bytes] = ()) -> Self:
     for d in chain(data, iter):
       self.hash.update(d)
     return self
 
-  def write_text(self, *data: str, iter: Iterable[str] = ()) -> "ObjectHash":
+  def write_text(self, *data: str, iter: Iterable[str] = ()) -> Self:
     return self.write_bytes(iter=(d.encode() for d in chain(data, iter)))
 
-  def header(self, *args: object) -> "ObjectHash":
+  def header(self, *args: object) -> Self:
     return self.write_bytes(":".join(map(str, args)).encode())
 
-  def update(self, *objs: object, iter: Iterable[object] = (), tolerate_errors: bool | None=None) -> "ObjectHash":
-    with nullcontext() if tolerate_errors is None else self.tolerate_errors.set(tolerate_errors):
+  def update(self, *objs: object, iter: Iterable[object] = (), tolerable: bool | None=None, header: str | None = None) -> Self:
+    with nullcontext() if tolerable is None else self.tolerable.set(tolerable):
       for obj in chain(objs, iter):
+        if header is not None:
+          self.write_bytes(header.encode())
+          header = None
         try:
           self._update_one(obj)
         except Exception as ex:
-          if self.tolerate_errors.value:
+          if self.tolerable.value:
             self.header("error").update(type(ex))
           else:
             raise ObjectHashError(obj, ex) from ex
@@ -180,10 +183,10 @@ class ObjectHash:
         finally:
           del self.current[id(obj)]
 
-  def _update_iterator(self, obj: Iterable) -> "ObjectHash":
+  def _update_iterator(self, obj: Iterable) -> Self:
     return self.header("iterator", encode_type_of(obj)).update(iter=obj).header("iterator-end")
 
-  def _update_object(self, obj: object) -> "ObjectHash":
+  def _update_object(self, obj: object) -> Self:
     self.header("instance", encode_type_of(obj))
     get_hash = hasattr(obj, "__objecthash__") and getattr(obj, "__objecthash__")
     if callable(get_hash):

{checkpointer-2.11.2 → checkpointer-2.12.0}/checkpointer/storages/__init__.py

@@ -1,9 +1,11 @@
-from typing import Type
-from .storage import Storage
-from .pickle_storage import PickleStorage
+from typing import Literal, Type
 from .memory_storage import MemoryStorage
+from .pickle_storage import PickleStorage
+from .storage import Storage
+
+StorageType = Literal["pickle", "memory"]
 
-STORAGE_MAP: dict[str, Type[Storage]] = {
+STORAGE_MAP: dict[StorageType, Type[Storage]] = {
   "pickle": PickleStorage,
   "memory": MemoryStorage,
 }

checkpointer-2.12.0/checkpointer/types.py

@@ -0,0 +1,49 @@
+from typing import (
+  Annotated, Callable, Coroutine, Generic,
+  ParamSpec, TypeVar, get_args, get_origin,
+)
+
+Fn = TypeVar("Fn", bound=Callable)
+P = ParamSpec("P")
+R = TypeVar("R")
+C = TypeVar("C")
+T = TypeVar("T")
+
+class HashBy(Generic[Fn]):
+  pass
+
+class Captured:
+  pass
+
+class CapturedOnce:
+  pass
+
+def to_none(_):
+  return None
+
+def get_annotated_args(anno: object) -> tuple[object, ...]:
+  return get_args(anno) if get_origin(anno) is Annotated else ()
+
+def hash_by_from_annotation(anno: object) -> Callable[[object], object] | None:
+  for arg in get_annotated_args(anno):
+    if get_origin(arg) is HashBy:
+      return get_args(arg)[0]
+
+def is_capture_me(anno: object) -> bool:
+  return Captured in get_annotated_args(anno)
+
+def is_capture_me_once(anno: object) -> bool:
+  return CapturedOnce in get_annotated_args(anno)
+
+NoHash = Annotated[T, HashBy[to_none]]
+CaptureMe = Annotated[T, Captured]
+CaptureMeOnce = Annotated[T, CapturedOnce]
+Coro = Coroutine[object, object, R]
+
+class AwaitableValue(Generic[T]):
+  def __init__(self, value: T):
+    self.value = value
+
+  def __await__(self):
+    yield
+    return self.value

checkpointer-2.12.0/checkpointer/utils.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+import inspect
+from contextlib import contextmanager
+from itertools import islice
+from pathlib import Path
+from types import FunctionType, MethodType, ModuleType
+from typing import Callable, Generic, Iterable, Self, Type, TypeGuard
+from .types import T
+
+cwd = Path.cwd().resolve()
+
+def is_class(obj) -> TypeGuard[Type]:
+  return isinstance(obj, type)
+
+def get_file(obj: Callable | ModuleType) -> Path:
+  return Path(inspect.getfile(obj)).resolve()
+
+def is_user_file(path: Path) -> bool:
+  return cwd in path.parents and ".venv" not in path.parts
+
+def is_user_fn(obj) -> TypeGuard[Callable]:
+  return isinstance(obj, (FunctionType, MethodType)) and is_user_file(get_file(obj))
+
+def get_cell_contents(fn: Callable) -> Iterable[tuple[str, object]]:
+  for key, cell in zip(fn.__code__.co_freevars, fn.__closure__ or []):
+    try:
+      yield (key, cell.cell_contents)
+    except ValueError:
+      pass
+
+def distinct(seq: Iterable[T]) -> list[T]:
+  return list(dict.fromkeys(seq))
+
+def takewhile(iter: Iterable[tuple[bool, T]]) -> Iterable[T]:
+  for condition, value in iter:
+    if not condition:
+      return
+    yield value
+
+class seekable(Generic[T]):
+  def __init__(self, iterable: Iterable[T]):
+    self.index = 0
+    self.source = iter(iterable)
+    self.sink: list[T] = []
+
+  def __iter__(self):
+    return self
+
+  def __next__(self) -> T:
+    if len(self.sink) > self.index:
+      item = self.sink[self.index]
+    else:
+      item = next(self.source)
+      self.sink.append(item)
+    self.index += 1
+    return item
+
+  def __bool__(self):
+    return bool(self.lookahead(1))
+
+  def seek(self, index: int) -> Self:
+    remainder = index - len(self.sink)
+    if remainder > 0:
+      next(islice(self, remainder, remainder), None)
+    self.index = max(0, min(index, len(self.sink)))
+    return self
+
+  def step(self, count: int) -> Self:
+    return self.seek(self.index + count)
+
+  @contextmanager
+  def freeze(self):
+    initial_index = self.index
+    try:
+      yield
+    finally:
+      self.seek(initial_index)
+
+  def lookahead(self, count: int) -> list[T]:
+    with self.freeze():
+      return list(islice(self, count))
+
+class AttrDict(dict):
+  def __init__(self, *args, **kwargs):
+    super().__init__(*args, **kwargs)
+    self.__dict__ = self
+
+  def __getattribute__(self, name: str):
+    return super().__getattribute__(name)
+
+  def __setattr__(self, name: str, value: object):
+    super().__setattr__(name, value)
+
+  def set(self, d: dict) -> AttrDict:
+    if not d:
+      return self
+    return AttrDict({**self, **d})
+
+  def get_at(self: object, *attrs: str) -> object:
+    obj = self
+    for attr in attrs:
+      obj = getattr(obj, attr, None)
+    return obj
+
+class ContextVar(Generic[T]):
+  def __init__(self, value: T):
+    self.value = value
+
+  @contextmanager
+  def set(self, value: T):
+    self.value, old = value, self.value
+    try:
+      yield
+    finally:
+      self.value = old

{checkpointer-2.11.2 → checkpointer-2.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "checkpointer"
-version = "2.11.2"
+version = "2.12.0"
 requires-python = ">=3.11"
 dependencies = []
 authors = [
@@ -8,12 +8,29 @@ authors = [
 ]
 description = "checkpointer adds code-aware caching to Python functions, maintaining correctness and speeding up execution as your code changes."
 readme = "README.md"
-license = {file = "LICENSE"}
+license = "MIT"
+license-files = ["LICENSE", "ATTRIBUTION.md"]
 classifiers = [
   "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
 ]
+keywords = [
+  "cache",
+  "caching",
+  "memoize",
+  "memoization",
+  "performance",
+  "fast",
+  "memory",
+  "invalidation",
+  "code-aware",
+  "optimization",
+  "hashing",
+  "async",
+  "workflow",
+  "decorator",
+]
 
 [project.urls]
 Repository = "https://github.com/Reddan/checkpointer.git"
@@ -30,7 +47,7 @@ dev = [
 ]
 
 [tool.poe.tasks]
-tests = "pytest checkpointer/test_checkpointer.py"
+tests = "pytest checkpointer/**/test_*.py"
 tests-debug = "poe tests -s"
 
 [build-system]
@@ -40,5 +57,8 @@ build-backend = "hatchling.build"
 [tool.hatch.build.targets.wheel]
 packages = ["checkpointer", "checkpointer.storages"]
 
+[tool.hatch.build]
+exclude = ["test_*.py"]
+
 [tool.pytest.ini_options]
 asyncio_default_fixture_loop_scope = "session"

{checkpointer-2.11.2 → checkpointer-2.12.0}/uv.lock

@@ -8,7 +8,7 @@ resolution-markers = [
 
 [[package]]
 name = "checkpointer"
-version = "2.11.2"
+version = "2.12.0"
 source = { editable = "." }
 
 [package.dev-dependencies]

checkpointer-2.11.2/checkpointer/fn_ident.py

@@ -1,103 +0,0 @@
-import dis
-import inspect
-from itertools import takewhile
-from pathlib import Path
-from types import CodeType, FunctionType, MethodType
-from typing import Callable, Iterable, NamedTuple, Type, TypeGuard
-from .object_hash import ObjectHash
-from .utils import AttrDict, distinct, get_cell_contents, iterate_and_upcoming, unwrap_fn
-
-cwd = Path.cwd().resolve()
-
-class RawFunctionIdent(NamedTuple):
-  fn_hash: str
-  captured_hash: str
-  depends: list[Callable]
-
-def is_class(obj) -> TypeGuard[Type]:
-  # isinstance works too, but needlessly triggers _lazyinit()
-  return issubclass(type(obj), type)
-
-def extract_classvars(code: CodeType, scope_vars: AttrDict) -> dict[str, dict[str, Type]]:
-  attr_path: tuple[str, ...] = ()
-  scope_obj = None
-  classvars: dict[str, dict[str, Type]] = {}
-  for instr, upcoming_instrs in iterate_and_upcoming(dis.get_instructions(code)):
-    if instr.opname in scope_vars and not attr_path:
-      attrs = takewhile(lambda instr: instr.opname == "LOAD_ATTR", upcoming_instrs)
-      attr_path = (instr.opname, instr.argval, *(str(x.argval) for x in attrs))
-    elif instr.opname == "CALL":
-      obj = scope_vars.get_at(attr_path)
-      attr_path = ()
-      if is_class(obj):
-        scope_obj = obj
-    elif instr.opname in ("STORE_FAST", "STORE_DEREF") and scope_obj:
-      load_key = instr.opname.replace("STORE", "LOAD")
-      classvars.setdefault(load_key, {})[instr.argval] = scope_obj
-      scope_obj = None
-  return classvars
-
-def extract_scope_values(code: CodeType, scope_vars: AttrDict) -> Iterable[tuple[tuple[str, ...], object]]:
-  classvars = extract_classvars(code, scope_vars)
-  scope_vars = scope_vars.set({k: scope_vars[k].set(v) for k, v in classvars.items()})
-  for instr, upcoming_instrs in iterate_and_upcoming(dis.get_instructions(code)):
-    if instr.opname in scope_vars:
-      attrs = takewhile(lambda instr: instr.opname == "LOAD_ATTR", upcoming_instrs)
-      attr_path: tuple[str, ...] = (instr.opname, instr.argval, *(str(x.argval) for x in attrs))
-      val = scope_vars.get_at(attr_path)
-      if val is not None:
-        yield attr_path, val
-  for const in code.co_consts:
-    if isinstance(const, CodeType):
-      yield from extract_scope_values(const, scope_vars)
-
-def get_self_value(fn: Callable) -> type | object | None:
-  if isinstance(fn, MethodType):
-    return fn.__self__
-  parts = tuple(fn.__qualname__.split(".")[:-1])
-  cls = parts and AttrDict(fn.__globals__).get_at(parts)
-  if is_class(cls):
-    return cls
-
-def get_fn_captured_vals(fn: Callable) -> list[object]:
-  self_value = get_self_value(fn)
-  scope_vars = AttrDict({
-    "LOAD_FAST": AttrDict({"self": self_value} if self_value else {}),
-    "LOAD_DEREF": AttrDict(get_cell_contents(fn)),
-    "LOAD_GLOBAL": AttrDict(fn.__globals__),
-  })
-  vals = dict(extract_scope_values(fn.__code__, scope_vars))
-  return list(vals.values())
-
-def is_user_fn(candidate_fn) -> TypeGuard[Callable]:
-  if not isinstance(candidate_fn, (FunctionType, MethodType)):
-    return False
-  fn_path = Path(inspect.getfile(candidate_fn)).resolve()
-  return cwd in fn_path.parents and ".venv" not in fn_path.parts
-
-def get_depend_fns(fn: Callable, captured_vals_by_fn: dict[Callable, list[object]] = {}) -> dict[Callable, list[object]]:
-  from .checkpoint import CachedFunction
-  captured_vals = get_fn_captured_vals(fn)
-  captured_vals_by_fn = captured_vals_by_fn or {}
-  captured_vals_by_fn[fn] = [val for val in captured_vals if not callable(val)]
-  for val in captured_vals:
-    if not callable(val):
-      continue
-    child_fn = unwrap_fn(val, cached_fn=True)
-    if isinstance(child_fn, CachedFunction):
-      captured_vals_by_fn[child_fn] = []
-    elif child_fn not in captured_vals_by_fn and is_user_fn(child_fn):
-      get_depend_fns(child_fn, captured_vals_by_fn)
-  return captured_vals_by_fn
-
-def get_fn_ident(fn: Callable, capture: bool) -> RawFunctionIdent:
-  from .checkpoint import CachedFunction
-  captured_vals_by_fn = get_depend_fns(fn)
-  depend_captured_vals = list(captured_vals_by_fn.values()) * capture
-  depends = captured_vals_by_fn.keys()
-  depends = distinct(fn.__func__ if isinstance(fn, MethodType) else fn for fn in depends)
-  unwrapped_depends = [fn for fn in depends if not isinstance(fn, CachedFunction)]
-  assert fn == unwrapped_depends[0]
-  fn_hash = str(ObjectHash(iter=unwrapped_depends))
-  captured_hash = str(ObjectHash(iter=depend_captured_vals, tolerate_errors=True))
-  return RawFunctionIdent(fn_hash, captured_hash, depends)

checkpointer-2.11.2/checkpointer/test_checkpointer.py

@@ -1,168 +0,0 @@
-import asyncio
-import pytest
-from checkpointer import CheckpointError, checkpoint
-from .utils import AttrDict
-
-def global_multiply(a: int, b: int) -> int:
-  return a * b
-
-@pytest.fixture(autouse=True)
-def run_before_and_after_tests(tmpdir):
-  global checkpoint
-  checkpoint = checkpoint(root_path=tmpdir)
-  yield
-
-def test_basic_caching():
-  @checkpoint
-  def square(x: int) -> int:
-    return x ** 2
-
-  result1 = square(4)
-  result2 = square(4)
-
-  assert result1 == result2 == 16
-
-def test_cache_invalidation():
-  @checkpoint
-  def multiply(a: int, b: int):
-    return a * b
-
-  @checkpoint
-  def helper(x: int):
-    return multiply(x + 1, 2)
-
-  @checkpoint
-  def compute(a: int, b: int):
-    return helper(a) + helper(b)
-
-  result1 = compute(3, 4)
-  assert result1 == 18
-
-def test_layered_caching():
-  dev_checkpoint = checkpoint(when=True)
-
-  @checkpoint(format="memory")
-  @dev_checkpoint
-  def expensive_function(x: int):
-    return x ** 2
-
-  assert expensive_function(4) == 16
-  assert expensive_function(4) == 16
-
-def test_recursive_caching1():
-  @checkpoint
-  def fib(n: int) -> int:
-    return fib(n - 1) + fib(n - 2) if n > 1 else n
-
-  assert fib(10) == 55
-  assert fib.get(10) == 55
-  assert fib.get(5) == 5
-
-def test_recursive_caching2():
-  @checkpoint
-  def fib(n: int) -> int:
-    return fib.fn(n - 1) + fib.fn(n - 2) if n > 1 else n
-
-  assert fib(10) == 55
-  assert fib.get(10) == 55
-  with pytest.raises(CheckpointError):
-    fib.get(5)
-
-@pytest.mark.asyncio
-async def test_async_caching():
-  @checkpoint(format="memory")
-  async def async_square(x: int) -> int:
-    await asyncio.sleep(0.1)
-    return x ** 2
-
-  result1 = await async_square(3)
-  result2 = await async_square(3)
-  result3 = async_square.get(3)
-
-  assert result1 == result2 == result3 == 9
-
-def test_force_recalculation():
-  @checkpoint
-  def square(x: int) -> int:
-    return x ** 2
-
-  assert square(5) == 25
-  square.rerun(5)
-  assert square.get(5) == 25
-
-def test_multi_layer_decorator():
-  @checkpoint(format="memory")
-  @checkpoint(format="pickle")
-  def add(a: int, b: int) -> int:
-    return a + b
-
-  assert add(2, 3) == 5
-  assert add.get(2, 3) == 5
-
-def test_capture():
-  item_dict = AttrDict({"a": 1, "b": 1})
-
-  @checkpoint(capture=True)
-  def test_whole():
-    return item_dict
-
-  @checkpoint(capture=True)
-  def test_a():
-    return item_dict.a + 1
-
-  init_hash_a = test_a.ident.captured_hash
-  init_hash_whole = test_whole.ident.captured_hash
-  item_dict.b += 1
-  test_whole.reinit()
-  test_a.reinit()
-  assert test_whole.ident.captured_hash != init_hash_whole
-  assert test_a.ident.captured_hash == init_hash_a
-  item_dict.a += 1
-  test_a.reinit()
-  assert test_a.ident.captured_hash != init_hash_a
-
-def test_depends():
-  def multiply_wrapper(a: int, b: int) -> int:
-    return global_multiply(a, b)
-
-  def helper(a: int, b: int) -> int:
-    return multiply_wrapper(a + 1, b + 1)
-
-  @checkpoint
-  def test_a(a: int, b: int) -> int:
-    return helper(a, b)
-
-  @checkpoint
-  def test_b(a: int, b: int) -> int:
-    return test_a(a, b) + multiply_wrapper(a, b)
-
-  assert set(test_a.depends) == {test_a.fn, helper, multiply_wrapper, global_multiply}
-  assert set(test_b.depends) == {test_b.fn, test_a, multiply_wrapper, global_multiply}
-
-def test_lazy_init_1():
-  @checkpoint
-  def fn1(x: object) -> object:
-    return fn2(x)
-
-  @checkpoint
-  def fn2(x: object) -> object:
-    return fn1(x)
-
-  assert set(fn1.depends) == {fn1.fn, fn2}
-  assert set(fn2.depends) == {fn1, fn2.fn}
-
-def test_lazy_init_2():
-  @checkpoint
-  def fn1(x: object) -> object:
-    return fn2(x)
-
-  assert set(fn1.depends) == {fn1.fn}
-
-  @checkpoint
-  def fn2(x: object) -> object:
-    return fn1(x)
-
-  assert set(fn1.depends) == {fn1.fn}
-  fn1.reinit()
-  assert set(fn1.depends) == {fn1.fn, fn2}
-  assert set(fn2.depends) == {fn1, fn2.fn}

checkpointer-2.11.2/checkpointer/types.py

@@ -1,21 +0,0 @@
-from typing import Annotated, Callable, Coroutine, Generic, ParamSpec, TypeVar
-
-Fn = TypeVar("Fn", bound=Callable)
-P = ParamSpec("P")
-R = TypeVar("R")
-C = TypeVar("C")
-T = TypeVar("T")
-
-class HashBy(Generic[Fn]):
-  pass
-
-NoHash = Annotated[T, HashBy[lambda _: None]]
-Coro = Coroutine[object, object, R]
-
-class AwaitableValue(Generic[T]):
-  def __init__(self, value: T):
-    self.value = value
-
-  def __await__(self):
-    yield
-    return self.value

checkpointer-2.11.2/checkpointer/utils.py

@@ -1,83 +0,0 @@
-from contextlib import contextmanager
-from typing import Callable, Generic, Iterable, cast
-from .types import Fn, T
-
-def distinct(seq: Iterable[T]) -> list[T]:
-  return list(dict.fromkeys(seq))
-
-def get_cell_contents(fn: Callable) -> Iterable[tuple[str, object]]:
-  for key, cell in zip(fn.__code__.co_freevars, fn.__closure__ or []):
-    try:
-      yield (key, cell.cell_contents)
-    except ValueError:
-      pass
-
-def unwrap_fn(fn: Fn, cached_fn=False) -> Fn:
-  from .checkpoint import CachedFunction
-  while True:
-    if (cached_fn and isinstance(fn, CachedFunction)) or not hasattr(fn, "__wrapped__"):
-      return cast(Fn, fn)
-    fn = getattr(fn, "__wrapped__")
-
-class AttrDict(dict):
-  def __init__(self, *args, **kwargs):
-    super().__init__(*args, **kwargs)
-    self.__dict__ = self
-
-  def __getattribute__(self, name: str):
-    return super().__getattribute__(name)
-
-  def __setattr__(self, name: str, value: object):
-    super().__setattr__(name, value)
-
-  def set(self, d: dict) -> "AttrDict":
-    if not d:
-      return self
-    return AttrDict({**self, **d})
-
-  def delete(self, *attrs: str) -> "AttrDict":
-    d = AttrDict(self)
-    for attr in attrs:
-      del d[attr]
-    return d
-
-  def get_at(self, attrs: tuple[str, ...]) -> object:
-    d = self
-    for attr in attrs:
-      d = getattr(d, attr, None)
-    return d
-
-class ContextVar(Generic[T]):
-  def __init__(self, value: T):
-    self.value = value
-
-  @contextmanager
-  def set(self, value: T):
-    self.value, old = value, self.value
-    try:
-      yield
-    finally:
-      self.value = old
-
-class iterate_and_upcoming(Generic[T]):
-  def __init__(self, it: Iterable[T]) -> None:
-    self.it = iter(it)
-    self.previous: tuple[()] | tuple[T] = ()
-    self.tracked = self._tracked_iter()
-
-  def __iter__(self):
-    return self
-
-  def __next__(self) -> tuple[T, Iterable[T]]:
-    try:
-      item = self.previous[0] if self.previous else next(self.it)
-      self.previous = ()
-      return item, self.tracked
-    except StopIteration:
-      self.tracked.close()
-      raise
-
-  def _tracked_iter(self):
-    for x in self.it:
-      self.previous = (x,)
-      yield x