README_DIST.md

typeshi - a dead-simple TypedDict utility

Sometimes when working with Python typing we come across a situation when we need to quickly get a TypedDict object from an existing dict, and then maybe even make it into a self-contained declaration file -- typeshi does both of these things while exposing helpful function interfaces and utilities. You can get started right away by looking at the docstrings of the exposed functions listed below in your favorite code editor, or get a general feel for typeshi first with the examples that follow.

Documented functions of typeshi

• typeddict_from_dict
• declaration_module_from_typeddict
• save_declaration_module_from_json

Installation

$ pip install typeshi

A quick example

typeshi exposes two main functions, typeddict_from_dict and declaration_module_from_typeddict. typeddict_from_dict is used to get a TypedDict from a dict instance at runtime, whereas declaration_module_from_typeddict generates the contents of a declaration module from a TypedDict. The most common usage of typeshi would be something like this:

# Let's say I have some JSON file that I load into my app at runtime,
# maybe it contains something like a locale or a config file...
# For the sake of this example let this be some sort of locale
with open(MY_JSON) as fp:
    my_dict = json.load(fp)

print(my_dict['greetings']['evening']['polite'])
# ^ I can *guess* that this is a string (and that it exists at all),
# but I'm lacking my Intellisense to be sure, let's change that

# I kind of wish I could develop easier with the help of type hints of my locale,
# this is where typeshi comes in:
import typeshi

# first, I'll generate my TypedDict
# since in this example I'm thinking of a locale, I'll name my TypedDict "Locale" as well as tell typeshi
# to convert applicable types into their typing.Literal counterparts, which will make my life easier while coding
td = typeshi.typeddict_from_dict(typeddict_name='Locale', original_dict=my_dict, literals_where_possible=True)

# Now my TypedDict is already generated, but it doesn't do much for me if it's just sitting in memory...
# I'll generate a declaration file so that I can import it and type hint my locale
declaration = typeshi.declaration_module_from_typeddict(td)
# okay, that's my declaration ready, now I'll just save it to a Python file of my choice...
with open('generated/locale_declaration.py', 'w+') as fp:
    fp.write(declaration)

# a generated typeshi declaration file will look something like this:

# generated/locale_declaration.py
from typing import TypedDict, Literal


class GreetingsEvening(TypedDict):
    polite: Literal['Good evening!']
    ...

class Greetings(TypedDict):
    evening: GreetingsEvening
    ...

class Locale(TypedDict):
    greetings: Greetings
    ...

# Okay! With that done, I can now import my TypedDict and use it to type hint my locale
from generated.locale_declaration import Locale

my_dict: Locale  # tell my editor that this is of my Locale type
my_dict['greetings']['evening']['polite']  # Literal['Good evening!']

Now, the locale example is obviously limiting, but the heart of typeshi, that being typeddict_from_dict, becomes very useful very quickly. It supports custom hooks for types and the naming of nested TypedDict classes, making it very easy to use and flexible -- everything is documented within docstrings.

It's worth noting the above example is significantly shortened by using the typeshi helper function save_declaration_module_from_json as follows:

from typeshi import save_declaration_module_from_json

save_declaration_module_from_json(toplevel_cls_name='Locale', json_path='my_json.json',
                                  declaration_path='generated/locale_declaration.py')

Contributing

typeshi is developed and maintained publicly on GitHub.