What

Make it possible to multibind to types/classes which then get instantiated when injector.get(<MultiBoundType>) is called. Support this both for lists and dictionaries. Update the multibind documentation accordingly.

Example:

def configure(binder: Binder):
    binder.multibind(List[Plugin], to=PluginA)
    binder.multibind(List[Plugin], to=[PluginB, PluginC()])

injector = Injector([configure])
plugins = injector.get(List[Plugin])
assert len(plugins) == 3
assert isinstance(plugins[0], PluginA)
assert isinstance(plugins[1], PluginB)
assert isinstance(plugins[2], PluginC)

Why

In modular software systems, it's often convenient to leverage plug-in patterns to allow a particular module to hook into certain events. The Guice documentation explains this nicely.

Personally, I have used this pattern for lifecycle listeners that get invoked whenever an application starts up and shuts down. Imagine that you have an application that supports different database back-ends and key-value stores. In such a scenario, we typically have separate DI modules for each database system and each key-value store, e.g.

class MySQLModule(Module):
    ...

class PostgreSQLModule(Module):
    ...

class RedisModule(Module):
    ...
  
class InMemoryCacheModule(Module):
    ...

The injector is then configured using the appropriate set of modules, depending on which database and cache we want to employ, e.g. injector = Injector([PostgreSQLModule, RedisModule]).

Each of these modules can optionally register a lifecycle listener. Here's an example for a listener that closes the connection to redis on shutdown.

class RedisLifecycleListener(LifecycleListener):
    @inject
    def __init__(self, redis: Redis):
        self._redis = redis

    @override
    async def on_startup(self):
        pass

    @override
    async def on_shutdown(self):
        await self._redis.aclose()


class RedisModule(Module):
    def configure(self, binder):
        binder.multibind(list[LifecycleListener], RedisLifecycleListener)

The application code then simply asks for all lifecycle listeners and invokes them on startup and shutdown. Here's an example of a FastAPI lifespan that does this

@asynccontextmanager
async def lifespan(app: FastAPI):
    lifecycle_listeners = injector.get(list[LifecycleListener])
    for listener in lifecycle_listeners:
        await listener.on_startup()

    yield

    for listener in reversed(lifecycle_listeners):
        await listener.on_shutdown()

app = FastAPI(
    title="My API",
    lifespan=lifespan,
)

According to @alecthomas (see #121 (comment)) it was always the intention to support this behavior but up until now, users have had to employ workarounds to get this working.

Prior work

This is similar to #197 in that it solves the problem of multibinding to types. However, the API is quite different.
In #197 the proposal is to multibind to a MultiClassProvider like so

# PR 197
binder.multibind(List[A], to=MultiBindClassProvider([A, B]))

The implementation in this PR foregoes the need for a special wrapper, allowing one to mix and match classes and instances like so

# this PR
binder.multibind(List[Plugin], to=[PluginB, PluginC()])

Moreover, this PR also supports binding to classes without nesting them in lists

# this PR
binder.multibind(List[Plugin], to=PluginA)

It also supports dictionary multibindings

# this PR
def configure(binder: Binder):
    binder.multibind(Dict[str, Plugin], to={'a': PluginA})
    binder.multibind(Dict[str, Plugin], to={'b': PluginB, 'c': PluginC()})

Closes #121