contextbase-shared-plugins 0.0.0a1__py3-none-any.whl

contextbase_shared_plugins-0.0.0a1.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.3
+Name: contextbase-shared-plugins
+Version: 0.0.0a1
+Summary: Shared infrastructure for ContextBase plugins
+Author: Alizain Feerasta
+Author-email: Alizain Feerasta <alizain.feerasta@gmail.com>
+Requires-Dist: contextbase-base-client==0.0.0a1
+Requires-Dist: airbyte
+Requires-Dist: azure-core>=1.30.0
+Requires-Dist: azure-identity>=1.25.1
+Requires-Dist: dagster==1.12.14
+Requires-Dist: dagster-dlt==0.28.14
+Requires-Dist: dlt[postgres]>=1.26.0
+Requires-Dist: google-api-python-client>=2.185.0
+Requires-Dist: google-auth>=2.0.0
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: microsoft-kiota-abstractions>=1.10.1
+Requires-Dist: microsoft-kiota-authentication-azure>=1.10.1
+Requires-Dist: microsoft-kiota-serialization-json>=1.11.7
+Requires-Dist: msgraph-core>=1.3.8
+Requires-Dist: psycopg2-binary
+Requires-Dist: pydantic>=2.12.0
+Requires-Dist: sqlalchemy>=2.0.0
+Requires-Dist: pydantic-settings>=2.13.1
+Requires-Dist: tenacity>=8.2
+Requires-Dist: sentry-sdk>=2.35.0
+Requires-Python: >=3.12, <3.13

contextbase_shared_plugins-0.0.0a1.dist-info/RECORD

