app.sources.registry

Source type registry: type name -> settings validator / adapter factory.

The catalog configuration loader (app.catalog_config) validates the common registration fields and hands everything type-specific to SourceTypeRegistry.validate(). The validator registered for the type checks the type-specific settings at the adapter boundary and returns a SourceBinding: a factory that opens the adapter for a poll, plus the scope check used by push intake. Invalid settings raise SourceConfigError; the registration is then disabled with that message, the rest of the catalog keeps working.

Adapter modules plug in at default_registry() (the only place that names concrete adapters). A type listed in SUPPORTED_TYPES but not registered yet yields a readable “not available” error instead of a crash; an unknown type yields an “unknown source type” error.

Validator contract (implemented by app.sources.filesystem and app.sources.gitlab):

def validate_settings(
    settings: SourceSettings, env: Mapping[str, str]
) -> SourceBinding: ...

• read type-specific keys from settings.options (and the scope from settings.scope), typically with parse_options();

• resolve secrets from env by the configured env var name; never put a secret value in an error message or in a log line;

• resolve relative paths against settings.base_dir (the directory of catalog.yaml);

• do not perform I/O; open clients only inside open_adapter.

Public API: SUPPORTED_TYPES, SourceSettings, AdapterOpener, SourceBinding, SourceTypeValidator, SourceTypeRegistry, parse_options(), default_registry().

app.sources.registry.SUPPORTED_TYPES = ('filesystem', 'gitlab')

Source types supported by the catalog.

class app.sources.registry.SourceSettings(*, id, type, path, published_ref, scope, options, base_dir)

Bases: object

Validated common settings of one registration plus raw extras.

Parameters:

• id (str) – Registration id.

• type (str) – Source type name.

• path (str) – ADR path inside each project.

• published_ref (str) – Configured published ref (adapter-specific meaning, e.g. "@project-default" for GitLab).

• scope (Mapping[str, JsonValue]) – Raw scope mapping; its shape is type-specific.

• options (Mapping[str, JsonValue]) – All other, type-specific keys (e.g. root, base_url, token_env).

• base_dir (Path) – Directory of the configuration file, for resolving relative paths.

id: str

type: str

path: str

published_ref: str

scope: Mapping[str, JsonValue]

options: Mapping[str, JsonValue]

base_dir: Path

type app.sources.registry.AdapterOpener = Callable[[], AbstractAsyncContextManager[SourceAdapter]]

Opens an adapter for the duration of one poll (async with).

class app.sources.registry.SourceBinding(open_adapter, in_scope=<function _whole_scope>)

Bases: object

A validated registration, ready to open its adapter.

Parameters:

• open_adapter (AdapterOpener) – Opens the adapter for one poll.

• in_scope (Callable[[str], bool]) – Tells whether a project path is within the registration scope (used by push intake, which never calls the adapter).

open_adapter: AdapterOpener

in_scope: Callable[[str], bool]

class app.sources.registry.SourceTypeValidator(*args, **kwargs)

Bases: Protocol

Validates type-specific settings and binds the adapter factory.

class app.sources.registry.SourceTypeRegistry(validators=None, *, pending=())

Bases: object

Maps source type names to their validators.

Parameters:

• validators (Mapping[str, SourceTypeValidator] | None) – Initially registered validators by type name.

• pending (Collection[str]) – Known type names whose adapter is not available.

register(name, validator)

Register (or replace) the validator of a source type.

Parameters:

• name (str) – Type name as written in catalog.yaml.

• validator (SourceTypeValidator) – The validator.

Return type:

None

property available: tuple[str, ...]

Type names with a registered adapter.

Returns:

Sorted names.

validate(settings, env)

Validate one registration with the validator of its type.

Parameters:

• settings (SourceSettings) – Common settings plus type-specific options.

• env (Mapping[str, str]) – Environment used to resolve secret env var names.

Return type:

SourceBinding

Returns:

The binding.

Raises:

SourceConfigError – If the type is unknown or unavailable, or its settings are invalid.

app.sources.registry.parse_options[M: BaseModel](model, data, *, prefix='')

Validate type-specific settings with a pydantic model.

Parameters:

• model (type[M]) – Model describing the settings (use extra="forbid").

• data (Mapping[str, JsonValue]) – Raw settings.

• prefix (str) – Location prefix for messages (e.g. "scope").

Return type:

M

Returns:

The validated model.

Raises:

SourceConfigError – With a readable, secret-free message.

app.sources.registry.default_registry(*, ssl_context=None)

Build the registry of the Phase 1 source types.

Adapter hook: each adapter module registers its validator here. The adapter imports are local to this function because those modules import back from this one (SourceBinding, SourceSettings, parse_options); importing them at module level would be a circular import.

Parameters:

ssl_context (SSLContext | None) – TLS context of network adapters (see app.tls); None uses the default outbound context.

Return type:

SourceTypeRegistry

Returns:

The registry.