What is the proper type annotation for any object that can be unpacked with the ** operator?

I have a function that looks like this:

from pandas import Series
def my_function(unpackable: dict | Series) -> None:
    {**unpackable}

I would actually like to type hint for any object that can be unpacked with the ** operator while excluding those that cannot. I thought about typing.Mapping, but it appears isinstance(Series({"a": 1}), Mapping) is False.

What is the proper type hint for any object that can be unpacked with the ** operator in Python?

TL;DR

In most cases collections.abc.Mapping[K, V] will be just fine.

The widest possible valid annotation is a (generic) protocol implementing the __getitem__ and keys methods:

from collections.abc import Iterable, Hashable
from typing import Protocol, TypeVar

K = TypeVar("K", bound=Hashable)
V = TypeVar("V", covariant=True)


class DoubleStarUnpackable(Protocol[K, V]):
    def keys(self) -> Iterable[K]: ...
    def __getitem__(self, key: K, /) -> V: ...

Digging deeper

This topic is not as straightforward as you might think at first glance. To find out what an appropriate type annotation for "unpackable" objects is, we need to dig into a few different sources.

What do you actually need for unpacking?

Since PEP 448 the unpacking operators * and ** can be used in multiple different circumstances. The restriction on the ** operand type is explicitly mentioned in the official Expressions documentation:

> A double asterisk ** denotes dictionary unpacking. Its operand must be a mapping.

The term mapping is further defined as a

> container object that supports arbitrary key lookups and implements the methods specified in [...] collections.abc.Mapping [...].

To see what the specific methods of a collections ABC are, I find it most helpful to check this table.

But what may be surprising (at least it was for me), is that not all of those are actually necessary for unpacking to work at runtime.¹ By doing a bit of experimentation, we can see which methods are necessary. It turns out that all you need is a __getitem__ and a keys implementation.

Minimal example:

class Foo:
    def __getitem__(self, item: str) -> int:
        if item != "a":
            raise KeyError
        return 1

    def keys(self) -> str:
        return "a"

Demo:

def f(a: int) -> None:
    print(f"{a=}")


f(**Foo())

print({**Foo()})

Output:

a=1
{'a': 1}

You will notice that this also passes mypy --strict without errors.

But as soon as you remove either of those two methods, you will get an error both from mypy and at runtime.

So how do we annotate it?

It turns out that the good people at python/typeshed are also aware of this (no surprise here) and have defined a protocol for just that and called it SupportsKeysAndGetItem:

from collections.abc import Iterable
from typing import Protocol, TypeVar

_KT = TypeVar("_KT")
_VT_co = TypeVar("_VT_co", covariant=True)


class SupportsKeysAndGetItem(Protocol[_KT, _VT_co]):
    def keys(self) -> Iterable[_KT]: ...
    def __getitem__(self, __key: _KT) -> _VT_co: ...

This obviously works just fine with our silly Foo class and we can use it to annotate your function like this:

def my_function(unpackable: SupportsKeysAndGetItem[str, int]) -> None:
    unpacked = {**unpackable}
    print(f"{unpacked=}")


my_function(Foo())  # unpacked={'a': 1}

Again, mypy accepts this code without errors.

We can actually see that mypy uses this exact protocol from the typeshed to check, if something is "unpackable" or not. If we omit either the keys or the __getitem__ method from Foo and try to do {**Foo()}, the error message from mypy will tell us:

List item 0 has incompatible type "Foo"; expected "SupportsKeysAndGetItem[<nothing>, <nothing>]"

(Not sure what lists have to do with this, but the relevant bit here is that it tells us it expects something that implements the SupportsKeysAndGetItem protocol.)

Why not just use Mapping?

You could do that of course and in most situations that is just fine and is exactly how I would annotate something that is supposed to be unpacked at some point. But there are still two relevant caveats to keep in mind.

Mapping is not a protocol!

Unlike other collections abstract base classes such as Iterable, Container or Reversible, the collections.abc.Mapping class ist not actually a protocol. The classes that are protocols are all listed here in PEP 544 as well as here in the mypy documentation.

The consequence is that structural subtyping will not work.

Even if I wrote a class Foo that implements all the Mapping methods (i.e. __getitem__, __iter__, __len__, as well as the inherited __contains__, keys, items, values, get, __eq__, and __ne__), a type checker will still complain, if I tried to do m: Mapping = Foo().

Only nominal subtyping (i.e. inheriting from Mapping) would make this work. Here is another Stack Overflow question about this exact topic.

pandas.Series is unpackable, but not a Mapping subtype

Since you brought up the Series class in your question, I am using it here as a stand-in for any class that you could use for unpacking.

Annotating your function like this would not allow a Series argument to be passed:

from collections.abc import Mapping

def my_function(unpackable: Mapping) -> None: ...

For example mypy would complain, if you did my_function(pd.Series()):

Argument 1 to "my_function" has incompatible type "Series[Any]"; expected "Mapping[Any, Any]"

So you would have to resort to specifically defining a union for the annotation, like Anton Petrov suggested in his answer.

But then what if someone would like to pass something that is neither a Mapping subclass, nor a pd.Series, but still unpackable?

This is basically the argument for making your function parameter type annotations as wide as possible.

Footnotes

¹ At least in the current CPython implementation. I could not find specific documentation for this.

The only requirement for the unpackable type is to follow the Mapping protocol, but it doesn't mean it should be inherited from Mapping.

So Mapping should be enough in most cases, but if you want to be more descriptive, and considering you care about Series specifically, you could create Unpackable alias:

Unpackable = Union[Mapping, Series]

<s>But, actually, mypy will be happy if you provide Series for the Mapping type, so it's just a matter of what seems more readable to you.</s>