@@ -0,0 +1,41 @@
+shared_plugins/__init__.py,sha256=qsWU9-bf0rmqndl4KN1W7sH3XR6uPiQzZNexICQeo4Q,378
+shared_plugins/automation.py,sha256=ZFpRzQUnyH_J_GoSZCrYYWNO6OcsnvbQ_kjFS2BnetA,380
+shared_plugins/base_platform.py,sha256=ASqlHugzwcdaqkatIKAX1CqPvrLYfLralsIpuURg7bU,4225
+shared_plugins/bindings.py,sha256=du7XzCkpNEMEzdH49fEmQsiofvBLCdAOKthzvf-vOKI,7725
+shared_plugins/dlt.py,sha256=T-GtgWLESlhkK3Bv4crWKY4370ZHXkWTSQBddM_BsJg,3151
+shared_plugins/env.py,sha256=TMrMsnM0qjOXuQsE4SmKD1gvpR28iOqt9ATEcP2GYQE,3647
+shared_plugins/exceptions.py,sha256=hV-Dn01TrvmFpMkRoNRy629KLL-Rdh3zi82z9JAodKM,318
+shared_plugins/google_client/__init__.py,sha256=56uWeZViYLtnuD5X5iSiwmbbZVSMSuRhpOhjpPrwrAk,62
+shared_plugins/google_client/auth.py,sha256=7F87U38qVKKtkdgg4-eiuFUdSbd-HdPOzUP4cg3AzgA,3955
+shared_plugins/google_client/batch_retry.py,sha256=sVK-uPXgF4a-ZDWunN_k5PUJYk1FsgvJzLYX3qmKrp8,10167
+shared_plugins/google_client/http_errors.py,sha256=j_8vQ4URdnKYBatrkqSq2GHrRCgyHJZufyZIpvEn3S8,806
+shared_plugins/machine_token.py,sha256=g87cKwpKoxmuU8qLRds-kcAHuYtdp45wrofKwU5xFAU,18243
+shared_plugins/microsoft_dataverse/__init__.py,sha256=xMLs_ICxnVkCfvpUHy-YK7d3ufk6OmUpVtweWLoudS4,840
+shared_plugins/microsoft_dataverse/annotations.py,sha256=fR53FSqMB-vJ9YgtsEPYJAoN7nVhCzqEGVCQ6Mp7qyY,2830
+shared_plugins/microsoft_dataverse/auth.py,sha256=PrMvAgfAT5fZt66zes6ShEzppFGSWCu5PudO0Y4wR8k,627
+shared_plugins/microsoft_dataverse/binding_config.py,sha256=VgrN6Xb3-dvi1IfQpdRHSK754almITY0YU9nCQh2Izk,1302
+shared_plugins/microsoft_dataverse/client.py,sha256=vpcBwiXmtCdTpIOTrhuD3qdnKla-C01JizcBd_4WIXw,17145
+shared_plugins/microsoft_dataverse/ctx.py,sha256=_nZYNPaDA9njvviwgMIdEKc815dnUM_CzwFGhqSMIpM,783
+shared_plugins/microsoft_dataverse/identifiers.py,sha256=OMzQI2vVgL4AvWHMybOyltpjqW2Sr7q_gHU4doJN6iE,2300
+shared_plugins/microsoft_dataverse/ingress.py,sha256=5PlVPxuzbY8whs6FjtTnqCVhFGHZnkzFzSgsf3RlO2U,2276
+shared_plugins/microsoft_dataverse/metadata.py,sha256=NV_JaviYd2JdOtMx1z1sN9ezMxGPWBO1XYt7COzG8s8,4510
+shared_plugins/microsoft_dataverse/runtime_schema.py,sha256=T1tNTX2CqOVGIBIY9YHNuc1dAFG60fD5owEH0224VD4,11554
+shared_plugins/microsoft_dataverse/source.py,sha256=3g2VHsVAvg8pX3vqWydJV41vvawEYsfU62W2SCma4rU,10728
+shared_plugins/microsoft_dataverse/tables.py,sha256=j-20oGgYTUrc6De7_cni7nR9D9XfcHfa6zyOgc_FU1I,1192
+shared_plugins/microsoft_dataverse/translators.py,sha256=4pEDDzESFJH_zebf-qjW3NrX9xqK5UIzexgnh0QCjgM,5329
+shared_plugins/microsoft_dataverse/types.py,sha256=kI9AewGBQ1UQPyxWyfYN5WVj8gWVQQLMt8gz33pRQAE,12416
+shared_plugins/microsoft_graph.py,sha256=Gu_kkqudUl0ygblZS6l98J6QDcGQI4vXnKxHeBT_ZwU,9413
+shared_plugins/models.py,sha256=m4nNrPTmwR1zV2EoUvuwfhS_WjBi05x61_bShOso3j0,2669
+shared_plugins/naming.py,sha256=tE7oANx8SxGjfDzZT0GqDcObzFLs_RrS_B2vw_cdPjU,2208
+shared_plugins/pg_column_comments.py,sha256=HTSC8Og4jPXdBaiEhrAN__k2UOnb3E_6g38teLp2Q7s,2346
+shared_plugins/provider_token.py,sha256=xhef0aBr3wx4iBxY-B438ALzcLMCYaMEWuF6lBZpACc,10482
+shared_plugins/pyairbyte.py,sha256=xh1nLO__XmKBD6nhIL0lpN9o6BfBL3-ROA9ambnOFwg,17111
+shared_plugins/resources.py,sha256=i-pVKSXmSBAjKh6-KfAppAcuGiPt4cerjExM6nxEqvs,5429
+shared_plugins/scratch.py,sha256=oZCJZSB5m80Ez7Ox8Ktl7rKV2vFIJyp8LBkZcXp6wlA,4176
+shared_plugins/sentry.py,sha256=n912Pi0Jkrw-LaTuUKOUozwA3QJq3O1wV4lnT_FGW7o,5367
+shared_plugins/sqlalchemy_types.py,sha256=1e_OxfUQzY377VlV4gidtVroK6FkgdOyMvgZeATxv8E,7123
+shared_plugins/sqlite.py,sha256=Pl3gXNixyQOrz19HgGojux0Ywkxukmub7rkwdkhU3QY,4301
+shared_plugins/values.py,sha256=DhTk62AvmPcfUvCa_n-dXN5zTdu4UN9tJeyjzMhGTl8,3199
+contextbase_shared_plugins-0.0.0a1.dist-info/WHEEL,sha256=i9aSRDivn5iP9LaR1BLQX2GNAuriQWPsFwbbWygTX2k,81
+contextbase_shared_plugins-0.0.0a1.dist-info/METADATA,sha256=s2QdcjgWge0nNhx4cnA2eteug7i7L69jZ8IA7vO2Hx8,1008
+contextbase_shared_plugins-0.0.0a1.dist-info/RECORD,,

