quadkit 0.0.4__tar.gz → 0.0.42__tar.gz

{quadkit-0.0.4 → quadkit-0.0.42}/.gitignore

@@ -149,6 +149,27 @@ apps/**/*.pyc
 apps/**/*.db
 apps/**/*.db-wal
 apps/**/*.db-shm
+apps/**/.env
+apps/**/.env.*
+!apps/**/.env.example
+!apps/**/.env.full.example
+
+# Piccolina — nested app tracked in this monorepo (standalone .git removed).
+# Keep marketing packages and deployment secrets out of the tree.
+apps/piccolina/piccolina-marketing/
+apps/piccolina/piccolina-marketing-plans/
+apps/piccolina/secrets/
+apps/piccolina/**/secrets/
+apps/piccolina/**/*.pem
+apps/piccolina/**/*.key
+apps/piccolina/**/.venv/
+apps/piccolina/**/node_modules/
+apps/piccolina/**/__pycache__/
+apps/piccolina/**/*.pyc
+apps/piccolina/**/*.pbf
+apps/piccolina/**/.open-next/
+apps/piccolina/**/storage/
+apps/piccolina/**/.deploy-host
 
 # Re-exclude private content under the tiered paths.
 # MUST come after the !...docs/** negations above — last match wins.
@@ -180,4 +201,14 @@ test.db
 !packages/*/quadkit*/docs/gifs/
 !packages/*/quadkit*/docs/gifs/**
 examples/*/screenshot.png
-!banner*
+!banner*
+apps/quadkit-playground/**/node_modules/
+apps/quadkit-playground/**/dist/
+apps/quadkit-playground/**/__pycache__/
+apps/quadkit-playground/**/*.pyc
+apps/quadkit-playground/**/*.db
+apps/quadkit-playground/**/*.db-wal
+apps/quadkit-playground/**/*.db-shm
+apps/quadkit-playground/projects/
+apps/quadkit-playground/quadkit/
+docs/superpowers/

{quadkit-0.0.4 → quadkit-0.0.42}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quadkit
-Version: 0.0.4
+Version: 0.0.42
 Summary: Async-first DI/IoC framework for Python — core package
 Project-URL: Homepage, https://dbtinoy-.github.io/quadkit/
 Project-URL: Repository, https://github.com/dbtinoy-/quadkit
@@ -27,6 +27,7 @@ Classifier: Typing :: Typed
 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: structlog<27,>=25.1.0
 Provides-Extra: codegen
@@ -250,10 +251,10 @@ report vulnerabilities privately per
 
 ## Stability
 
-Version `0.0.3` in the `0.x` series, released in lockstep with the
+Version `0.0.42` in the `0.x` series, released in lockstep with the
 other four distributions; APIs may change between minor versions until
 1.0 — pin an exact version
