feat: Support instantiation with multibind #277

eirikur-nc · 2025-07-23T15:06:00Z

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

… instantiated the the injector

…on-generic list/dict

eirikur-nc · 2025-07-28T11:13:29Z

injector/__init__.py

-        :param interface: typing.Dict or typing.List instance to bind to.
-        :param to: Instance, class to bind to, or an explicit :class:`Provider`
-                subclass. Must provide a list or a dictionary, depending on the interface.
+        :param interface: A generic list[T] or dict[str, T] type to bind to.


I decided to use PEP 585 styled type hints. Support for them was introduced in Python 3.9. While this project still supports Python 3.8, I suspect it's only a matter of time until that support gets dropped since 3.8 has reached end-of-life.

I think that's fine.

eirikur-nc · 2025-07-28T11:21:35Z

injector/__init__.py

+            binder.multibind(list[Interface], to=A)
+            binder.multibind(list[Interface], to=[B, C()])
+            injector.get(list[Interface])  # [<A object at 0x1000>, <B object at 0x2000>, <C object at 0x3000>]


I changed these examples to illustrate the use of classes and objects, rather than strings. This improves consistency with the bind documentation.

IMO, people reach for DI libraries to simplify object construction. Injecting strings or other primitive values, while possible, is less beneficial, at least in my experience.

I agree! The current handling of primitive values has always felt like a side effect to me, so removing that from the documentation is fine by me.

codecov · 2025-08-19T11:44:50Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.84%. Comparing base (03ea2e1) to head (90c0ae0).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #277      +/-   ##
==========================================
+ Coverage   95.62%   95.84%   +0.21%     
==========================================
  Files           1        1              
  Lines         572      602      +30     
  Branches       97      103       +6     
==========================================
+ Hits          547      577      +30     
  Misses         19       19              
  Partials        6        6

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

davidparsson · 2025-09-30T18:17:26Z

Thanks for your contribution, and sorry for the slow handling of this. After a quick glance, I think it looks great. I will try to find the time to make a proper review of this and get this merged and released soon.

davidparsson

All good. Thanks!

I think this drops the ability to multibind a list of types, but I'm fine sacrificing that for this. Much appreciated!

davidparsson · 2025-10-01T06:26:54Z

injector/__init__.py

-        :param interface: typing.Dict or typing.List instance to bind to.
-        :param to: Instance, class to bind to, or an explicit :class:`Provider`
-                subclass. Must provide a list or a dictionary, depending on the interface.
+        :param interface: A generic list[T] or dict[str, T] type to bind to.


I think that's fine.

davidparsson · 2025-10-01T06:27:38Z

injector/__init__.py

-        :param interface: typing.Dict or typing.List instance to bind to.
-        :param to: Instance, class to bind to, or an explicit :class:`Provider`
-                subclass. Must provide a list or a dictionary, depending on the interface.
+        :param interface: A generic list[T] or dict[str, T] type to bind to.


Here in the docstring, dict[str, T] is mentioned, but it does not have to be a str, right?

I confirmed this.

davidparsson · 2025-10-03T18:29:04Z

injector/__init__.py

+            binder.multibind(list[Interface], to=A)
+            binder.multibind(list[Interface], to=[B, C()])
+            injector.get(list[Interface])  # [<A object at 0x1000>, <B object at 0x2000>, <C object at 0x3000>]


I agree! The current handling of primitive values has always felt like a side effect to me, so removing that from the documentation is fine by me.

davidparsson · 2025-10-03T19:24:15Z

Now this is merged, but I tried to add a few tests. However, I found that the following did not pass:

def test_scopes_applies_to_multibound_type() -> None:
    class A:
        pass

    def configure(binder: Binder) -> None:
        binder.bind(A, to=A, scope=singleton)
        binder.multibind(List[A], to=A)

    injector = Injector([configure])
    first_list = injector.get(List[A])
    second_list = injector.get(List[A])

    assert first_list[0] is second_list[0]

But I think I would expect it to. What are your thoughts, @eirikur-nc?

davidparsson · 2025-10-04T10:59:22Z

I'd just like to clarify that I still think it's useful in its current form.

eirikur-nc · 2025-10-05T17:51:56Z

Now this is merged, but I tried to add a few tests. However, I found that the following did not pass:

def test_scopes_applies_to_multibound_type() -> None:
    class A:
        pass

    def configure(binder: Binder) -> None:
        binder.bind(A, to=A, scope=singleton)
        binder.multibind(List[A], to=A)

    injector = Injector([configure])
    first_list = injector.get(List[A])
    second_list = injector.get(List[A])

    assert first_list[0] is second_list[0]

But I think I would expect it to. What are your thoughts, @eirikur-nc?

That's a good point. I'll admit, I was just focusing on getting class instantiation to work. I didn't pay much heed to scopes.

The current implementation of mulitibind does take a scope argument, but it applies to the list/map, rather than its elements. This is probably not obvious to the caller of the multibind method, nor is the fact that the first multibind call for a given type is the one that governs the scope. Subsequent calls cannot alter the scope. If I do this

binder.multibind(List[Plugin], to=PluginA, scope=singleton)
binder.multibind(List[Plugin], to=PluginB)

then the list will be a singleton scoped

