typing-unknown

Unknown: The missing member of Python's typing module

pip install typing-unknown

Use Unknown as a drop-in (but more strict) replacement for object in type hints.

from typing_unknown import Unknown

def handle_thing(obj: Unknown):
    # Caller may pass any value, but we're limited in how we can use it.

Why Unknown?

Historically, object has served the implicit role of "Unknown" in type hints, preferred over typing.Any when you wish to limit how a value may be used before checking its type.

But, object isn't as strict as you'd think. For example, static type checkers consider the following code valid (no type issues):

def handle_unknown_thing(obj: object | MyType, *args: float):
    if obj:
        obj_class = type(obj)
        instance = obj_class(*args)

But, this code could be invalid. In multiple ways. Even if obj were of a valid, compatible subtype of object, with no hidden or unusual behavior.

To static type checkers, Unknown more accurately reflects what can and cannot be done with an arbitrary, valid object.

Same code, after swapping object for Unknown:

def handle_unknown_thing(obj: Unknown | MyType, *args: float):
    if obj: # PYRIGHT ERROR: Invalid conditional operand
        obj_class = type(obj)
        instance = obj_class(*args) # PYRIGHT ERROR: reportArgumentType

Perfect. This forces us to safely narrow the type of obj (or explicitly suppress the issues):

# Pyright errors are gone. Code is "safe" now.

def handle_unknown_thing(obj: Unknown | MyType, *args: float):
    if obj is not None and isinstance(obj, MyType):
        obj_class = type(obj)
        instance = obj_class(*args)