Add type stubs for punq by abrahammurciano · Pull Request #15274 · python/typeshed

abrahammurciano · 2026-01-13T17:53:11Z

punq is an IOC (Inversion of Control) Container for Python 3.8+

srittau

Thanks, notes below.

srittau · 2026-01-15T09:40:11Z

stubs/punq/punq/__init__.pyi

+    service: type[_T] | str
+    scope: Scope
+    builder: Callable[[], _T]
+    needs: dict[str, object]


Due to the invariance of dict, using object as value type is often problematic. For example, the following won't type check with mypy:

x = {"": "a"} y: dict[str, object] = x # incompatible assignments

The usual pattern here is to use Any.

stubs/punq/punq/__init__.pyi

srittau · 2026-01-15T09:43:40Z

stubs/punq/punq/__init__.pyi

+    needs: dict[str, object]
+    args: dict[str, object]
+
+empty: Any


The standard pattern for this kind of exported sentinel in typeshed is the following:

_Empty = NewType("_Empty", object) # a class at runtime empty: Final[_Empty]

See below for how to use it.

Alternatively, if empty is not supposed to be used by users, I would consider leaving this out.

srittau · 2026-01-15T09:44:45Z

stubs/punq/punq/__init__.pyi

+    def register_concrete_service(self, service: type | str, scope: Scope) -> None: ...
+    def build_context(self, key: type | str, existing: _ResolutionContext | None = None) -> _ResolutionContext: ...
+    def register(
+        self, service: type[_T] | str, factory: Callable[..., _T] = ..., instance: _T = ..., scope: Scope = ..., **kwargs: object


See above for using _Empty. Also, typeshed uses Any instead of object to mark kwargs where the type matters, but can't be represented accurately.

Suggested change

self, service: type[_T] | str, factory: Callable[..., _T] = ..., instance: _T = ..., scope: Scope = ..., **kwargs: object

self, service: type[_T] | str, factory: Callable[..., _T] | _Empty = ..., instance: _T | _Empty = ..., scope: Scope = ..., **kwargs: Any # kwargs are passed to ForwardRef

srittau · 2026-01-15T09:45:55Z

stubs/punq/punq/__init__.pyi

+    def register(self, service: type[_TOpt] | str, *, instance: _TOpt, **kwargs: Any) -> Container: ...
+    @overload
+    def register(
+        self, service: type[_TOpt] | str, factory: Callable[..., _TOpt] = ..., *, scope: Scope = ..., **kwargs: Any


Suggested change

self, service: type[_TOpt] | str, factory: Callable[..., _TOpt] = ..., *, scope: Scope = ..., **kwargs: Any

self, service: type[_TOpt] | str, factory: Callable[..., _TOpt] | _Empty = ..., *, scope: Scope = ..., **kwargs: Any

srittau · 2026-01-15T09:54:51Z

stubs/punq/punq/__init__.pyi

+    def __getitem__(self, key: type | str) -> object: ...
+    def __setitem__(self, key: type | str, value: object) -> None: ...


Suggested change

def __getitem__(self, key: type | str) -> object: ...

def __setitem__(self, key: type | str, value: object) -> None: ...

def __getitem__(self, key: type | str) -> Any: ... # return type depends on the cache entry

def __setitem__(self, key: type | str, value: Any) -> None: ... # value type depends on the cache entry

Updated to type these generically instead of using Any

srittau · 2026-01-15T09:57:03Z

stubs/punq/punq/__init__.pyi

+class Container:
+    registrations: _Registry
+    def __init__(self) -> None: ...
+    @overload


Suggested change

@overload

# kwargs are passed to ForwardRef

@overload

They're actually all eventually passed to builder, which is the main destination of all the kwargs for all the functions. I put a single comment at the top of the Container indicating this for all the functions in that class.

srittau · 2026-01-15T09:57:30Z

stubs/punq/punq/__init__.pyi

+        service: type[_TOpt] | str,
+        factory: Callable[..., _TOpt] = ...,


Suggested change

service: type[_TOpt] | str,

factory: Callable[..., _TOpt] = ...,

service: type[_TOpt] | str | _Empty,

factory: Callable[..., _TOpt] | _Empty = ...,

Service can't be empty, I assume you meant factory and instance?

Sorry, yes.

srittau · 2026-01-15T09:59:52Z

stubs/punq/punq/__init__.pyi

+    def resolve_all(self, service: type[_TOpt] | str, **kwargs: Any) -> list[_TOpt]: ...
+    def resolve(self, service_key: type[_TOpt] | str, **kwargs: Any) -> _TOpt: ...
+    def instantiate(self, service_key: type[_TOpt] | str, **kwargs: Any) -> _TOpt: ...


Maybe something like this for kwargs?

Suggested change

def resolve_all(self, service: type[_TOpt] | str, **kwargs: Any) -> list[_TOpt]: ...

def resolve(self, service_key: type[_TOpt] | str, **kwargs: Any) -> _TOpt: ...

def instantiate(self, service_key: type[_TOpt] | str, **kwargs: Any) -> _TOpt: ...

# All kwargs are passed to the builder.

def resolve_all(self, service: type[_TOpt] | str, **kwargs: Any) -> list[_TOpt]: ...

def resolve(self, service_key: type[_TOpt] | str, **kwargs: Any) -> _TOpt: ...

def instantiate(self, service_key: type[_TOpt] | str, **kwargs: Any) -> _TOpt: ...

srittau · 2026-01-15T10:01:03Z

stubs/punq/punq/__init__.pyi

+class _Registration(NamedTuple, Generic[_T]):
+    service: type[_T] | str
+    scope: Scope
+    builder: Callable[[], _T]


It seems that builder can be called with arbitrary keyword args, so this would be more appropriate:

Suggested change

builder: Callable[[], _T]

builder: Callable[..., _T]

- Replace object with Any where appropriate - Clarify the use of **kwargs in method signatures - Make _T default to Any and use it in more places instead of Any/object - Include _Empty as a default parameter where applicable

github-actions · 2026-01-15T13:05:12Z

According to mypy_primer, this change has no effect on the checked open source code. 🤖🎉

srittau

Thanks! For future reference, please don't force push in typeshed PRs as that makes reviewing changes harder. We squash when merging anyways.

abrahammurciano · 2026-01-15T14:46:10Z

Sure, sorry, and thank you for your help

This comment has been minimized.

Sign in to view

Add type stubs for punq

9059696

punq is an IOC (Inversion of Control) Container for Python 3.8+

abrahammurciano force-pushed the punq branch from a4a0e45 to 9059696 Compare January 13, 2026 18:03

This comment has been minimized.

Sign in to view

srittau requested changes Jan 15, 2026

View reviewed changes

This comment has been minimized.

Sign in to view

abrahammurciano force-pushed the punq branch from c72ad59 to 41a4f31 Compare January 15, 2026 12:34

Improve type hints in punq stubs

d5e71ab

- Replace object with Any where appropriate - Clarify the use of **kwargs in method signatures - Make _T default to Any and use it in more places instead of Any/object - Include _Empty as a default parameter where applicable

abrahammurciano force-pushed the punq branch from 5020a5d to d5e71ab Compare January 15, 2026 12:44

Merge branch 'main' into punq

0134a52

This comment has been minimized.

Sign in to view

[pre-commit.ci] auto fixes from pre-commit.com hooks

7c37421

abrahammurciano force-pushed the punq branch from 7ab6271 to 7c37421 Compare January 15, 2026 12:57

abrahammurciano requested a review from srittau January 15, 2026 13:06

srittau approved these changes Jan 15, 2026

View reviewed changes

srittau merged commit 127e4d2 into python:main Jan 15, 2026
48 checks passed

	self, service: type[_T] \| str, factory: Callable[..., _T] = ..., instance: _T = ..., scope: Scope = ..., **kwargs: object
	self, service: type[_T] \| str, factory: Callable[..., _T] \| _Empty = ..., instance: _T \| _Empty = ..., scope: Scope = ..., **kwargs: Any # kwargs are passed to ForwardRef

	self, service: type[_TOpt] \| str, factory: Callable[..., _TOpt] = ..., , scope: Scope = ..., *kwargs: Any
	self, service: type[_TOpt] \| str, factory: Callable[..., _TOpt] \| _Empty = ..., , scope: Scope = ..., *kwargs: Any

		def __getitem__(self, key: type \| str) -> object: ...
		def __setitem__(self, key: type \| str, value: object) -> None: ...

		service: type[_TOpt] \| str,
		factory: Callable[..., _TOpt] = ...,

Uh oh!

Conversation

abrahammurciano commented Jan 13, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

srittau left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

This comment has been minimized.

github-actions bot commented Jan 15, 2026

Uh oh!

srittau left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

abrahammurciano commented Jan 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants