fairseq2.dependency

This module contains the lightweight dependency injection API of the library. See Design Philosophy to learn more.

ABCs

DependencyContainer, DependencyResolver

Classes

StandardDependencyContainer

Protocols

DependencyFactory

Exceptions

DependencyError, DependencyNotFoundError

Functions

get_container()

ABCs

class fairseq2.dependency.DependencyContainer[source]

Bases: DependencyResolver

Holds a dependency graph.

abstract register(kls, sub_kls=None, key=None)[source]

Registers a lazily-initialized object of type T.

The __init__() method of kls, or if not None, sub_kls must have type annotations for all its parameters in order for dependency injection to work.

If multiple objects of type T, optionally with the same key, are registered, resolve() will return only the last registered one.

Parameters:

  • kls (type[T]) – The value of T.

  • sub_kls (type[T] | None) – The real type of the object. If not None, must be a subclass of kls.

  • key (str | None) – If not None, registers the object with the specified key. resolve() will return the object only if the same key is provided.

Raises:

  • ValueError – when sub_kls is not a subclass of kls.

  • RuntimeError – when called after the container is already used to resolve an object.

abstract register_factory(kls, factory, key=None)[source]

Registers a lazily-initialized object of type T.

If multiple objects of type T, optionally with the same key, are registered, resolve() will return only the last registered one.

Parameters:

  • kls (type[T]) – The value of T.

  • factory (DependencyFactory[T]) – A callable to create an object of type T. If the callable returns None, the object is considered to not exist.

  • key (str | None) – If not None, registers the object with the specified key. resolve() will return the object only if the same key is provided.

Raises:

RuntimeError – when called after the container is already used to resolve an object.

abstract register_instance(kls, obj, key=None)[source]

Registers an object of type T.

Other than registering an existing object instead of a factory, the method behaves the same as register().

Parameters:

  • kls (type[T]) – The value of T.

  • obj (T) – The object to register.

  • key (str | None) – If not None, registers the object with the specified key. resolve() will return the object only if the same key is provided.

Raises:

RuntimeError – when called after the container is already used to resolve an object.

class fairseq2.dependency.DependencyResolver[source]

Bases: ABC

Resolves objects contained in a dependency graph.

abstract resolve(kls, key=None)[source]

Returns the object of type T.

Parameters:

  • kls (type[T]) – The value of T.

  • key (str | None) – If not None, the object with the specified key will be returned.

Raises:

  • DependencyError – when the dependencies of the object cannot be inferred due to invalid or missing type annotations.

  • DependencyNotFoundError – when the object or one of its dependencies cannot be found.

Returns:

The resolved object.

Return type:

T

abstract resolve_optional(kls, key=None)[source]

Returns the object of type T similar to resolve(), but returns None instead of raising a DependencyNotFoundError if the object is not found.

Parameters:

  • kls (type[T]) – The value of T.

  • key (str | None) – If not None, the object with the specified key will be returned.

Returns:

The resolved object, or None if the object is not found.

Return type:

T | None

abstract resolve_all(kls)[source]

Returns all non-keyed objects of type T.

If multiple objects of type T are registered, resolve() returns only the last registered one. In contrast, resolve_all returns them all in the order they were registered.

Parameters:

kls (type[T]) – The value of T.

Returns:

An iterable of resolved objects. If no object is found, an empty iterable.

Return type:

Iterable[T]

abstract resolve_all_keyed(kls)[source]

Returns all keyed objects of type T.

This method behaves similar to resolve_all(), but returns an iterable of key-object pairs instead.

Parameters:

kls (type[T]) – The value of T.

Returns:

An iterable of resolved key-object pairs. If no object is found, an empty iterable.

Return type:

Iterable[tuple[str, T]]

Classes

final class fairseq2.dependency.StandardDependencyContainer[source]

Bases: DependencyContainer

This is the standard implementation of DependencyContainer and transitively of DependencyResolver.

register(kls, sub_kls=None, key=None)[source]

Registers a lazily-initialized object of type T.

The __init__() method of kls, or if not None, sub_kls must have type annotations for all its parameters in order for dependency injection to work.

If multiple objects of type T, optionally with the same key, are registered, resolve() will return only the last registered one.

Parameters:

  • kls (type[T]) – The value of T.

  • sub_kls (type[T] | None) – The real type of the object. If not None, must be a subclass of kls.

  • key (str | None) – If not None, registers the object with the specified key. resolve() will return the object only if the same key is provided.

Raises:

  • ValueError – when sub_kls is not a subclass of kls.

  • RuntimeError – when called after the container is already used to resolve an object.

register_factory(kls, factory, key=None)[source]

Registers a lazily-initialized object of type T.

If multiple objects of type T, optionally with the same key, are registered, resolve() will return only the last registered one.

Parameters:

  • kls (type[T]) – The value of T.

  • factory (DependencyFactory[T]) – A callable to create an object of type T. If the callable returns None, the object is considered to not exist.

  • key (str | None) – If not None, registers the object with the specified key. resolve() will return the object only if the same key is provided.

Raises:

RuntimeError – when called after the container is already used to resolve an object.

register_instance(kls, obj, key=None)[source]

Registers an object of type T.

Other than registering an existing object instead of a factory, the method behaves the same as register().

Parameters:

  • kls (type[T]) – The value of T.

  • obj (T) – The object to register.

  • key (str | None) – If not None, registers the object with the specified key. resolve() will return the object only if the same key is provided.

Raises:

RuntimeError – when called after the container is already used to resolve an object.

resolve(kls, key=None)[source]

Returns the object of type T.

Parameters:

  • kls (type[T]) – The value of T.

  • key (str | None) – If not None, the object with the specified key will be returned.

Raises:

  • DependencyError – when the dependencies of the object cannot be inferred due to invalid or missing type annotations.

  • DependencyNotFoundError – when the object or one of its dependencies cannot be found.

Returns:

The resolved object.

Return type:

T

resolve_optional(kls, key=None)[source]

Returns the object of type T similar to resolve(), but returns None instead of raising a DependencyNotFoundError if the object is not found.

Parameters:

  • kls (type[T]) – The value of T.

  • key (str | None) – If not None, the object with the specified key will be returned.

Returns:

The resolved object, or None if the object is not found.

Return type:

T | None

resolve_all(kls)[source]

Returns all non-keyed objects of type T.

If multiple objects of type T are registered, resolve() returns only the last registered one. In contrast, resolve_all returns them all in the order they were registered.

Parameters:

kls (type[T]) – The value of T.

Returns:

An iterable of resolved objects. If no object is found, an empty iterable.

Return type:

Iterable[T]

resolve_all_keyed(kls)[source]

Returns all keyed objects of type T.

This method behaves similar to resolve_all(), but returns an iterable of key-object pairs instead.

Parameters:

kls (type[T]) – The value of T.

Returns:

An iterable of resolved key-object pairs. If no object is found, an empty iterable.

Return type:

Iterable[tuple[str, T]]

Protocols

class fairseq2.dependency.DependencyFactory[source]

Bases: Protocol[T_co]

Used by DependencyContainer.register() for its factory parameter.

__call__(resolver)[source]

Creates an object of type T_co.

Parameters:

resolver (DependencyResolver) – The dependency resolver that the callable can use to resolve the dependencies of the newly-created object.

Returns:

An object of type T_co that will be registered in the calling DependencyContainer, or None if the object cannot be created.

Return type:

T_co | None

Exceptions

class fairseq2.dependency.DependencyError[source]

Bases: RuntimeError

Raised when an error occurs while resolving a dependency.

class fairseq2.dependency.DependencyNotFoundError[source]

Bases: DependencyError

Raised when a dependency cannot be found.

Functions

fairseq2.dependency.get_container()[source]

Returns the global DependencyContainer instance.

Raises:

RuntimeError – when setup_fairseq2() has not been called first which is responsible for initializing the global container.

Return type:

DependencyContainer