contextbase_shared_plugins-0.0.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.15
+Root-Is-Purelib: true
+Tag: py3-none-any

shared_plugins/__init__.py

@@ -0,0 +1,8 @@
+"""Keep this module empty.
+
+Every symbol is imported from its canonical submodule (shared_plugins.models,
+shared_plugins.resources, ...). Anything imported here is paid by every
+process that touches any submodule — including stdlib-only ones like
+shared_plugins.sqlite — and the dlt/dagster tree costs seconds per
+interpreter. Enforced by tests/test_package_imports.py.
+"""

shared_plugins/automation.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+import dagster as dg
+
+
+def non_overlapping_automation_condition(
+    condition: dg.AutomationCondition,
+) -> dg.AutomationCondition:
+    # Cron and missing-based automation can keep requesting work while the
+    # current partition is still active unless we add this explicit guard.
+    return condition & ~dg.AutomationCondition.in_progress()

shared_plugins/base_platform.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from datetime import timezone
+
+import httpx
+from base_client import (
+    BaseAPIClient,
+    DagsterAllPlanBinding,
+    DagsterBindingPlanAll,
+)
+from base_client.sync_state import SyncStateInputBindingsValue
+
+# The binding-state wire-contract version, mirrored from base-schemas'
+# ``BINDING_STATE_VERSION`` (TS). It is a cross-language constant, so it is
+# duplicated in both trees; base-platform validates it as a literal on write.
+BINDING_STATE_VERSION = 1
+
+
+class BasePlatformClient:
+    """Thin daemon-side facade over the generated base-platform SDK
+    (``base_client``), bound to the single base this daemon serves.
+
+    Exposes the binding-plan reads the Dagster defs need
+    (``load_binding_plan`` / ``list_active_bindings`` / ``get_binding``) plus
+    the per-binding sync-state write the producer pushes up
+    (``report_binding_sync_state`` — F2), and carries the per-base ``base_id``
+    so callers stay base-agnostic — one Dagster code location serves one base.
+    Provider-token (OAuth) redemption is deliberately NOT here: it lives in
+    ``google_client/auth.py``, which redeems server-side via web's
+    ``/provider-token`` endpoint using the injected ``provider_token`` Dagster
+    resource (the credentials keystone).
+
+    ``auth`` is the per-request credential for the platform calls — the
+    ``aud=ctx`` machine Bearer in platform-managed deployments (the twin of the
+    TS CLIs' ``ctxAuthHeaders``), or ``None`` in local dev, where the platform
+    authorizes via its ``CTX_AUTH_SUB_ID`` trust-env mode and no token is
+    needed. ``transport`` swaps the socket for tests; ``client`` overrides the
+    SDK client wholesale (duck-typed facade tests), ignoring both.
+    """
+
+    def __init__(
+        self,
+        *,
+        platform_url: str,
+        base_id: str,
+        auth: httpx.Auth | None = None,
+        transport: httpx.BaseTransport | None = None,
+        client: BaseAPIClient | None = None,
+    ) -> None:
+        self._base_id = base_id
+        self._client = (
+            BaseAPIClient(
+                base_url=platform_url,
+                # Mirrors the SDK's own defaults (60s timeout, follow
+                # redirects); built here so auth applies to every request.
+                httpx_client=httpx.Client(
+                    timeout=60.0,
+                    follow_redirects=True,
+                    auth=auth,
+                    transport=transport,
+                ),
+            )
+            if client is None
+            else client
+        )
+
+    def load_binding_plan(self) -> DagsterBindingPlanAll:
+        plan = self._client.binding_plan.get_binding_plan(self._base_id)
+        # Normalize generated_at to UTC so downstream consumers compare
+        # timezone-aware timestamps consistently (parity with the prior
+        # hand-rolled client).
+        return plan.model_copy(
+            update={"generated_at": plan.generated_at.astimezone(timezone.utc)}
+        )
+
+    def list_active_bindings(self, plugin_id: str) -> list[DagsterAllPlanBinding]:
+        plan = self.load_binding_plan()
+        return [binding for binding in plan.bindings if binding.plugin_id == plugin_id]
+
+    def get_binding(self, plugin_id: str, binding_id: str) -> DagsterAllPlanBinding:
+        for binding in self.list_active_bindings(plugin_id):
+            if binding.binding_id == binding_id:
+                return binding
+
+        raise RuntimeError(
+            f"Binding '{binding_id}' was not found for plugin_id '{plugin_id}'."
+        )
+
+    def report_binding_sync_state(
+        self,
+        binding_id: str,
+        state: SyncStateInputBindingsValue,
+    ) -> None:
+        """Push one binding's freshness digest to base-platform (F2).
+
+        The event-driven producer recomputes a single binding per run-status
+        transition, so this wraps the SDK's multi-binding ``report_sync_state``
+        into a one-entry map and bakes the ``BINDING_STATE_VERSION`` wire
+        constant — callers supply only the binding and its digest.
+        """
+        self._client.sync_state.report_sync_state(
+            self._base_id,
+            bindings={binding_id: state},
+            version=BINDING_STATE_VERSION,
+        )

