In the previous versions of our app, people would just pass some arguments with plain strings to certain functions, as we did not have specific type hinting or data types for some of them. Something like:

# Hidden function signature:
def dummy(var: str):
    pass

# Users:
dummy("cat")

But now we want to implement custom data types for those function signatures, while providing backward compatibility. Say something like this:

# Signature:
def dummy(var: Union[NewDataType, Literal["cat"]])

# Backward compatibility:
dummy("cat")

# New feature:
dummy(NewDataType.cat)

Achieving this for simple function signatures is fine, but the problem comes when the signatures are more complex.

How to implement this if the argument of dummy is a dictionary that can take both Literal["cat"] and NewDataType as keys? Furthermore, how to achieve this if the argument is a dictionary with the same previous key type combination, but that could also have str and int as values (and the four possible combinations)? All of this must be compliant with mypy, pylint and use Python 3.9 (no StrEnum or TypeAlias).

I have tried many different combinations like the following:

from typing import TypedDict, Literal, Dict, Union
from enum import Enum

# For old support:
AnimalsLiteral = Literal[
    "cat",
    "dog",
    "snake",
]

# New datatypes:
class Animals(Enum):
    cat = "cat"
    dog = "dog"
    snake = "snake"

# Union of Animals Enum and Literal types for full support:
DataType = Union[Animals, AnimalsLiteral]

# option 1, which fails:
def dummy(a: Dict[DataType, str]):
    pass

# option 2, which also fails:
# def dummy(a: Union[Dict[DataType, str], Dict[Animals, str], Dict[AnimalsLiteral, str]]):
#    pass

if __name__ == "__main__":
    # Dictionary with keys as Animals Enum
    input_data1 = {
        Animals.dog: "dog",
    }
    dummy(input_data1)

    # Dictionary with keys as Literal["cat", "dog", "snake"]
    input_data2 = {
        "dog": "dog",
    }
    dummy(input_data2)

    # Dictionary with mixed keys: Animals Enum and Literal string
    input_data3 = {
        Animals.dog: "dog",
        "dog": "dog",
    }
    dummy(input_data3)

dummy(input_data1) is fine, but dummy(input_data2) gives the following mypy errors with signature 2 for dummy:

Argument 1 to "dummy" has incompatible type "dict[str, str]"; expected "Union[dict[Union[Animals, Literal['cat', 'dog', 'snake']], str], dict[Animals, str], dict[Literal['cat', 'dog', 'snake'], str]]"Mypyarg-type

Argument 1 to "dummy" has incompatible type "dict[str, str]"; expected "Union[dict[Union[Animals, Literal['cat', 'dog', 'snake']], str], dict[Animals, str], dict[Literal['cat', 'dog', 'snake'], str]]"Mypyarg-type

(variable) input_data2: dict[str, str]

Of course doing something like:

input_data2: DataTypes = {
    "dog": "dog",
}

would solve it, but I can’t ask the users to always do that when they create their datatypes.

Also, I have tried another alternative using TypedDict, but I still run into the same type of mypy errors.

In the end, I want to be able to create mypy and pylint compliant typehints of dictionaries which may take custom key types (as in the example) and even custom value types, or combination of the above.