Declarative discovery

provider

provider(target: type[T]) -> Provider[T]

provider(
    target: Callable[P, Generator[T, None, None]],
) -> Provider[T]

provider(
    target: Callable[P, AsyncGenerator[T, None]],
) -> Provider[T]

provider(
    target: Callable[P, AbstractContextManager[T]],
) -> Provider[T]

provider(
    target: Callable[P, AbstractAsyncContextManager[T]],
) -> Provider[T]

provider(target: Callable[P, Awaitable[T]]) -> Provider[T]

provider(target: Callable[P, T]) -> Provider[T]

provider(
    target: type[object] | Callable[..., object],
) -> Provider[object]

Capture one provider target without wrapping or replacing its identity.

Declaration records only the explicit target and its source location. It performs no scanning, condition evaluation, provider analysis, or import.

Parameters:

Name	Type	Description	Default
target	type[object] | Callable[..., object]	Class or factory to declare.	required

Returns:

Type	Description
Provider[object]	An immutable declaration ready for optional Provider.configure() and
Provider[object]	inclusion in its owning module's Catalog.

Raises:

Type	Description
InvalidProviderError	The target is neither a class nor callable, or the declaration module cannot be determined.

Example

>>> from depin import Provider, provider
>>> class Service: ...
>>> declaration = provider(Service)
>>> isinstance(declaration, Provider)
True

Provider dataclass

An immutable declaration created only by provider().

The declaration retains the exact target identity and its declaration-site ownership. Calling Provider(...) directly is invalid; use provider(target) so depin can capture that provenance.

Raises:

Type	Description
InvalidProviderError	The class is constructed directly instead of through provider().

Example

>>> from depin import Provider, provider
>>> class Service: ...
>>> declaration = provider(Service)
>>> isinstance(declaration, Provider)
True

configure

configure(
    *,
    scope: Scope = Scope.SINGLETON,
    provides: ProviderKey | None = None,
    tag: str | None = None,
    when: Condition | None = None,
    check: Callable[[U], object] | None = None,
) -> Provider[U]

Return a new declaration whose metadata replaces the current metadata.

Omitted arguments reset to their defaults. Conditions and health checks are stored without being evaluated; Container.freeze() evaluates the condition, and the frozen container runs the check.

Parameters:

Name	Type	Description	Default
scope	Scope	Lifetime to apply to the produced value.	SINGLETON
provides	ProviderKey | None	Explicit key, replacing inference from the target.	None
tag	str | None	Disambiguator for other providers under the same key.	None
when	Condition | None	Condition deciding whether the binding enters the plan.	None
check	Callable[[U], object] | None	Health check associated with the produced value.	None

Returns:

Type	Description
Provider[U]	A new immutable declaration retaining the original target and
Provider[U]	declaration location.

Raises:

Type	Description
InvalidProviderError	Any metadata value violates its contract.

Example

>>> from depin import Scope, provider
>>> class Service: ...
>>> base = provider(Service)
>>> configured = base.configure(scope=Scope.TRANSIENT, tag='worker')
>>> configured is base
False

Catalog dataclass

An immutable ordered declaration snapshot kept by its owning module.

A catalogue records only local Provider declarations. It is not a Bindings source: composition roots explicitly place completed catalogues inside a Manifest before ingestion.

Raises:

Type	Description
InvalidProviderError	The owner is not the caller, a member is not a declaration, or a declaration belongs to another module.

Example

>>> from depin import Catalog, provider
>>> class Service: ...
>>> declaration = provider(Service)
>>> providers = Catalog(__name__, declaration)
>>> providers.providers == (declaration,)
True

__init__

__init__(
    module: str, /, *providers: _ProviderInput
) -> None

Create the completed snapshot for its owning module.

Parameters:

Name	Type	Description	Default
module	str	The caller's module name, conventionally __name__.	required
*providers	_ProviderInput	Local declarations in their desired lexical order.	()

Raises:

Type	Description
InvalidProviderError	The owner is not the caller, a member is not a declaration, or a declaration belongs to another module.

Example

>>> from depin import Catalog, provider
>>> class Service: ...
>>> declaration = provider(Service)
>>> providers = Catalog(__name__, declaration)
>>> providers.providers == (declaration,)
True

Manifest dataclass

An immutable ordered composition of catalogues and nested manifests.

A manifest is the explicit discovery boundary and satisfies Bindings. Sources flatten left-to-right; repeated occurrences remain repeated. No package scan, name search, or de-duplication occurs.

Raises:

Type	Description
InvalidProviderError	The owner is not the caller or a source is not a completed Catalog or Manifest.

Example

>>> from depin import Catalog, Manifest, provider
>>> class Service: ...
>>> providers = Catalog(__name__, provider(Service))
>>> manifest = Manifest(__name__, providers)
>>> manifest.sources == (providers,)
True

__init__

__init__(
    module: str, /, *sources: Catalog | Manifest
) -> None

Create an explicit composition snapshot.

Parameters:

Name	Type	Description	Default
module	str	The caller's module name, conventionally __name__.	required
*sources	Catalog | Manifest	Completed catalogues or manifests in ingestion order.	()

Raises:

Type	Description
InvalidProviderError	The owner is not the caller or a source is not a completed Catalog or Manifest.

Example

>>> from depin import Catalog, Manifest, provider
>>> class Service: ...
>>> providers = Catalog(__name__, provider(Service))
>>> manifest = Manifest(__name__, providers)
>>> manifest.sources == (providers,)
True

records

records() -> Iterable[BindRecord]

Flatten every occurrence into one complete record tuple.

Staging preserves lexical order and every repetition, then discards discovery provenance. Conditions and checks are copied but not run.

Returns:

Type	Description
Iterable[BindRecord]	Ordinary records ready for one atomic collector append.

Raises:

Type	Description
InvalidProviderError	A forged or otherwise malformed snapshot is detected before any tuple is returned.

Example

>>> from depin import Catalog, Manifest, provider
>>> class Service: ...
>>> providers = Catalog(__name__, provider(Service))
>>> leaf = Manifest(__name__, providers)
>>> records = Manifest(__name__, leaf, leaf).records()
>>> [record.source for record in records] == [Service, Service]
True