shared_plugins/bindings.py

@@ -0,0 +1,260 @@
+from __future__ import annotations
+
+import hashlib
+import importlib.util
+import os
+import sys
+from collections.abc import Callable, Collection, Iterable, Iterator
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Annotated, TypeVar
+
+from pydantic import (
+    BaseModel,
+    BeforeValidator,
+    ConfigDict,
+    Field,
+    StringConstraints,
+    ValidationError,
+)
+
+from base_client import (
+    BindingAuth_ApiKey,
+    BindingAuth_AuthenticatedAccount,
+    BindingAuth_ClientCredentials,
+    BindingAuth_None,
+    DagsterAllPlanBinding,
+)
+
+from .exceptions import PluginConfigurationError
+from .models import CtxModel
+
+RowFilter = Callable[[str, CtxModel], bool]
+RowT = TypeVar("RowT", bound=CtxModel)
+
+_UTC_TIMESTAMP_PATTERN = r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$"
+
+NonEmptyText = Annotated[
+    str,
+    StringConstraints(strip_whitespace=True, min_length=1),
+]
+UtcTimestampText = Annotated[
+    str,
+    StringConstraints(
+        strip_whitespace=True,
+        min_length=1,
+        pattern=_UTC_TIMESTAMP_PATTERN,
+    ),
+]
+StrictNonNegativeInt = Annotated[int, Field(strict=True, ge=0)]
+ResolvedPath = Annotated[
+    Path, BeforeValidator(lambda value: _resolve_binding_path(value))
+]
+
+
+class BaseBindingConfigModel(BaseModel):
+    """Canonical base class for every plugin's ``BindingConfig`` and any nested
+    sub-models it uses.
+
+    Declares ``extra="forbid"`` once so plugins never redeclare it and cannot
+    accidentally allow unknown keys. Every ``BaseModel`` that lives inside a
+    plugin's ``binding_config.py`` inherits from this class, at every depth of
+    the config tree.
+    """
+
+    model_config = ConfigDict(extra="forbid")
+
+
+BindingConfigT = TypeVar("BindingConfigT", bound=BaseBindingConfigModel)
+
+
+@dataclass(frozen=True)
+class ResolvedBindingModels:
+    active: tuple[str, ...]
+    filter: RowFilter | None
+
+
+def require_authenticated_account(
+    binding: DagsterAllPlanBinding,
+) -> BindingAuth_AuthenticatedAccount:
+    auth_payload = binding.auth
+    if isinstance(auth_payload, BindingAuth_AuthenticatedAccount):
+        return auth_payload
+
+    raise RuntimeError(
+        f"{binding.plugin_id} binding requires auth.type='authenticated_account', got '{auth_payload.type}'."
+    )
+
+
+def require_api_key(binding: DagsterAllPlanBinding) -> BindingAuth_ApiKey:
+    auth_payload = binding.auth
+    if isinstance(auth_payload, BindingAuth_ApiKey):
+        return auth_payload
+
+    raise RuntimeError(
+        f"{binding.plugin_id} binding requires auth.type='api_key', got '{auth_payload.type}'."
+    )
+
+
+def require_client_credentials(
+    binding: DagsterAllPlanBinding,
+) -> BindingAuth_ClientCredentials:
+    auth_payload = binding.auth
+    if isinstance(auth_payload, BindingAuth_ClientCredentials):
+        return auth_payload
+
+    raise RuntimeError(
+        f"{binding.plugin_id} binding requires auth.type='client_credentials', got '{auth_payload.type}'."
+    )
+
+
+def require_binding_auth_none(binding: DagsterAllPlanBinding) -> BindingAuth_None:
+    auth_payload = binding.auth
+    if isinstance(auth_payload, BindingAuth_None):
+        return auth_payload
+
+    raise RuntimeError(
+        f"{binding.plugin_id} binding requires auth.type='none', got '{auth_payload.type}'."
+    )
+
+
+def parse_binding_config(
+    binding: DagsterAllPlanBinding,
+    config_model: type[BindingConfigT],
+) -> BindingConfigT:
+    try:
+        return config_model.model_validate(binding.config)
+    except ValidationError as exc:
+        raise PluginConfigurationError(
+            f"{binding.plugin_id} binding.config is invalid: {exc}"
+        ) from exc
+
+
+def resolve_binding_models(
+    binding: DagsterAllPlanBinding,
+    *,
+    supported_models: Collection[str],
+    default_active: Collection[str] = (),
+) -> ResolvedBindingModels:
+    models_payload = binding.models
+    raw_active = (
+        default_active
+        if models_payload is None or models_payload.active is None
+        else models_payload.active
+    )
+    active_models = tuple(dict.fromkeys(raw_active))
+    unsupported_models = tuple(
+        model_name for model_name in active_models if model_name not in supported_models
+    )
+    if unsupported_models:
+        supported = ", ".join(sorted(supported_models))
+        unsupported = ", ".join(unsupported_models)
+        raise PluginConfigurationError(
+            f"{binding.plugin_id} models.active contains unsupported models [{unsupported}]. "
+            f"Supported models: [{supported}]."
+        )
+
+    return ResolvedBindingModels(
+        active=active_models,
+        filter=_load_row_filter(
+            None if models_payload is None else models_payload.filter,
+            plugin_id=binding.plugin_id,
+        ),
+    )
+
+
+def iter_active_model_rows(
+    *,
+    model_name: str,
+    rows: Iterable[RowT],
+    binding_models: ResolvedBindingModels,
+) -> Iterator[RowT]:
+    if model_name not in binding_models.active:
+        return
+
+    for row in rows:
+        if _should_keep_model_row(
+            model_name=model_name,
+            row=row,
+            binding_models=binding_models,
+        ):
+            yield row
+
+
+def _should_keep_model_row(
+    *,
+    model_name: str,
+    row: RowT,
+    binding_models: ResolvedBindingModels,
+) -> bool:
+    row_filter = binding_models.filter
+    if row_filter is None:
+        return True
+
+    return row_filter(model_name, row.model_copy(deep=True))
+
+
+def _load_row_filter(
+    filter_ref: str | None,
+    *,
+    plugin_id: str,
+) -> RowFilter | None:
+    # DEPRECATED + dormant: `models.filter` (base-schemas binding-plan.ts) has no
+    # consumer — no binding sets it, so filter_ref is always None here. The machinery
+    # is retained, not wired for new use; `models.active` owns stream selection.
+    if filter_ref is None:
+        return None
+
+    module_path_raw, separator, attr_name = filter_ref.partition(":")
+    if separator != ":" or not module_path_raw or not attr_name:
+        raise PluginConfigurationError(
+            f"Invalid {plugin_id} models.filter. Expected '<path.py>:<callable>'."
+        )
+
+    module_path = Path(module_path_raw).expanduser()
+    if not module_path.is_absolute():
+        module_path = (Path.cwd() / module_path).resolve()
+    else:
+        module_path = module_path.resolve()
+
+    if not module_path.is_file():
+        raise PluginConfigurationError(
+            f"{plugin_id} models.filter path does not exist: {module_path}"
+        )
+
+    module_name = _filter_module_name(module_path)
+    spec = importlib.util.spec_from_file_location(module_name, module_path)
+    if spec is None or spec.loader is None:
+        raise PluginConfigurationError(
+            f"Unable to load {plugin_id} models.filter module: {module_path}"
+        )
+
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[module_name] = module
+    spec.loader.exec_module(module)
+
+    row_filter = getattr(module, attr_name, None)
+    if not callable(row_filter):
+        raise PluginConfigurationError(
+            f"{plugin_id} models.filter '{filter_ref}' does not resolve to a callable"
+        )
+    return row_filter
+
+
+def _filter_module_name(module_path: Path) -> str:
+    digest = hashlib.sha1(str(module_path).encode("utf-8")).hexdigest()[:12]
+    return f"shared_plugins_binding_filter_{digest}"
+
+
+def _resolve_binding_path(value: object) -> Path:
+    if isinstance(value, Path):
+        path = value
+    elif isinstance(value, str):
+        stripped = value.strip()
+        if not stripped:
+            raise ValueError("Path values must not be empty.")
+        path = Path(os.path.expandvars(stripped)).expanduser()
+    else:
+        raise TypeError(f"Expected path-like value, got {type(value).__name__}")
+
+    return path.resolve(strict=False)