binder.multibind(List[Plugin], to=PluginA)
binder.multibind(List[Plugin], to=PluginB, scope=singleton)

then the list will not be scoped.

So I guess there are a few questions that need to be considered

Should it be possible to scope the list/map?
- If so, what should the API for that look like? IMO, that calls for two separate methods, one for declaring the scope of the list/map type and another to add bindings to it.
Should the scope argument of multibind be repurposed to apply to the element(s) being added, or should it be removed?
If a type is scoped (bind(A, to=A, scope=singleton)), then later multibound without a scope (multibind(List[A], A)), should [inj.get(A)] is inj.get(List[A]) be true?

eirikur-nc · 2025-10-05T20:09:11Z

I've given this some more thought and I think the sensible thing is to mimic the behavior of Guice, since this library is inspired by its design.

Judging from the Guice documentation, it seems like

It's not possible to scope the actual container (list/map).
When adding a binding to a multi-binder, the scope pertains to the bound element (target) within that multi-binder (and that multi-binder alone).
If a type has been bound with a particular scope, and is then bound to a multi-bind container, then the scope should also apply within the multi-bind container.

In other words, the answers to my previous questions are

Q: Should it be possible to scope the list/map?
A: No

Q: Should the scope argument of multibind be repurposed to apply to the element(s) being added, or should it be removed?
A: It should be repurposed to apply to the element(s) being added

Q: If a type is scoped (bind(A, to=A, scope=singleton)), then later multibound without a scope (multibind(List[A], A)), should [inj.get(A)] is inj.get(List[A]) be true?
A: Yes

Would you agree @davidparsson ?

To take this forward, we should probably start by writing up an issue. I wouldn't mind taking a stab at this, but I can't really promise when I'll be able to.

davidparsson · 2025-10-05T20:18:12Z

I totally agree. All three points seem reasonable and intuitive to me.

I've opened #283, and I'll drop a line there before I start working on it. I think I'm open to releasing this without that, but having the support in place would be ideal.

davidparsson · 2025-10-05T20:18:56Z

And by the way, thanks for your thoughts and research. Much appreciated!

davidparsson · 2025-10-06T06:42:03Z

I kept thinking about this, and I like most aspects of it. One thing I'm not sure of is whether scopes applied to multibound types should apply to the type globally or not. If you're interrested in continuing the discussion, I think we should continue in #283.

eirikur-nc added 5 commits July 23, 2025 12:17

Make it possible to register types with multibind, which will then be…

39dda31

… instantiated the the injector

Augment tests with callable providers

320f23b

Raise a more helpful error if an attempt is made to multi-bind to a n…

59dc6a5

…on-generic list/dict

refactor a bit

4bc95be

Update documentation for multibind

d469f2a

eirikur-nc commented Jul 28, 2025

View reviewed changes

test callable provider for dict multibind as well

ae199e6

eirikur-nc marked this pull request as ready for review July 28, 2025 11:32

eirikur-nc added 3 commits July 28, 2025 15:43

Add newlines to avoid horizontal scrolling in docs

7a0b3de

rewrite to work around mypy quirk

93bbd4a

format

cc4b8d0

Merge branch 'master' into multibind-for-plugins

2b88182

bveldhoen mentioned this pull request Sep 30, 2025

How to implement a plug-in system with multibind? #121

Closed

davidparsson approved these changes Oct 3, 2025

View reviewed changes

Merge branch 'master' into multibind-for-plugins

90c0ae0

davidparsson merged commit 5a30e9a into python-injector:master Oct 3, 2025
13 checks passed

davidparsson mentioned this pull request Oct 6, 2025

Support scopes for multibind types #283

Open

davidparsson mentioned this pull request Oct 11, 2025

Add multibind class provider #197

Closed

feat: Support instantiation with multibind #277

feat: Support instantiation with multibind #277

Uh oh!

Conversation

eirikur-nc commented Jul 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Example:

Why

Prior work

Uh oh!

eirikur-nc Jul 28, 2025

Choose a reason for hiding this comment

Uh oh!

davidparsson Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

eirikur-nc Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidparsson Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

davidparsson commented Sep 30, 2025

Uh oh!

davidparsson left a comment

Choose a reason for hiding this comment

Uh oh!

davidparsson Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

davidparsson Oct 1, 2025

Choose a reason for hiding this comment

Uh oh!

davidparsson Oct 3, 2025

Choose a reason for hiding this comment

Uh oh!

davidparsson Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

davidparsson commented Oct 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davidparsson commented Oct 4, 2025

Uh oh!

eirikur-nc commented Oct 5, 2025

Uh oh!

eirikur-nc commented Oct 5, 2025

Uh oh!

davidparsson commented Oct 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davidparsson commented Oct 5, 2025

Uh oh!

davidparsson commented Oct 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

eirikur-nc commented Jul 23, 2025 •

edited

Loading

eirikur-nc Jul 28, 2025 •

edited

Loading

davidparsson Oct 3, 2025 •

edited

Loading

codecov bot commented Aug 19, 2025 •

edited

Loading

davidparsson Oct 3, 2025 •

edited

Loading

davidparsson commented Oct 3, 2025 •

edited

Loading

davidparsson commented Oct 5, 2025 •

edited

Loading

davidparsson commented Oct 6, 2025 •

edited

Loading