quadkit 0.0.46__tar.gz → 0.0.50__tar.gz

{quadkit-0.0.46 → quadkit-0.0.50}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quadkit
-Version: 0.0.46
+Version: 0.0.50
 Summary: Async-first DI/IoC framework for Python — core package
 Project-URL: Homepage, https://oridecon.dev
 Project-URL: Repository, https://github.com/dbtinoy-/quadkit
@@ -28,7 +28,7 @@ Requires-Python: >=3.11
 Requires-Dist: orjson<4,>=3.0.0
 Requires-Dist: pydantic<3,>=2.10.0
 Requires-Dist: pyyaml<7,>=6.0.0
-Requires-Dist: quadkit-contracts>=0.0.2
+Requires-Dist: quadkit-contracts>=0.0.50
 Requires-Dist: structlog<27,>=25.1.0
 Provides-Extra: codegen
 Requires-Dist: jinja2<4,>=3.1.0; extra == 'codegen'
@@ -39,6 +39,8 @@ Requires-Dist: ruff<1,>=0.16.4; extra == 'dev'
 Provides-Extra: docs
 Requires-Dist: mkdocs-material<10,>=9.0.0; extra == 'docs'
 Requires-Dist: mkdocs<2,>=1.4.0; extra == 'docs'
+Provides-Extra: email
+Requires-Dist: email-validator<3,>=2.0.0; extra == 'email'
 Provides-Extra: security
 Requires-Dist: cryptography<52,>=41.0.0; extra == 'security'
 Provides-Extra: test
@@ -47,7 +49,7 @@ Requires-Dist: pytest-cov<8,>=4.0.0; extra == 'test'
 Requires-Dist: pytest-mock<4,>=3.10.0; extra == 'test'
 Requires-Dist: pytest<10,>=8.0.0; extra == 'test'
 Provides-Extra: web
-Requires-Dist: quadkit-web[granian]>=0.0.2; extra == 'web'
+Requires-Dist: quadkit-web[granian]>=0.0.50; extra == 'web'
 Description-Content-Type: text/markdown
 
 # quadkit
@@ -251,10 +253,10 @@ report vulnerabilities privately per
 
 ## Stability
 
-Version `0.0.46` in the `0.x` series, released in lockstep with the
-other twelve distributions; APIs may change between minor versions until
+Version `0.0.50` in the `0.x` series, versioned independently of the
+other distributions; APIs may change between minor versions until
 1.0 — pin an exact version