shared_plugins/dlt.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Any
+
+import dlt
+from dagster import AssetExecutionContext
+from dagster_dlt import DagsterDltResource
+from dlt.common.schema import Schema
+from dlt.destinations.sql_client import SqlClientBase
+from base_client import DagsterAllPlanBinding
+
+from .base_platform import BasePlatformClient
+from .naming import dlt_dataset_name, dlt_pipeline_name
+from .resources import DLT_TRANSLATOR
+
+# Side-effect import: patches PostgresClient to emit COMMENT ON COLUMN for
+# dlt column descriptions. It must be active in any process that loads a dlt
+# pipeline into postgres, and every such pipeline is constructed below.
+from . import pg_column_comments as _pg_column_comments  # noqa: F401
+
+DLT_DESTINATION = "postgres"
+
+
+def pre_register_source_schema(pipeline: Any, source: Any) -> None:
+    """Idempotently register an empty Schema for `source.name` on the
+    pipeline. This lets resources call `pipe.sql_client(schema_name=<source>)`
+    on cold start; without it, dlt's `_get_schema_or_create` falls through to
+    `Schema(pipeline_name)`, which raises `InvalidSchemaName` whenever the
+    pipeline_name exceeds dlt's 64-char Schema regex limit. Safe to call on
+    warm runs — `has_schema` short-circuits when the schema is already on
+    disk or restored from destination state."""
+    if not pipeline.schemas.has_schema(source.name):
+        pipeline.schemas.save_schema(Schema(source.name))
+
+
+def resolve_partition_binding(
+    *,
+    context: AssetExecutionContext,
+    base_platform: BasePlatformClient,
+    plugin_id: str,
+) -> DagsterAllPlanBinding:
+    partition_key = context.partition_key
+    if partition_key is None:
+        raise RuntimeError("Missing partition key; expected binding_id partition.")
+
+    return base_platform.get_binding(plugin_id=plugin_id, binding_id=partition_key)
+
+
+def run_dlt_pipeline(
+    *,
+    context: AssetExecutionContext,
+    dlt_resource: DagsterDltResource,
+    source: Any,
+    plugin_id: str,
+    binding_id: str,
+    job_name: str,
+) -> Iterator[Any]:
+    pipeline = dlt.pipeline(
+        pipeline_name=dlt_pipeline_name(plugin_id, binding_id, job_name),
+        destination=DLT_DESTINATION,
+        dataset_name=dlt_dataset_name(plugin_id),
+        progress="log",
+    )
+    pre_register_source_schema(pipeline, source)
+    context.log.info(f"Starting {plugin_id} job={job_name} for binding_id={binding_id}")
+    yield from dlt_resource.run(
+        context=context,
+        dlt_source=source,
+        dlt_pipeline=pipeline,
+        dagster_dlt_translator=DLT_TRANSLATOR,
+    )
+    context.log.info(
+        f"Completed {plugin_id} job={job_name} for binding_id={binding_id}"
+    )
+
+
+def destination_has_table(
+    sql_client: SqlClientBase[Any],
+    table_name: str,
+) -> bool:
+    """Check whether a table exists in the dlt destination dataset."""
+    query = (
+        "SELECT 1 FROM information_schema.tables"
+        " WHERE table_schema = current_schema() AND table_name = %s"
+        " LIMIT 1"
+    )
+    with sql_client.execute_query(query, table_name) as cursor:
+        return cursor.fetchone() is not None