-(`quadkit==0.0.3`) or a tight range (`>=0.0.3,<0.1.0`). Full policy:
+(`quadkit==0.0.42`) or a tight range (`>=0.0.42,<0.1.0`). Full policy:
 [stability and compatibility](https://dbtinoy-.github.io/quadkit/reference/stability/).
 
 ## Links

{quadkit-0.0.4 → quadkit-0.0.42}/README.md

@@ -199,10 +199,10 @@ report vulnerabilities privately per
 
 ## Stability
 
-Version `0.0.3` in the `0.x` series, released in lockstep with the
+Version `0.0.42` in the `0.x` series, released in lockstep with the
 other four distributions; APIs may change between minor versions until
 1.0 — pin an exact version
-(`quadkit==0.0.3`) or a tight range (`>=0.0.3,<0.1.0`). Full policy:
+(`quadkit==0.0.42`) or a tight range (`>=0.0.42,<0.1.0`). Full policy:
 [stability and compatibility](https://dbtinoy-.github.io/quadkit/reference/stability/).
 
 ## Links

{quadkit-0.0.4 → quadkit-0.0.42}/pyproject.toml

@@ -30,7 +30,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quadkit"
-version = "0.0.4"
+version = "0.0.42"
 description = "Async-first DI/IoC framework for Python — core package"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -74,6 +74,7 @@ dependencies = [
     "orjson>=3.0.0,<4",
     "structlog>=25.1.0,<27",         # Structured logging foundation
     "pydantic>=2.10.0,<3",              # Required: used unconditionally by config, validation
+    "pyyaml>=6.0.0,<7",                 # Required: YAML config file parsing
 ]
 
 # =============================================================================

{quadkit-0.0.4 → quadkit-0.0.42}/src/quadkit/app/config/models.py

@@ -23,6 +23,12 @@ class AppConfig:
     # ``name`` is the canonical YAML key under ``app:``; ``app_name`` remains
     # supported for compatibility with the original flat configuration.
     name: str | None = None
+    # ``version`` is the canonical YAML key under ``app:`` (application
+    # version string). Declared so apps that pin ``app.version`` in
+    # application.yaml bind cleanly — unknown keys raise ConfigSourceError
+    # from Application.stop()/get_section().
+    version: str = "0.0.0"
+    # consumed by: Application — version surfaced in health/telemetry
     # consumed by: OTEL resource attribute, logger context, AppProvider
     debug: bool | str = False
     # consumed by: Application — verbose startup/teardown logging

{quadkit-0.0.4 → quadkit-0.0.42}/src/quadkit/codegen/__init__.py

@@ -1,4 +1,5 @@
 from quadkit.codegen.base import GeneratorBase
+from quadkit.codegen.field_types import annotation_for, import_lines
 from quadkit.contracts.cli.generators import GenerationResult
 from quadkit.contracts.cli.parsers import FieldSpec, parse_fields
 
@@ -6,5 +7,7 @@ __all__ = [
     "FieldSpec",
     "GenerationResult",
     "GeneratorBase",
+    "annotation_for",
+    "import_lines",
     "parse_fields",
 ]

quadkit-0.0.42/src/quadkit/codegen/field_types.py

@@ -0,0 +1,131 @@
+"""Field-type vocabulary for the CLI code generators.
+
+Field types arrive as free-form identifiers from ``--fields`` strings
+(``order_id:uuid,total:decimal,payload:json``) and generators render them
+straight into annotations -- dataclass fields, Pydantic model fields, function
+signatures. Rendering the token verbatim only
+works while the token happens to be a builtin: ``float`` and ``str`` are fine,
+but ``uuid``, ``datetime``, ``date``, ``time`` and ``json`` are *not* names in
+the generated module, so a payload carrying any of them produced a file that
+raised ``NameError`` on import — the module could not even be collected by
+pytest.
+
+Two things have to agree for a field to render correctly, so they live
+together here: the annotation for a token, and the import that annotation
+needs. ``date`` is a ``datetime`` name, ``UUID`` is a ``uuid`` name, and
+``dict[str, Any]`` needs ``Any`` — an annotation vocabulary without its import
+list is how the original bug happened.
+
+Unknown tokens fall back to themselves, matching the SQL vocabulary's stance
+that a typo degrades rather than blocks generation; the difference is that a
+*known* token now always renders a name that exists.
+
+This lives in ``quadkit.codegen`` because every generator that renders a field
+already imports from here (``parse_fields`` is the other half of the same
+contract): the vocabulary and the parser that produces its input belong
+together, and a second copy is how the two halves drift apart again.
+
+``quadkit-sql`` keeps its own table: SQLAlchemy columns need a second mapping
+(``String(length=255)``, ``Text``) that has no meaning for a payload.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+import re
+
+#: Field type → Python annotation for a dataclass field or signature.
+PY_TYPES: dict[str, str] = {
+    # Text — an event payload carries values, so URL-ish tokens stay strings:
+    # a domain event is a frozen dataclass, not a validated Pydantic model,
+    # and importing a validator type for one field would point the dependency
+    # the wrong way.
+    "str": "str",
+    "string": "str",
+    "text": "str",
+    "slug": "str",
+    "char": "str",
+    "email": "str",
+    "phone": "str",
+    "filename": "str",
+    "filepath": "str",
+    "enum": "str",
+    "url": "str",
+    "uri": "str",
+    "ipv4": "str",
+    "ipv6": "str",
+    "ip": "str",
+    # Numeric
+    "int": "int",
+    "integer": "int",
+    "bigint": "int",
+    "smallint": "int",
+    "float": "float",
+    "double": "float",
+    "number": "float",
+    "decimal": "float",
+    "numeric": "float",
+    "money": "float",
+    # Boolean and temporal
+    "bool": "bool",
+    "boolean": "bool",
+    "datetime": "datetime",
+    "timestamp": "datetime",
+    "date": "date",
+    "time": "time",
+    # Identifiers and structured data
+    "uuid": "UUID",
+    "json": "dict[str, Any]",
+    "jsonb": "dict[str, Any]",
+    "dict": "dict[str, Any]",
+    "object": "dict[str, Any]",
+    "bytes": "bytes",
+    "blob": "bytes",
+    "binary": "bytes",
+}
+
+#: Annotation → the module and name that provide it.
+ANNOTATION_SOURCES: dict[str, tuple[str, str]] = {
+    "UUID": ("uuid", "UUID"),
+    "datetime": ("datetime", "datetime"),
+    "date": ("datetime", "date"),
+    "time": ("datetime", "time"),
+    "Any": ("typing", "Any"),
+}
+
+
+def annotation_for(field_type: str) -> str:
+    """The Python annotation for a field-spec type token."""
+    return PY_TYPES.get(field_type.strip().lower(), field_type.strip())
+
+
+def import_lines(
+    field_types: Iterable[str], *, always: Iterable[str] = ()
+) -> list[str]:
+    """One import line per module needed by the rendered annotations.
+
+    Args:
+        field_types: Raw field-spec tokens from the ``--fields`` string.
+        always: Annotations the template renders outside the payload — the
+            event template's ``aggregate_id: UUID``, the command and query
+            templates' ``Any`` — so they are imported whether or not a field
+            happens to ask for them. Templates have no import machinery of
+            their own; this is it.
+    """
+    per_module: dict[str, set[str]] = {}
+    for field_type in [*field_types, *always]:
+        rendered = annotation_for(field_type)
+        # Scan the *rendered annotation* rather than looking the token up in a
+        # second table: a composite annotation carries more than one name
+        # (``dict[str, Any]`` needs ``Any``), and the names are what the file
+        # has to import.
+        for name, (module, _) in ANNOTATION_SOURCES.items():
+            if re.search(rf"\b{name}\b", rendered):
+                per_module.setdefault(module, set()).add(name)
+    return [
+        f"from {module} import {', '.join(sorted(names))}"
+        for module, names in sorted(per_module.items())
+    ]
+
+
+__all__ = ["ANNOTATION_SOURCES", "PY_TYPES", "annotation_for", "import_lines"]

quadkit-0.0.42/src/quadkit/observability/di/sub_providers/observability.py

@@ -0,0 +1,68 @@
+"""No-op observability provider registered by the Quadkit core framework."""
+
+from __future__ import annotations
+
+from quadkit.contracts.core.di import (
+    ContainerRegistrarProtocol,
+    ContainerResolverProtocol,
+)
+from quadkit.contracts.core.health import HealthCheckProtocol
+from quadkit.contracts.observability.metrics import (
+    HealthCheckRegistryProtocol,
+    MetricsCollectorProtocol,
+    MetricsFactoryProtocol,
+    MetricsRecorderProtocol,
+)
+from quadkit.contracts.observability.tracing import TracerProtocol
+from quadkit.di.provider import Provider, ProviderPriority
+from quadkit.observability.core import (
+    NoOpHealthCheckRegistry,
+    NoOpMetricsCollector,
+    NoOpTracer,
+)
+
+
+class ObservabilityProvider(Provider):
+    """Provides no-op observability bindings for the core framework."""
+
+    name = "observability"
+    priority = ProviderPriority.INFRASTRUCTURE
+
+    async def register(self, container: ContainerRegistrarProtocol) -> None:
+        """Register the no-op observability implementations.
+
+        These bindings are fallbacks: they let application code compile and
+        run without ``quadkit-monitor``, but they must never win over a real
+        implementation. The container overwrites a token with the last
+        registration, so registering unconditionally makes the winner depend
+        on module composition order — and in nested module graphs this
+        provider lands *after* ``MonitorProvider`` and suppresses the concrete
+        collector. Guard each token, the same pattern the other fallback
+        sites use (``quadkit-auth``, ``quadkit-cache``, ``quadkit-ai-relay``),
+        so whichever real implementation registered first survives.
+        """
+        collector = NoOpMetricsCollector()
+        if not container.has(MetricsCollectorProtocol):
+            container.singleton(MetricsCollectorProtocol, collector)
+        if not container.has(MetricsRecorderProtocol):
+            container.singleton(MetricsRecorderProtocol, collector)
+        if not container.has(MetricsFactoryProtocol):
+            container.singleton(MetricsFactoryProtocol, collector)
+
+        if not container.has(TracerProtocol):
+            container.singleton(TracerProtocol, NoOpTracer())
+
+        registry = NoOpHealthCheckRegistry()
+        if not container.has(HealthCheckRegistryProtocol):
+            container.singleton(HealthCheckRegistryProtocol, registry)
+        if not container.has(HealthCheckProtocol):
+            container.singleton(HealthCheckProtocol, registry)
+
+    async def boot(self, container: ContainerResolverProtocol) -> None:
+        """No boot-time work is required."""
+
+    async def shutdown(self) -> None:
+        """No resources need teardown."""
+
+
+__all__ = ["ObservabilityProvider"]

{quadkit-0.0.4 → quadkit-0.0.42}/tests/unit/test_observability.py

@@ -200,6 +200,7 @@ class TestObservabilityProvider:
 
         provider = ObservabilityProvider()
         container = MagicMock()
+        container.has.return_value = False
         await provider.register(container)
 
         bound_abstracts = [c.args[0] for c in container.singleton.call_args_list]
@@ -224,6 +225,7 @@ class TestObservabilityProvider:
             return None
 
         container = MagicMock()
+        container.has.return_value = False
         container.singleton = capture_singleton
 
         await provider.register(container)
@@ -269,10 +271,53 @@ class TestObservabilityProvider:
 
         provider = ObservabilityProvider()
         container = MagicMock()
+        container.has.return_value = False
         await provider.register(container)
 
         assert container.singleton.call_count == 6
 
+    @pytest.mark.asyncio
+    async def test_skips_tokens_a_real_implementation_already_holds(self) -> None:
+        """Fallback bindings must not overwrite an already-registered token.
+
+        The container keeps the last registration; an unconditional register
+        here let composition order decide the winner, and nested module graphs
+        can land the no-op *after* a real implementation.
+        """
+        from quadkit.observability.di.sub_providers.observability import (
+            ObservabilityProvider,
+        )
+
+        provider = ObservabilityProvider()
+        container = MagicMock()
+        container.has.return_value = True
+        await provider.register(container)
+
+        assert container.singleton.call_count == 0
+
+    @pytest.mark.asyncio
+    async def test_only_missing_tokens_are_filled(self) -> None:
+        """A partially populated container gets the remaining five no-ops."""
+        from quadkit.observability.di.sub_providers.observability import (
+            ObservabilityProvider,
+        )
+
+        provider = ObservabilityProvider()
+        container = MagicMock()
+        container.has.side_effect = (
+            lambda service_type: service_type is MetricsCollectorProtocol
+        )
+        await provider.register(container)
+
+        bound_abstracts = [c.args[0] for c in container.singleton.call_args_list]
+        assert bound_abstracts == [
+            MetricsRecorderProtocol,
+            MetricsFactoryProtocol,
+            TracerProtocol,
+            HealthCheckRegistryProtocol,
+            HealthCheckProtocol,
+        ]
+
 
 class TestPackageExports:
     """Verify the observability package exports the canonical no-op classes."""

quadkit-0.0.4/src/quadkit/observability/di/sub_providers/observability.py

@@ -1,52 +0,0 @@
-"""No-op observability provider registered by the Quadkit core framework."""
-
-from __future__ import annotations
-
-from quadkit.contracts.core.di import (
-    ContainerRegistrarProtocol,
-    ContainerResolverProtocol,
-)
-from quadkit.contracts.core.health import HealthCheckProtocol
-from quadkit.contracts.observability.metrics import (
-    HealthCheckRegistryProtocol,
-    MetricsCollectorProtocol,
-    MetricsFactoryProtocol,
-    MetricsRecorderProtocol,
-)
-from quadkit.contracts.observability.tracing import TracerProtocol
-from quadkit.di.provider import Provider, ProviderPriority
-from quadkit.observability.core import (
-    NoOpHealthCheckRegistry,
-    NoOpMetricsCollector,
-    NoOpTracer,
-)
-
-
-class ObservabilityProvider(Provider):
-    """Provides no-op observability bindings for the core framework."""
-
-    name = "observability"
-    priority = ProviderPriority.INFRASTRUCTURE
-
-    async def register(self, container: ContainerRegistrarProtocol) -> None:
-        """Register the no-op observability implementations."""
-        collector = NoOpMetricsCollector()
-        container.singleton(MetricsCollectorProtocol, collector)
-        container.singleton(MetricsRecorderProtocol, collector)
-        container.singleton(MetricsFactoryProtocol, collector)
-
-        tracer = NoOpTracer()
-        container.singleton(TracerProtocol, tracer)
-
-        registry = NoOpHealthCheckRegistry()
-        container.singleton(HealthCheckRegistryProtocol, registry)
-        container.singleton(HealthCheckProtocol, registry)
-
-    async def boot(self, container: ContainerResolverProtocol) -> None:
-        """No boot-time work is required."""
-
-    async def shutdown(self) -> None:
-        """No resources need teardown."""
-
-
-__all__ = ["ObservabilityProvider"]