Type-hinting parameters with a sentinel value as the default

Question

I currently use this strategy when I cannot assign default arguments in a function's signature and/or None already has meaning.

from typing import Optional

DEFAULT = object()


# `None` already has meaning.
def spam(ham: Optional[list[str]] = DEFAULT):
    if ham is DEFAULT:
        ham = ['prosciutto', 'jamon']
    if ham is None:
        print('Eggs?')
    else:
        print(str(len(ham)) + ' ham(s).')

Error:

Failed (exit code: 1) (2607 ms)

main.py:7: error: Incompatible default for argument "ham" (default has type "object", argument has type "Optional[List[str]]")
Found 1 error in 1 file (checked 1 source file)

• How do I type-hint ham without getting errors in mypy? or
• What strategy should I use instead of DEFAULT = object()?

Answer 1

As I commented, this is an active area of development in Python. PEP 661 proposes to add a sentinel function that creates a sentinel object, but until that PEP is approved, you're on your own.

You can take inspiration from some of the proposed (or rejected) options in the PEP however. One very simple approach that plays reasonably well with type hinting is to make your sentinel value a class:

class DEFAULT: pass

Now you can type-hint your function as taking a union of types that includes type[DEFAULT]:

def spam(ham: list[str]|None|type[DEFAULT] = DEFAULT):

Answer 2

Something I like to do — which is only a slight variation on @Blckknght's answer — is to use a metaclass to give my sentinel class a nicer repr and make it always-falsey.

---

sentinel.py

from typing import Literal 

class SentinelMeta(type):
    def __repr__(cls) -> str:
        return f'<{cls.__name__}>'

    def __bool__(cls) -> Literal[False]:
        return False


class Sentinel(metaclass=SentinelMeta): pass

main.py

from sentinel import Sentinel

class DEFAULT(Sentinel): pass

---

You use it in type hints exactly in the same way @Blckknght suggests:

def spam(ham: list[str]|None|type[DEFAULT] = DEFAULT): ...

But you have the added advantages that your sentinel value is always falsey and has a nicer repr:

>>> DEFAULT
<DEFAULT>
>>> bool(DEFAULT)
False

Answer 3

Nothing wrong with existing answers but I wanted to say another valid option is using Enum. In fact it's the recommended approach in PEP484 - Support for singleton types in unions:

To allow precise typing in such situations, the user should use the Union type in conjunction with the enum.Enum class provided by the standard library, so that type errors can be caught statically.

You code should then look like this:

from enum import Enum

class Default(Enum):
    token = 0

DEFAULT = Default.token

def spam(ham: list[str] | None | Default = DEFAULT):
    if ham is DEFAULT:
        ham = ["prosciutto", "jamon"]
    if ham is None:
        print("Eggs?")
    else:
        print(str(len(ham)) + " ham(s).")