Add basic macro interfaces and path handling

configzen/config.py

@@ -3,10 +3,10 @@
 from __future__ import annotations
 
 from collections.abc import Callable, Iterable, Mapping
+from contextlib import suppress
 from contextvars import ContextVar
 from dataclasses import dataclass
-from functools import wraps
-from typing import TYPE_CHECKING, Any, ClassVar, cast
+from typing import TYPE_CHECKING, Any, ClassVar, NamedTuple, cast
 
 from anyio.to_thread import run_sync
 from pydantic import BaseModel, PrivateAttr
@@ -15,9 +15,9 @@
 from pydantic_settings import BaseSettings
 from pydantic_settings.main import SettingsConfigDict
 
-from configzen.context import copy_context_on_await, copy_context_on_call
+from configzen.context import isolated_context_coroutine, isolated_context_function
 from configzen.data import roundtrip_update_mapping
-from configzen.processor import ConfigProcessor
+from configzen.processor import ConfigProcessor, FileSystemAwareConfigProcessor
 from configzen.routes import (
  EMPTY_ROUTE,
  GetAttr,
@@ -51,10 +51,20 @@ class ModelConfig(SettingsConfigDict, total=False):
 
 
 pydantic_config_keys |= set(ModelConfig.__annotations__)
-loading: ContextVar[bool] = ContextVar("loading", default=False)
+processing: ContextVar[ProcessingContext | None] = ContextVar(
+ "processing",
+ default=None,
+)
 owner_lookup: ContextVar[BaseConfig] = ContextVar("owner")
 
 
+class ProcessingContext(NamedTuple):
+ model_class: type[BaseConfig]
+ processor: ConfigProcessor
+ # We keep it mainly to make path resolution smarter.
+ trace: list[ConfigSource]
+
+
 def _locate(
  owner: object,
  value: object,
@@ -150,7 +160,7 @@ def __init__(self, **data: Any) -> None:
  owner = owner_lookup.get()
  except LookupError:
  owner = None
- if loading.get():
+ if processing.get():
  owner_lookup.set(self)
  super().__init__(**data)
  self._config_root = owner
@@ -192,7 +202,7 @@ def config_processor(self) -> ConfigProcessor:
  """
  if self._config_root is None:
  if not hasattr(self, "_config_processor"):
- return ConfigProcessor(self.config_dump())
+ return FileSystemAwareConfigProcessor(self.config_dump())
  return self._config_processor
  return self._config_root.config_processor
 
@@ -251,11 +261,29 @@ def _validate_processor_factory(
  "Callable[..., ConfigProcessor] | None",
  cls.model_config.get("config_processor_factory"),
  )
- or ConfigProcessor
+ or FileSystemAwareConfigProcessor
  )
 
  @classmethod
- @copy_context_on_call
+ def _try_rebuild_model(cls) -> None:
+ # Possible scenarios:
+ # (sync) Frame 1: <class>.config_load()
+ # (sync) Frame 2: isolated_context_function.<locals>.copy()
+ # (sync) Frame 3: run_isolated()
+ # (sync) Frame 4: <class>.config_load()
+ # (sync) Frame 5: <class>.model_rebuild()
+ #
+ # (async) Frame 1: <class>.config_load_async()
+ # (async) Frame 2: isolated_context_function.<locals>.copy()
+ # (async) Frame 3: run_isolated()
+ # (async) Frame 4: <class>.config_load()
+ # (async) Frame 5: <class>.model_rebuild()
+ if cls.model_config["rebuild_on_load"]:
+ with suppress(Exception):
+ cls.model_rebuild(_parent_namespace_depth=5)
+
+ @classmethod
+ @isolated_context_function
  def config_load(
  cls,
  source: object | None = None,
@@ -276,7 +304,7 @@ def config_load(
  that case just create `BinaryFileConfigSource("plist_file.plist")`.
  context
  The context to use during model validation.
- See also https://docs.pydantic.dev/latest/api/base_model @ `model_validate`.
+ See also [`model_validate`][pydantic.BaseModel.model_validate].
  processor_factory
  The state factory to use to parse the newly loaded configuration data.
 
@@ -285,12 +313,7 @@ def config_load(
  self
 
  """
- if cls.model_config["rebuild_on_load"]:
- # Frame 1: copy_context_and_call.<locals>.copy()
- # Frame 2: copy_and_run()
- # Frame 3: <class>.config_load()
- # Frame 4: <class>.model_rebuild()
- cls.model_rebuild(_parent_namespace_depth=4)
+ cls._try_rebuild_model()
 
  # Validate the source we load our configuration from.
  config_source = cls._validate_config_source(source)
@@ -308,7 +331,7 @@ def config_load(
 
  # ruff: noqa: FBT003
  try:
- loading.set(True)
+ processing.set(ProcessingContext(cls, processor, trace=[config_source]))
 
  # Processing will execute any commands that are present
  # in the configuration data and return the final configuration
@@ -319,16 +342,15 @@ def config_load(
  # is saved (`processor.revert_processor_changes()`).
  self = cls(**processor.get_processed_data())
  finally:
- loading.set(False)
+ processing.set(None)
 
  # Quick setup and we're done.
  self._config_source = config_source
  self._config_processor = processor
  return self
 
  @classmethod
- @copy_context_on_await
- @wraps(config_load)
+ @isolated_context_coroutine
  async def config_load_async(
  cls,
  source: object | None = None,
@@ -355,28 +377,22 @@ async def config_load_async(
  self
 
  """
- # Intentionally not using `run_sync(config_load)` here.
- # We want to keep every user-end object handled by the same thread.
+ cls._try_rebuild_model()
 
- if cls.model_config["rebuild_on_load"]:
- # Frame 1: copy_context_on_await.<locals>.copy_async()
- # Frame 2: copy_and_await()
- # Frame 3: <class>.config_load_async()
- # Frame 4: <class>.model_rebuild()
- cls.model_rebuild(_parent_namespace_depth=4)
+ # Intentionally not using `run_sync(config_load)` here.
+ # We want to keep make the set up instructions blocking to avoid running
+ # into mutexes.
 
  config_source = cls._validate_config_source(source)
  make_processor = cls._validate_processor_factory(processor_factory)
  processor = make_processor(await config_source.load_async())
 
  try:
- loading.set(True)
+ processing.set(ProcessingContext(cls, processor, trace=[config_source]))
 
- # Since `processor.get_processed_data()` operates on primitive data types,
- # we can safely use run_sync here to run in a worker thread.
  self = cls(**await run_sync(processor.get_processed_data))
  finally:
- loading.set(False)
+ processing.set(None)
 
  self._config_processor = processor
  self._config_source = config_source
@@ -439,11 +455,6 @@ async def config_reload_async(self) -> Self:
 
  return self
 
- @wraps(config_reload_async)
- async def reload_async(self) -> Self:
- """Do the same as `config_reload_async`."""
- return await self.config_reload_async()
-
  def _config_data_save(
  self,
  destination: object | None = None,
@@ -464,7 +475,7 @@ def _config_data_save(
  new_data = self.config_dump()
  else:
  # Construct a new configuration instance.
- # Respect __class__ attribute since root might be a proxy (from proxyvars).
+ # Respect `__class__` attribute: root might be a proxy, e.g. from proxyvars.
  new_root = root.__class__(**processor.get_processed_data())
  routes = root.config_find_routes(self)
 
@@ -499,8 +510,8 @@ def config_save(self, destination: object | None = None) -> Self:
  that case just create `BinaryFileConfigSource("plist_file.plist")`.
 
  """
- config_source, data = self._config_data_save(destination)
- config_source.dump(data)
+ config_destination, data = self._config_data_save(destination)
+ config_destination.dump(data)
  return self
 
  async def config_save_async(self, destination: object | None = None) -> Self:
@@ -518,8 +529,8 @@ async def config_save_async(self, destination: object | None = None) -> Self:
  that case just create `BinaryFileConfigSource("plist_file.plist")`.
 
  """
- config_source, data = self._config_data_save(destination)
- await config_source.dump_async(data)
+ config_destination, data = self._config_data_save(destination)
+ await config_destination.dump_async(data)
  return self
 
  def config_at(self, *routes: RouteLike) -> Item:

configzen/context.py

@@ -18,14 +18,14 @@
 
 
 __all__ = (
- "copy_context_on_call",
- "copy_context_on_await",
- "copy_and_run",
- "copy_and_await",
+ "isolated_context_function",
+ "isolated_context_coroutine",
+ "run_isolated",
+ "async_run_isolated",
 )
 
 
-def copy_context_on_call(func: Callable[_P, _T]) -> Callable[_P, _T]:
+def isolated_context_function(func: Callable[_P, _T]) -> Callable[_P, _T]:
  """
  Copy the context automatically on function call.
 
@@ -34,16 +34,16 @@ def copy_context_on_call(func: Callable[_P, _T]) -> Callable[_P, _T]:
  Used as a decorator.
  """
  if isinstance(func, (classmethod, staticmethod)):
- return type(func)(copy_context_on_call(func.__func__))
+ return type(func)(isolated_context_function(func.__func__))
 
  @wraps(func)
  def copy(*args: _P.args, **kwargs: _P.kwargs) -> _T:
- return copy_and_run(func, *args, **kwargs)
+ return run_isolated(func, *args, **kwargs)
 
  return copy
 
 
-def copy_context_on_await(
+def isolated_context_coroutine(
  func: Callable[_P, Coroutine[object, object, _T]],
 ) -> Callable[_P, Coroutine[object, object, _T]]:
  """
@@ -54,22 +54,22 @@ def copy_context_on_await(
  Used as a decorator.
  """
  if isinstance(func, (classmethod, staticmethod)):
- return type(func)(copy_context_on_await(func.__func__))
+ return type(func)(isolated_context_coroutine(func.__func__))
 
  @wraps(func)
  async def copy_async(*args: _P.args, **kwargs: _P.kwargs) -> _T:
- return await copy_and_await(func, *args, **kwargs)
+ return await async_run_isolated(func, *args, **kwargs)
 
  return copy_async
 
 
-def copy_and_run(func: Callable[_P, _T], *args: _P.args, **kwargs: _P.kwargs) -> _T:
+def run_isolated(func: Callable[_P, _T], *args: _P.args, **kwargs: _P.kwargs) -> _T:
  """Run a function in an isolated context."""
  context = contextvars.copy_context()
  return context.run(func, *args, **kwargs)
 
 
-def copy_and_await(
+def async_run_isolated(
  func: Callable[_P, Coroutine[object, object, _T]],
  *args: _P.args,
  **kwargs: _P.kwargs,