app.sources.port

Provider-neutral port between polling and the source adapters.

A SourceAdapter reads the published ref of one source registration. Everything crossing the port is provider-neutral: project id/path, file path, change token, content bytes, source URL, author and ref. Pagination, API formats, scopes and credentials stay inside the adapter module.

Polling drives an adapter in three steps:

  1. SourceAdapter.list_projects() – the in-scope projects with the resolved published ref of each. complete=False means the listing may miss projects; polling then deletes nothing.

  2. SourceAdapter.list_documents() – the ADR files of one project under the registration path with their change tokens. The adapter receives the stored tokens and marks each document changed or not; polling fetches only changed documents. complete=False means files may be missing; polling then deletes nothing in that project.

  3. SourceAdapter.fetch() – the exact bytes of one changed file.

Change tokens are opaque strings chosen by the adapter (for example mtime_ns:size or a blob id). A document reported with changed=False but a token different from the stored one keeps its content; polling only rewrites the stored token. Adapters may use that to carry project-level state (such as a branch head) in the token.

Adapters raise SourceError subclasses for source problems; messages must be actionable and must never contain secrets.

Public API: SourceProject, ProjectListing, SourceDocument, DocumentListing, FetchedDocument, SourceAdapter, SourceError, ConfigErrorCode, SourceConfigError, SourceUnavailableError, SourceAccessError, SourceNotFoundError.

exception app.sources.port.SourceError(message, *, code=None, hint=None, extra=None)

Bases: AdrianoError

A source could not be read; prior content must be preserved.

class app.sources.port.ConfigErrorCode(*values)

Bases: StrEnum

Stable, machine-readable reason why a registration is disabled.

The readable config_error text stays the detailed explanation; the code lets the UI show plain-language copy.

  • invalid_settings – a field of the entry, its type-specific options or its scope failed validation (missing, wrong type, bad URL, unknown key, …).

  • unknown_type – the type is not a known source type.

  • type_unavailable – the type is known but has no adapter in this build.

  • invalid_published_ref – published_ref is not usable for the type.

  • token_env_missing – the env var named by token_env is not set.

  • removed_from_config – the registration is stored but no longer in catalog.yaml.

  • other – any other configuration error.

INVALID_SETTINGS = 'invalid_settings'
UNKNOWN_TYPE = 'unknown_type'
TYPE_UNAVAILABLE = 'type_unavailable'
INVALID_PUBLISHED_REF = 'invalid_published_ref'
TOKEN_ENV_MISSING = 'token_env_missing'
REMOVED_FROM_CONFIG = 'removed_from_config'
OTHER = 'other'
exception app.sources.port.SourceConfigError(message, *, config_code=ConfigErrorCode.OTHER)

Bases: SourceError

Type-specific registration settings are invalid.

Parameters:
exception app.sources.port.SourceUnavailableError(message, *, code=None, hint=None, extra=None)

Bases: SourceError

The source is temporarily unreachable (network, timeout, 5xx).

exception app.sources.port.SourceAccessError(message, *, code=None, hint=None, extra=None)

Bases: SourceError

The source refused access (bad or insufficient credentials).

exception app.sources.port.SourceNotFoundError(message, *, code=None, hint=None, extra=None)

Bases: SourceError

A configured root, project or path does not exist at the source.

class app.sources.port.SourceProject(*, id, path, ref)

Bases: object

One in-scope project (repository or directory) of a registration.

Parameters:

  • id (str) – Adapter-internal stable id (opaque to polling).

  • path (str) – Project path stored as the record project.

  • ref (str) – Resolved published ref polled for this project.

id: str
path: str
ref: str
class app.sources.port.ProjectListing(*, projects, complete=True, problems=())

Bases: object

The in-scope projects of a registration.

Parameters:

  • projects (tuple[SourceProject, ...]) – Projects found, without duplicates.

  • complete (bool) – True only if no in-scope project can be missing (all pages read, no project skipped by an error).

  • problems (tuple[str, ...]) – Actionable descriptions of skipped parts.

projects: tuple[SourceProject, ...]
complete: bool
problems: tuple[str, ...]
class app.sources.port.SourceDocument(*, project, path, change_token, changed=True)

Bases: object

One ADR file found in a project listing.

Parameters:

  • project (SourceProject) – Owning project.

  • path (str) – POSIX file path inside the project (including the registration path prefix).

  • change_token (str | None) – Opaque token that changes when the content may have changed; None if the source offers none.

  • changed (bool) – Whether the content may differ from the content that produced the stored token; polling fetches only these.

project: SourceProject
path: str
change_token: str | None
changed: bool
class app.sources.port.DocumentListing(*, documents, complete=True, problems=())

Bases: object

The ADR files of one project.

Parameters:

  • documents (tuple[SourceDocument, ...]) – Documents found, without duplicate paths.

  • complete (bool) – True only if no file under the registration path can be missing.

  • problems (tuple[str, ...]) – Actionable descriptions of skipped parts.

documents: tuple[SourceDocument, ...]
complete: bool
problems: tuple[str, ...]
class app.sources.port.FetchedDocument(*, content, source_url=None, author=None)

Bases: object

The content of one document.

Parameters:

  • content (bytes) – The exact bytes at the source.

  • source_url (str | None) – Link (or display path) to the file at the source.

  • author (str | None) – Commit author email, if cheaply known.

content: bytes
source_url: str | None
author: str | None
class app.sources.port.SourceAdapter(*args, **kwargs)

Bases: Protocol

Reads the published ref of one source registration.

async list_projects()

List the in-scope projects.

Return type:

ProjectListing

Returns:

The listing.

Raises:

SourceError – If no listing can be produced at all.

async list_documents(project, previous_tokens)

List the ADR files of one project.

Parameters:
Return type:

DocumentListing

Returns:

The listing.

Raises:

SourceError – If the project cannot be listed.

async fetch(document)

Read one document.

Parameters:

document (SourceDocument) – A document from list_documents().

Return type:

FetchedDocument

Returns:

Its content.

Raises:

SourceError – If the document cannot be read.