-(`quadkit==0.0.46`) or a tight range (`>=0.0.46,<0.1.0`). Full policy:
+(`quadkit==0.0.50`) or a tight range (`>=0.0.50,<0.1.0`). Full policy:
 [stability and compatibility](https://oridecon.dev/quadkit/ecosystem/compatibility/).
 
 ## Links

{quadkit-0.0.46 → quadkit-0.0.50}/README.md

@@ -199,10 +199,10 @@ report vulnerabilities privately per
 
 ## Stability
 
-Version `0.0.46` in the `0.x` series, released in lockstep with the
-other twelve distributions; APIs may change between minor versions until
+Version `0.0.50` in the `0.x` series, versioned independently of the
+other distributions; APIs may change between minor versions until
 1.0 — pin an exact version
-(`quadkit==0.0.46`) or a tight range (`>=0.0.46,<0.1.0`). Full policy:
+(`quadkit==0.0.50`) or a tight range (`>=0.0.50,<0.1.0`). Full policy:
 [stability and compatibility](https://oridecon.dev/quadkit/ecosystem/compatibility/).
 
 ## Links

{quadkit-0.0.46 → quadkit-0.0.50}/pyproject.toml

@@ -29,7 +29,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quadkit"
-version = "0.0.46"
+version = "0.0.50"
 description = "Async-first DI/IoC framework for Python — core package"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -69,7 +69,7 @@ maintainers = [
 # lifecycle, or exception hierarchy literally cannot function without it.
 
 dependencies = [
-    "quadkit-contracts>=0.0.2",
+    "quadkit-contracts>=0.0.50",
     "orjson>=3.0.0,<4",
     "structlog>=25.1.0,<27",         # Structured logging foundation
     "pydantic>=2.10.0,<3",              # Required: used unconditionally by config, validation
@@ -117,6 +117,11 @@ security = [
     "cryptography>=41.0.0,<52",
 ]
 
+# Validation extras — opt-in RFC 5322 email validation for quadkit.validation.EmailStr
+email = [
+    "email-validator>=2.0.0,<3",
+]
+
 # ── Extension Convenience Groups ──────────────────────────────────────
 # Users can install entire subsystems via:
 #   pip install quadkit[web]     → all web packages
@@ -124,7 +129,7 @@ security = [
 # ── Web & API ─────────────────────────────────────────────────────────
 
 web = [
-    "quadkit-web[granian]>=0.0.2",
+    "quadkit-web[granian]>=0.0.50",
 ]
 # NOTE: Convenience extras for the extension packages (db, cache, auth,
 # events, tasks, monitor, graphql) were removed. Those packages are not

{quadkit-0.0.46 → quadkit-0.0.50}/src/quadkit/__init__.py

@@ -14,6 +14,7 @@ from typing import Any, Final
 # Critical: enable namespace-package discovery for quadkit-* distributions.
 __path__ = pkgutil.extend_path(__path__, __name__)
 
+
 from quadkit.constants import __version__
 
 _ExportSpec = tuple[str, str | None]
@@ -126,6 +127,7 @@ _EXPORTS: Final[dict[str, _ExportSpec]] = {
     "module": ("quadkit.di.module", "module"),
     "partition": ("quadkit.result", "partition"),
     "provide": ("quadkit.di.function_provider", "provide"),
+    "refresh_namespace": ("quadkit.primitives.namespace", "refresh_namespace"),
     "request_context": ("quadkit.primitives.context", "request_scope"),
     "run_application": ("quadkit.app.runner", "run_application"),
     "save_disabled": ("quadkit.plugins.state", "save_disabled"),
@@ -260,6 +262,7 @@ __all__ = [
     "ops",
     "partition",
     "provide",
+    "refresh_namespace",
     "request_context",
     "retry",
     "run_application",

{quadkit-0.0.46 → quadkit-0.0.50}/src/quadkit/app/base.py

@@ -26,7 +26,7 @@ from quadkit.logging import get_logger
 from quadkit.logging.configurator import apply_config as _apply_logging_config
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterator
+    from collections.abc import AsyncIterator, Iterable
 
     from quadkit.di.module.dynamic import DynamicModule
     from quadkit.di.module.graph import CompiledModuleGraph
@@ -237,8 +237,11 @@ class Application(SecretsMixin, HealthProbeMixin):
             )
         self._modules.append(module)
 
-    def add_modules(self, modules: list[type | Any]) -> None:
-        """Add multiple modules. Must be called before ``start()``."""
+    def add_modules(self, modules: Iterable[type | Any]) -> None:
+        """Register modules in iterable order without mutating the collection.
+
+        Each item retains the same pre-start guard as ``add_module``.
+        """
         for mod in modules:
             self.add_module(mod)
 
@@ -380,8 +383,8 @@ class Application(SecretsMixin, HealthProbeMixin):
             sys.stderr.write("================================\n")
             sys.stderr.flush()
             try:
-                await self._orchestrator.shutdown()
-            except RuntimeError as cleanup_err:
+                await self._lifecycle.shutdown()
+            except Exception as cleanup_err:  # noqa: BLE001 — preserve the original startup failure
                 self._logger.exception(
                     "application.cleanup_failed",
                     error=str(cleanup_err),

{quadkit-0.0.46 → quadkit-0.0.50}/src/quadkit/app/discovery.py

@@ -14,7 +14,7 @@ from pathlib import Path
 import pkgutil
 from typing import TYPE_CHECKING, Any
 
-from quadkit.logging import get_logger
+from quadkit.logging import get_logger, safe_error_type
 
 if TYPE_CHECKING:
     from quadkit.di.provider import Provider
@@ -51,11 +51,11 @@ def discover_providers(packages: tuple[str, ...] | list[str]) -> list[Provider]:
                 instance = cls()
                 found.append(instance)
                 logger.debug("discovery.provider.found", provider=cls.__name__)
-            except Exception:  # noqa: BLE001 — a provider that cannot be instantiated without args is skipped, never a discovery failure
+            except Exception as exc:  # noqa: BLE001 — a provider that cannot be instantiated without args is skipped, never a discovery failure
                 logger.debug(
                     "discovery.provider.skipped",
                     provider=cls.__name__,
-                    reason="instantiation_failed",
+                    error_type=safe_error_type(exc),
                 )
 
     return found
@@ -166,8 +166,12 @@ def _scan_subclasses(package: str, base: type) -> list[type]:
         try:
             module = importlib.import_module(modname)
             results.extend(_collect_subclasses(module, base))
-        except (ImportError, ModuleNotFoundError, AttributeError) as e:
-            logger.debug("discovery.module.import_failed", module=modname, error=str(e))
+        except (ImportError, ModuleNotFoundError, AttributeError) as exc:
+            logger.debug(
+                "discovery.module.import_failed",
+                module=modname,
+                error_type=safe_error_type(exc),
+            )
 
     # Also scan the root module itself
     results.extend(_collect_subclasses(root, base))
@@ -180,12 +184,12 @@ def _collect_subclasses(module: Any, base: type) -> list[type]:
     for attr_name in dir(module):
         try:
             obj = getattr(module, attr_name)
-        except (AttributeError, TypeError) as e:
+        except (AttributeError, TypeError) as exc:
             logger.debug(
                 "discovery.getattr_failed",
                 module=module.__name__,
                 attr=attr_name,
-                error=str(e),
+                error_type=safe_error_type(exc),
             )
             continue
         if (
@@ -227,11 +231,12 @@ def discover_modules_from_entry_points(
     for ep in importlib.metadata.entry_points(group=group):
         try:
             obj = ep.load()
-        except Exception:  # noqa: BLE001
+        except Exception as exc:  # noqa: BLE001
             logger.warning(
                 "module_discovery_entry_point_load_failed",
                 group=group,
                 name=ep.name,
+                error_type=safe_error_type(exc),
             )
             continue
         if isinstance(obj, type) and issubclass(obj, Module) and obj is not Module:
@@ -241,7 +246,7 @@ def discover_modules_from_entry_points(
                 "module_discovery_entry_point_not_a_module",
                 group=group,
                 name=ep.name,
-                loaded=repr(obj),
+                loaded_type=type(obj).__name__,
             )
     return discovered
 
@@ -268,7 +273,7 @@ def discover_modules_from_directories(
     for directory in directories:
         path = Path(directory)
         if not path.exists() or not path.is_dir():
-            logger.debug("module_discovery_dir_skipped", path=str(path))
+            logger.debug("module_discovery_dir_skipped")
             continue
 
         for candidate in ("plugin.py", "__init__.py"):
@@ -283,10 +288,11 @@ def discover_modules_from_directories(
                     continue
                 mod = importlib.util.module_from_spec(spec)
                 spec.loader.exec_module(mod)
-            except Exception:  # noqa: BLE001
+            except Exception as exc:  # noqa: BLE001
                 logger.warning(
                     "module_discovery_dir_load_failed",
-                    file=str(file_path),
+                    candidate=candidate,
+                    error_type=safe_error_type(exc),
                 )
                 continue
 

{quadkit-0.0.46 → quadkit-0.0.50}/src/quadkit/app/lifecycle.py

@@ -76,8 +76,10 @@ class ApplicationLifecycle:
         self._logger.info("application.stopping", name=self._app_name)
 
         try:
-            await self._orchestrator.shutdown()
-            await self._container.dispose()
+            try:
+                await self._orchestrator.shutdown()
+            finally:
+                await self._container.dispose()
         finally:
             if self._start_time is not None:
                 self._uptime_seconds = time.monotonic() - self._start_time

{quadkit-0.0.46 → quadkit-0.0.50}/src/quadkit/app/module.py

@@ -255,10 +255,14 @@ class CoreModule(Module):
             if name not in consumed and name not in provider_names:
                 providers.append(provider)
 
+        exports = list(_CORE_EXPORTS)
+        if config_class is not None and config_class not in exports:
+            exports.append(config_class)
+
         return DynamicModule(
             module=cls,
             providers=providers,  # type: ignore[arg-type]
-            exports=list(_CORE_EXPORTS),
+            exports=exports,
             is_global=True,
         )
 

{quadkit-0.0.46 → quadkit-0.0.50}/src/quadkit/app/standard.py

@@ -219,10 +219,14 @@ class StandardModule(Module):
             if name not in consumed and name not in provider_names:
                 providers.append(provider)
 
+        exports = list(_STANDARD_EXPORTS)
+        if config_class is not None and config_class not in exports:
+            exports.append(config_class)
+
         return DynamicModule(
             module=cls,
             providers=providers,
-            exports=list(_STANDARD_EXPORTS),
+            exports=exports,
             is_global=True,
         )
 

quadkit-0.0.50/src/quadkit/codegen/__init__.py

@@ -0,0 +1,30 @@
+from quadkit.codegen.base import GeneratorBase
+from quadkit.codegen.field_types import annotation_for, import_lines
+from quadkit.contracts.cli.generators import (
+    GenerationResult,
+    derived_index_name,
+    pluralize_identifier,
+)
+from quadkit.contracts.cli.parsers import (
+    EntitySpec,
+    FieldSpec,
+    IndexSpec,
+    format_fields,
+    parse_fields,
+    resolve_field_specs,
+)
+
+__all__ = [
+    "EntitySpec",
+    "FieldSpec",
+    "GenerationResult",
+    "GeneratorBase",
+    "IndexSpec",
+    "annotation_for",
+    "derived_index_name",
+    "format_fields",
+    "import_lines",
+    "parse_fields",
+    "pluralize_identifier",
+    "resolve_field_specs",
+]

{quadkit-0.0.46 → quadkit-0.0.50}/src/quadkit/codegen/base.py

@@ -21,6 +21,9 @@ from quadkit.contracts.cli.generators import (
 from quadkit.contracts.cli.generators import (
     pascal_case as pascal_case,
 )
+from quadkit.contracts.cli.generators import (
+    pluralize_identifier as pluralize_identifier,
+)
 from quadkit.contracts.cli.generators import (
     resolve_options as resolve_options,
 )
@@ -44,6 +47,11 @@ class GeneratorBase:
     and guarded file writes work without it.
     """
 
+    #: Whether ``generate`` accepts and honors a structured
+    #: :class:`quadkit.contracts.cli.EntitySpec`. This is explicit opt-in:
+    #: bridges must never infer support merely from ``**options``.
+    supports_entity_spec: bool = False
+
     def __init__(
         self,
         output_dir: str | Path = "src",
@@ -312,6 +320,10 @@ class GeneratorBase:
     def _to_snake_case(name: str) -> str:
         return snake_case(name)
 
+    @staticmethod
+    def _pluralize(name: str) -> str:
+        return pluralize_identifier(name)
+
     @classmethod
     def _validate_component_name(cls, name: str) -> str:
         return validate_component_name(name)

{quadkit-0.0.46 → quadkit-0.0.50}/src/quadkit/concurrency/executors/task_manager.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import asyncio
 from typing import TYPE_CHECKING, Any
 
-from quadkit.logging import get_logger
+from quadkit.logging import get_logger, safe_error_type
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Coroutine
@@ -96,10 +96,9 @@ class TaskManager:
                     ):
                         raise
                     if isinstance(exc, Exception):
-                        self._logger.exception(
+                        self._logger.error(
                             "task_manager.periodic_task_error",
-                            task=name or "unnamed",
-                            error=str(exc),
+                            error_type=safe_error_type(exc),
                         )
                         continue
                     raise
@@ -146,11 +145,6 @@ class TaskManager:
                     timed_out=len(pending),
                     timeout=critical_timeout,
                 )
-                for task in pending:
-                    self._logger.warning(
-                        "task_manager.critical_incomplete",
-                        task=task.get_name(),
-                    )
 
         # Phase 2: Cancel background tasks
         if self._background:
@@ -211,7 +205,6 @@ class TaskManager:
         task.add_done_callback(target_set.discard)
         self._logger.debug(
             "task.created",
-            name=task_name,
             priority="critical" if critical else "background",
         )
         return task

{quadkit-0.0.46 → quadkit-0.0.50}/src/quadkit/concurrency/task_utils.py

@@ -11,7 +11,7 @@ import asyncio
 from collections.abc import Coroutine
 from typing import Any, TypeVar
 
-from quadkit.logging import get_logger
+from quadkit.logging import get_logger, safe_error_type
 
 logger = get_logger(__name__)
 
@@ -30,8 +30,7 @@ def _handle_task_exception(task: asyncio.Task[Any]) -> None:
     if exc is not None:
         logger.error(
             "background_task_failed",
-            task_name=task.get_name(),
-            exc_info=exc,
+            error_type=safe_error_type(exc),
         )
 
 

{quadkit-0.0.46 → quadkit-0.0.50}/src/quadkit/config/base.py

@@ -105,7 +105,6 @@ class BaseConfig(DomainModel):
         else:
             logger.info(
                 "config.defaults_only",
-                path=str(yaml_path),
                 hint="create application.yaml or set QK_* env vars",
             )
 
@@ -242,7 +241,8 @@ class BaseConfig(DomainModel):
         cls,
         profile: str | None = None,
         *,
-        base_path: str | Path = ".",
+        base_path: str | Path | None = None,
+        fallback_path: str | Path | None = None,
         section: str | None = None,
     ) -> Self:
         """Load config for a named environment profile.
@@ -269,7 +269,11 @@ class BaseConfig(DomainModel):
         Args:
             profile: Environment profile name.  When ``None``, the
                 ``QK_PROFILE`` env-var is used.
-            base_path: Directory containing the profile YAML files.
+            base_path: Directory containing the profile YAML files (defaults to
+                the current working directory when ``None``).
+            fallback_path: Optional secondary directory (such as a workspace
+                member's package root) consulted when ``application.yaml`` is
+                not present in *base_path*.
             section: Override the section key for this call.  When omitted,
                 :attr:`config_section` is used automatically.
 
@@ -281,9 +285,13 @@ class BaseConfig(DomainModel):
             # Explicit override (e.g. non-standard nesting)
             config = CacheConfig.from_env_profile(section="services.cache")
         """
-        return cls.from_yaml(
-            Path(base_path) / "application.yaml", profile=profile, section=section
-        )
+        resolved_base = Path(base_path) if base_path is not None else Path()
+        yaml_file = resolved_base / "application.yaml"
+        if not yaml_file.exists() and fallback_path is not None:
+            candidate = Path(fallback_path) / "application.yaml"
+            if candidate.exists():
+                yaml_file = candidate
+        return cls.from_yaml(yaml_file, profile=profile, section=section)
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> Self:

{quadkit-0.0.46 → quadkit-0.0.50}/src/quadkit/config/di/provider.py

@@ -23,15 +23,13 @@ from quadkit.config.lib import (
 )
 from quadkit.config.main import QuadkitConfig
 from quadkit.contracts.core.config import ConfigProtocol
+from quadkit.contracts.core.di import ContainerResolverProtocol
 from quadkit.contracts.core.health import HealthCheckResult, HealthStatus
 from quadkit.di.provider import Provider, ProviderPriority
-from quadkit.logging import get_logger
+from quadkit.logging import get_logger, safe_error_type
 
 if TYPE_CHECKING:
-    from quadkit.contracts.core.di import (
-        ContainerRegistrarProtocol,
-        ContainerResolverProtocol,
-    )
+    from quadkit.contracts.core.di import ContainerRegistrarProtocol
 
 logger = get_logger(__name__)
 
@@ -70,34 +68,56 @@ class ConfigProvider(Provider):
     async def register(self, container: ContainerRegistrarProtocol) -> None:
         """Load configuration and register as a singleton."""
         if self._config_instance is None:
-            from pathlib import Path
-
-            loader = ConfigLoader()
-
-            # 1. Check for default application.yaml in CWD
-            yaml_path = Path.cwd() / "application.yaml"
-            try:
-                if yaml_path.exists():
-                    loader.add_source(FileConfigSource(yaml_path))
-            except (FileNotFoundError, OSError) as e:
-                logger.debug("no_default_config", path=str(yaml_path), reason=str(e))
-
-            # 2. Add custom sources if provided
-            if self.sources:
-                for source in self.sources:
-                    loader.add_source(source)
-
-            # 3. Always add env vars
-            prefix = self.env_prefix or "QK_"
-            loader.add_source(EnvironmentConfigSource(prefix))
-
-            # 4. Load and apply registry
-            self._config_instance = loader.load_sync(self.config_class)
-            self._registry.apply_to_instance(self._config_instance)
+            section = (
+                getattr(self.config_class, "config_section", "")
+                if not issubclass(self.config_class, QuadkitConfig)
+                else ""
+            )
+            if (
+                section
+                and not self.sources
+                and not self.env_prefix
+                and isinstance(container, ContainerResolverProtocol)
+                and container.has(QuadkitConfig)
+            ):
+                quadkit_cfg = await container.resolve(QuadkitConfig)
+                self._config_instance = quadkit_cfg.get_section(
+                    section, self.config_class
+                )
+                self._registry.apply_to_instance(self._config_instance)
+            else:
+                from pathlib import Path
+
+                loader = ConfigLoader()
+
+                # 1. Check for default application.yaml in CWD
+                yaml_path = Path.cwd() / "application.yaml"
+                try:
+                    if yaml_path.exists():
+                        loader.add_source(FileConfigSource(yaml_path))
+                except (FileNotFoundError, OSError) as exc:
+                    logger.debug(
+                        "no_default_config",
+                        error_type=safe_error_type(exc),
+                    )
+
+                # 2. Add custom sources if provided
+                if self.sources:
+                    for source in self.sources:
+                        loader.add_source(source)
+
+                # 3. Always add env vars
+                prefix = self.env_prefix or "QK_"
+                loader.add_source(EnvironmentConfigSource(prefix))
+
+                # 4. Load and apply registry
+                self._config_instance = loader.load_sync(self.config_class)
+                self._registry.apply_to_instance(self._config_instance)
 
         # 5. Register with multiple keys for compatibility
         container.singleton(self.config_class, instance=self._config_instance)
-        container.singleton(ConfigProtocol, instance=self._config_instance)
+        if hasattr(self._config_instance, "get_section"):
+            container.singleton(ConfigProtocol, instance=self._config_instance)
         # Also register as QuadkitConfig if it's a subclass of QuadkitConfig
         # and not already registered as the main config_class.
         if self.config_class is not QuadkitConfig and isinstance(