Add Monkeytype and Poe the Poet plugin for Poetry

[whabanks]

Summary | Résumé

This is an experimental PR that adds monkeytype and the Poetry plugin Poe the Poet to the project.

MonkeyType

Monkeytype collects runtime types of function arguments and return values, and can automatically generate stub files or even add draft type annotations directly to your Python code based on the types collected at runtime.

While it is very useful for automating the process of type annotating Python code bases, it is somewhat cumbersome to work with manually.

Poe the Poet

Enter Poe the Poet, a task runner similar to make that provides a simple way to define project tasks directly in pyproject.toml.

Leveraging features like composite tasks and graphs we can create a rich, fully documented ecosystem of project specific tasks.

Since all poe tasks are run from within the Poetry virtual env by default, we no longer need to ask ourselves the question "Do I need poetry run... in front of this command?", nor would we need poetry run in front of nearly every command in our makefile.

This PR leverages the plugin to create a basic suite of tasks to simplify using Monkeytype. Just run poe or poe --help to list fully documented tasks:

CONFIGURED TASKS
  trace-tests        Runs a Python test file through MonkeyType, generating a record of type annotation traces. Traces are stored in monkeytype.sqlite3
    -p, --path       Path to the test file to run. /tests/app/ can be omitted. e.g. poe trace-tests -p main/test_contact.py
    -m, --method     Name of the test method to execute and trace
  list-traces        Lists all traces awaiting application from monkeytype.sqlite3
  apply-annotations  Applies ALL type annotations generated by trace-tests.

Trying out MonkeyType via Poe the Poet tasks

1. Run poe trace-tests -p main/test_contact.py to generate type annotation traces for all code paths taken during each test in test_contact.py.
   • To collect traces from a single test in a file, run poe trace-tests -p main/test_contact.py -m test_identity_step_logged_in.
2. Note that after the task completes, a monkeytype.sqlite3 file is generated.
   • This DB file stores all the runtime types collected from the test(s) run in step 1.
3. Run poe list-traces to see all existing files and modules that MonkeyType collected types for.
4. Run poe apply-annotations to apply draft type annotations automagically to the code base.
5. Check your git status to review the type annotations that MonkeyType added.