shared_plugins/env.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from sqlalchemy.engine import make_url
+
+CTXB_DATABASE_URL_ENV_VAR = "CTXB_DATABASE_URL"
+CTX_PLATFORM_URL_ENV_VAR = "CTX_PLATFORM_URL"
+CTXB_BASE_ID_ENV_VAR = "CTXB_BASE_ID"
+CTXB_SCRATCH_DIR_ENV_VAR = "CTXB_SCRATCH_DIR"
+
+
+def normalize_required_string(value: object, *, env_var_name: str) -> str:
+    """Coerce a required env-var value to a non-blank, stripped string (raising a
+    typed/loud error tagged with the var name). Shared across the env-settings
+    validators here and ProviderTokenSettings."""
+    if not isinstance(value, str):
+        raise TypeError(f"{env_var_name} must be a string.")
+
+    normalized = value.strip()
+    if not normalized:
+        raise ValueError(f"{env_var_name} cannot be blank.")
+    return normalized
+
+
+def normalize_optional_absolute_path(
+    value: object,
+    *,
+    env_var_name: str,
+) -> Path | None:
+    if value is None:
+        return None
+
+    normalized = normalize_required_string(value, env_var_name=env_var_name)
+    candidate = Path(normalized).expanduser()
+    if not candidate.is_absolute():
+        raise ValueError(f"{env_var_name} must be an absolute path.")
+    return candidate.resolve(strict=False)
+
+
+class SharedPythonSettings(BaseSettings):
+    model_config = SettingsConfigDict(extra="ignore")
+
+    ctx_database_url: str = Field(alias=CTXB_DATABASE_URL_ENV_VAR)
+    ctx_platform_url: str | None = Field(default=None, alias=CTX_PLATFORM_URL_ENV_VAR)
+    ctx_base_id: str | None = Field(default=None, alias=CTXB_BASE_ID_ENV_VAR)
+    ctx_scratch_dir: Path | None = Field(default=None, alias=CTXB_SCRATCH_DIR_ENV_VAR)
+
+    @field_validator("ctx_database_url", mode="before")
+    @classmethod
+    def _validate_database_url(cls, value: object) -> str:
+        normalized = normalize_required_string(
+            value,
+            env_var_name=CTXB_DATABASE_URL_ENV_VAR,
+        )
+        parsed_url = make_url(normalized)
+        if not parsed_url.drivername.startswith("postgres"):
+            raise ValueError(
+                f"{CTXB_DATABASE_URL_ENV_VAR} must use a postgres driver, got '{parsed_url.drivername}'."
+            )
+        if not parsed_url.database:
+            raise ValueError(
+                f"{CTXB_DATABASE_URL_ENV_VAR} must include a database name."
+            )
+        return normalized
+
+    @field_validator("ctx_platform_url", mode="before")
+    @classmethod
+    def _validate_platform_url(cls, value: object) -> str | None:
+        if value is None:
+            return None
+        normalized = normalize_required_string(
+            value,
+            env_var_name=CTX_PLATFORM_URL_ENV_VAR,
+        )
+        if not normalized.startswith(("http://", "https://")):
+            raise ValueError(
+                f"{CTX_PLATFORM_URL_ENV_VAR} must use http:// or https://."
+            )
+        return normalized.rstrip("/")
+
+    @field_validator("ctx_base_id", mode="before")
+    @classmethod
+    def _validate_base_id(cls, value: object) -> str | None:
+        if value is None:
+            return None
+        return normalize_required_string(
+            value,
+            env_var_name=CTXB_BASE_ID_ENV_VAR,
+        )
+
+    @field_validator("ctx_scratch_dir", mode="before")
+    @classmethod
+    def _validate_scratch_dir(cls, value: object) -> Path | None:
+        return normalize_optional_absolute_path(
+            value,
+            env_var_name=CTXB_SCRATCH_DIR_ENV_VAR,
+        )
+
+
+def load_shared_python_settings() -> SharedPythonSettings:
+    return SharedPythonSettings()

shared_plugins/exceptions.py

@@ -0,0 +1,10 @@
+class PluginError(Exception):
+    """Base exception for plugin failures."""
+
+
+class PluginConfigurationError(PluginError):
+    """Raised when plugin configuration is invalid or missing."""
+
+
+class PluginCursorExpiredError(PluginError):
+    """Raised when an incremental cursor is no longer valid and must be reset."""

shared_plugins/google_client/__init__.py

@@ -0,0 +1 @@
+"""Shared Google API client utilities used across plugins."""