confluid 0.1.0__py3-none-any.whl

confluid/__init__.py

@@ -0,0 +1,152 @@
+"""
+Confluid: Modern, hierarchical configuration and dependency injection.
+
+The pydantic-powered schema-export API (``to_pydantic``, ``confluid_class_of``)
+is exposed lazily via :pep:`562` ``__getattr__`` so importing confluid never
+requires pydantic — it is the optional ``confluid[pydantic]`` extra. Accessing
+those names without pydantic installed raises an ``ImportError`` naming the
+extra.
+
+``__all__`` is the CURATED public surface (pruned 2026-07): internal
+machinery (validation plumbing, scope resolution, annotation predicates,
+marker internals) stays importable from its home module but is deliberately
+not re-exported here.
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from confluid.configurator import configure, configure_from_file
+from confluid.decorators import configurable, ignore_config, output, register
+from confluid.dumper import dump
+from confluid.engine import active_context, cast, collect_report, flow, get_configurable_attrs, materialize, resolve
+from confluid.exceptions import (
+    CircularIncludeError,
+    ConfigFileNotFoundError,
+    ConfigurableDefinitionError,
+    ConfigurationError,
+    ConfluidError,
+    ConstructionError,
+    IntrospectionError,
+    ReferenceResolutionError,
+    ScopeError,
+    UnknownClassError,
+    ValidationModeError,
+    WorkspaceEnvError,
+)
+from confluid.fluid import Class, Clone, Fluid, Instance
+from confluid.fluid import Lazy as LazyClass
+from confluid.fluid import Reference, format_yaml_loc
+from confluid.lazy import Lazy, lazy_param_names
+from confluid.llm_schema import sanitize_schema
+from confluid.loader import get_app_name, load, load_config, load_config_with_paths, resolve_config_path, set_app_name
+from confluid.mandatory import Mandatory, mandatory_param_names
+from confluid.merger import deep_merge, expand_dotted_keys
+from confluid.no_broadcast import NoBroadcast, no_broadcast_param_names
+from confluid.registry import get_registry
+from confluid.report import ConfigurationReport
+from confluid.resolver import parse_value
+from confluid.schema import (
+    InputSpec,
+    OutputSpec,
+    get_hierarchy,
+    get_hierarchy_from_instance,
+    input_specs,
+    output_specs,
+    parse_param_docs,
+    shortest_unique_paths,
+)
+from confluid.scopes import discover_dimensions
+from confluid.validation import ValidationMode, ValidationPolicy, get_policy, reset_policy, set_policy, validate_model
+
+__all__ = [
+    "ConfluidError",
+    "ConfigurationError",
+    "CircularIncludeError",
+    "ReferenceResolutionError",
+    "UnknownClassError",
+    "ConfigurableDefinitionError",
+    "ValidationModeError",
+    "ScopeError",
+    "ConfigFileNotFoundError",
+    "ConstructionError",
+    "WorkspaceEnvError",
+    "IntrospectionError",
+    "configurable",
+    "register",
+    "ignore_config",
+    "output",
+    "get_registry",
+    "load",
+    "load_config",
+    "load_config_with_paths",
+    "resolve_config_path",
+    "set_app_name",
+    "get_app_name",
+    "materialize",
+    "resolve",
+    "active_context",
+    "deep_merge",
+    "expand_dotted_keys",
+    "parse_value",
+    "dump",
+    "configure",
+    "configure_from_file",
+    "ConfigurationReport",
+    "collect_report",
+    "Fluid",
+    "Class",
+    "Clone",
+    "Instance",
+    "Reference",
+    "flow",
+    "cast",
+    "format_yaml_loc",
+    "Lazy",
+    "LazyClass",
+    "lazy_param_names",
+    "Mandatory",
+    "mandatory_param_names",
+    "NoBroadcast",
+    "no_broadcast_param_names",
+    "get_hierarchy",
+    "get_hierarchy_from_instance",
+    "input_specs",
+    "output_specs",
+    "InputSpec",
+    "OutputSpec",
+    "parse_param_docs",
+    "shortest_unique_paths",
+    "get_configurable_attrs",
+    "to_pydantic",
+    "confluid_class_of",
+    "discover_dimensions",
+    "ValidationMode",
+    "ValidationPolicy",
+    "get_policy",
+    "set_policy",
+    "reset_policy",
+    "validate_model",
+    "sanitize_schema",
+]
+
+if TYPE_CHECKING:
+    from confluid.pydantic_export import confluid_class_of, to_pydantic
+
+# Names served lazily from ``confluid.pydantic_export`` (requires the
+# ``confluid[pydantic]`` extra) — see the module docstring.
+_PYDANTIC_EXPORTS = ("to_pydantic", "confluid_class_of")
+
+
+def __getattr__(name: str) -> Any:
+    if name in _PYDANTIC_EXPORTS:
+        try:
+            from confluid import pydantic_export
+        except ModuleNotFoundError as exc:
+            if exc.name in ("pydantic", "annotated_types"):
+                raise ImportError(
+                    f"confluid.{name} requires pydantic, which is an optional dependency — "
+                    "install the extra: pip install 'confluid[pydantic]'"
+                ) from exc
+            raise
+        return getattr(pydantic_export, name)
+    raise AttributeError(f"module 'confluid' has no attribute {name!r}")

confluid/bake.py

@@ -0,0 +1,174 @@
+"""Build-time AST bake of ``__init__`` body-slot names — the packaged-mode scan.
+
+Confluid's broadcasting discovers post-init body attributes (``self.loss_fn = …``
+inside ``__init__``) by AST-scanning constructor SOURCE at runtime
+(:func:`confluid.introspect.scan_init_body`). Compiled / frozen / zip
+deployments ship no source, so the runtime scan is silently empty and body
+slots vanish from the broadcast surface. This module runs the SAME scan at
+BUILD time — while source still exists — and emits a generated
+``<package>/_confluid_baked.py`` table that the engine unions in at runtime
+(scanned ∪ declared ``broadcast_attrs`` ∪ baked): automatic dev/packaged
+parity, no hand-maintained ``broadcast_attrs`` lists.
+
+Run it in the packaging pipeline, BEFORE freezing/zipping::
+
+    python -m confluid.bake mypackage [otherpackage ...]
+    python -m confluid.bake mypackage --check   # CI drift guard (no write)
+
+Every class the package defines with its own ``__init__`` is baked — not only
+``@configurable`` ones — so in-package base classes contribute their body
+slots through the MRO exactly as the runtime scan would. An empty entry is
+meaningful ("scanned at build time, no body slots"): it silences the engine's
+cannot-scan warning for that class.
+
+Frozen-bundler caveat: the engine imports ``<pkg>._confluid_baked`` lazily by
+dotted name (:func:`confluid.introspect.baked_init_attrs`), which static
+import tracers (PyInstaller) don't see — declare it as a hidden import
+(``--hidden-import mypkg._confluid_baked``) or import it explicitly from the
+package's ``__init__``. Wheel/zip/pyc-only deployments need nothing extra.
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import pkgutil
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from loggair import get_logger
+
+from confluid.exceptions import ConfigurationError
+from confluid.introspect import BAKED_MODULE_BASENAME, init_setattr_names
+
+logger = get_logger("confluid.bake")
+
+_HEADER_TEMPLATE = """\
+# =========================================================================
+# AUTO-GENERATED FILE — DO NOT EDIT BY HAND
+# Generated by: python -m confluid.bake {package}
+# Source: confluid/bake.py (bake_broadcast_attrs)
+# To regenerate: python -m confluid.bake {package}
+# =========================================================================
+\"\"\"Baked ``__init__`` body-slot names for ``{package}`` (build-time AST scan).
+
+Consumed by ``confluid.introspect.baked_init_attrs`` so broadcasting keeps
+seeing post-init attributes in compiled/frozen/zip deployments where
+``inspect.getsource`` fails. See ``confluid/bake.py``.
+\"\"\"
+
+from typing import Dict, Tuple
+
+BROADCAST_ATTRS: Dict[str, Tuple[str, ...]] = {{
+{entries}}}
+"""
+
+
+def scan_package(package_name: str) -> Dict[str, Tuple[str, ...]]:
+    """AST-scan every class the package defines; return ``{module.QualName: (names,)}``.
+
+    Imports the package and each of its submodules (a module that fails to
+    import is skipped with a warning — its classes simply stay unbaked), then
+    scans the ``__init__`` of every top-level class DEFINED in those modules
+    (``cls.__module__`` matches — re-exports are skipped, as is the bake
+    module itself). Deterministic: modules and attr names are sorted.
+    """
+    package = importlib.import_module(package_name)
+    module_names: List[str] = [package_name]
+    search_paths = getattr(package, "__path__", None)
+    if search_paths is not None:
+        module_names.extend(info.name for info in pkgutil.walk_packages(search_paths, prefix=f"{package_name}."))
+
+    table: Dict[str, Tuple[str, ...]] = {}
+    for module_name in sorted(module_names):
+        if module_name.rsplit(".", 1)[-1] == BAKED_MODULE_BASENAME:
+            continue  # never scan a previous bake output
+        try:
+            module = importlib.import_module(module_name)
+        except Exception as exc:  # noqa: BLE001 — a broken optional submodule must not kill the bake
+            logger.warning(f"confluid.bake: skipping module {module_name!r} (import failed: {exc})")
+            continue
+        for value in vars(module).values():
+            if not isinstance(value, type) or value.__module__ != module_name:
+                continue
+            init = value.__dict__.get("__init__")
+            if init is None:
+                continue
+            table[f"{value.__module__}.{value.__qualname__}"] = tuple(sorted(init_setattr_names(init)))
+    return table
+
+
+def render_baked_module(package_name: str, table: Dict[str, Tuple[str, ...]]) -> str:
+    """Render the generated ``_confluid_baked.py`` source (deterministic output)."""
+    lines: List[str] = []
+    for key in sorted(table):
+        names = table[key]
+        # ("a",) — the trailing comma keeps 1-tuples valid; () renders bare.
+        rendered = "(" + "".join(f"{name!r}, " for name in names).rstrip() + ")" if names else "()"
+        lines.append(f"    {key!r}: {rendered},\n")
+    return _HEADER_TEMPLATE.format(package=package_name, entries="".join(lines))
+
+
+def baked_module_path(package_name: str) -> Path:
+    """Filesystem location of the package's bake table (``<pkg>/_confluid_baked.py``)."""
+    package = importlib.import_module(package_name)
+    package_file = getattr(package, "__file__", None)
+    if package_file is None:
+        raise ConfigurationError(
+            f"confluid.bake: package {package_name!r} has no __file__ (namespace package?) — "
+            "the bake table needs a regular package directory to live in."
+        )
+    return Path(package_file).parent / f"{BAKED_MODULE_BASENAME}.py"
+
+
+def bake_broadcast_attrs(package_names: List[str], check: bool = False) -> Dict[str, Any]:
+    """Scan each package and write (or, with ``check=True``, verify) its bake table.
+
+    Returns a JSON-serializable summary per package:
+    ``{package: {"path": str, "classes": int, "changed": bool}}`` — ``changed``
+    means the on-disk table differed from the fresh scan (in check mode
+    nothing is written; the caller decides whether drift fails the build).
+    """
+    summary: Dict[str, Any] = {}
+    for package_name in package_names:
+        table = scan_package(package_name)
+        rendered = render_baked_module(package_name, table)
+        path = baked_module_path(package_name)
+        existing = path.read_text() if path.exists() else None
+        changed = existing != rendered
+        if changed and not check:
+            path.write_text(rendered)
+            logger.info(f"confluid.bake: wrote {path} ({len(table)} classes)")
+        summary[package_name] = {"path": str(path), "classes": len(table), "changed": changed}
+    return summary
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    """CLI entry point: ``python -m confluid.bake <package> [...] [--check]``."""
+    parser = argparse.ArgumentParser(
+        prog="python -m confluid.bake",
+        description="Bake __init__ body-slot names into <package>/_confluid_baked.py "
+        "so broadcasting keeps working in compiled/frozen deployments.",
+    )
+    parser.add_argument("packages", nargs="+", help="importable package names to scan")
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="verify the existing bake tables are up to date (write nothing; exit 1 on drift)",
+    )
+    args = parser.parse_args(argv)
+
+    summary = bake_broadcast_attrs(args.packages, check=args.check)
+    drifted = [pkg for pkg, info in summary.items() if info["changed"]]
+    for pkg, info in summary.items():
+        status = "STALE" if info["changed"] and args.check else ("updated" if info["changed"] else "up to date")
+        print(f"{pkg}: {info['classes']} classes -> {info['path']} [{status}]")
+    if args.check and drifted:
+        print(f"bake tables out of date for: {', '.join(drifted)} — rerun python -m confluid.bake", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())