Skip to main content

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.

Example

Say some/module.py originally contains:

def add(a, b):
    return a + b

And myscript.py contains:

from some.module import add

add(1, 2)

Now we want to infer the type annotation of add in some/module.py by running myscript.py with MonkeyType. One way is to run:

$ monkeytype run myscript.py

By default this will dump call traces into a sqlite database in the file monkeytype.sqlite3 in the current working directory. You can then use the monkeytype command to generate a stub file for a module, or apply the type annotations directly to your code.

Running monkeytype stub some.module will output a stub:

def add(a: int, b: int) -> int: ...

Running monkeytype apply some.module will modify some/module.py to:

def add(a: int, b: int) -> int:
    return a + b

This example demonstrates both the value and the limitations of MonkeyType. With MonkeyType, it’s very easy to add annotations that reflect the concrete types you use at runtime, but those annotations may not always match the full intended capability of the functions. For instance, add is capable of handling many more types than just integers. Similarly, MonkeyType may generate a concrete List annotation where an abstract Sequence or Iterable would be more appropriate. MonkeyType’s annotations are an informative first draft, to be checked and corrected by a developer.

Motivation

Readability and static analysis are the primary motivations for adding type annotations to code. It’s already common in many Python style guides to document the argument and return types for a function in its docstring; annotations are a standardized way to provide this documentation, which also permits static analysis by a typechecker such as mypy.

For more on the motivation and design of Python type annotations, see PEP 483 and PEP 484.

Requirements

MonkeyType requires Python 3.6+ and the retype library (for applying type stubs to code files). It generates only Python 3 type annotations (no type comments).

Installing

Install MonkeyType with pip:

pip install MonkeyType

How MonkeyType works

MonkeyType uses the sys.setprofile hook provided by Python to interpose on function calls, function returns, and generator yields, and record the types of arguments / return values / yield values.

It generates stub files based on that data, and can use retype to apply those stub files directly to your code.

See the full documentation for details.

Troubleshooting

Check if your issue is mentioned in the frequently asked questions list.

LICENSE

MonkeyType is BSD licensed.

Changelog

18.1.13

  • Improve error messages in case of “no traces found” and/or file path given instead of module name. Merge of #37, partial fix for #65. Thanks Aarni Koskela.

  • Add monkeytype list_modules sub-command to list all modules present in trace db. Merge of #61, fixes #60. Thanks Alex Miasoiedov.

  • Add --diff option to monkeytype stub. Merge of #59, fixes #58. Thanks Tai-Lin!

  • Add --ignore-existing-annotations option to monkeytype stub. Merge of #55, fixes #15. Thanks Tai-Lin!

18.1.11

  • Fix crash in RewriteEmptyContainers rewriter if a parameter has only empty container types in traces (and more than one). Fixes #53.

18.1.10

  • Display retype errors when stub application fails. Merge of #52, fixes #49.

  • Add --sample-count option to show the number of traces a given stub is based on. Merge of #50, fixes #7. Thanks Tai-Lin.

  • Add monkeytype run -m for running a module as a script. Merge of #41. Thanks Simon Gomizelj.

  • Add support for Django’s cached_property decorator. Merge of #46, fixes #9. Thanks Christopher J Wang.

  • Catch and log serialization exceptions instead of crashing. Fixes #38, merge of #39.

  • Fix bug in default code filter when Python lib paths are symlinked. Merge of #40. Thanks Simon Gomizelj.

17.12.3

  • Rewrite imports from _io module to io. (#1, merge of #32). Thanks Radhans Jadhao.

  • Add Config.cli_context() as a hook for custom CLI initialization and cleanup logic (#28; merge of #29). Thanks Rodney Folz.

17.12.2

  • Exclude “frozen importlib” functions in default code filter.

  • Fix passing args to script run with monkeytype run (#18; merge of #21). Thanks Rodney Folz.

  • Fix generated annotations for NewType types (#22; merge of #23). Thanks Rodney Folz.

17.12.1

  • Fix using MonkeyType outside a virtualenv (#16). Thanks Guido van Rossum for the report.

17.12.0

  • Initial public version.

Metadata

Release files for MonkeyType 18.1.13

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for MonkeyType 18.1.13
File Size Uploaded Provenance Actions
MonkeyType-18.1.13.tar.gz 24.1 kB Without provenance Details for MonkeyType-18.1.13.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for MonkeyType 18.1.13
File Interpreter ABI Platform Actions
MonkeyType-18.1.13-py3-none-any.whl Python 3 none any Details for MonkeyType-18.1.13-py3-none-any.whl

Total release size: 55.9 kB

Release files / MonkeyType-18.1.13.tar.gz

Download URL MonkeyType-18.1.13.tar.gz
Size 24.1 kB
Tags Source
SHA-256 checksum
How to use checksums
1abaee68a19e326652a706199d7009e11a00d2fdbc58bc8c2d10a63d61d87acf
BLAKE2b-256 checksum
How to use checksums
e97ed014360f9fbd179234d370ca3ec85e3b8e2d73b9341438439dec9212afee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Release files / MonkeyType-18.1.13-py3-none-any.whl

Download URL MonkeyType-18.1.13-py3-none-any.whl
Size 31.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
47a296300eb3ada69a1a318e02f52054d92f4a2f6d6a9e5ab1b51e5295f6e71b
BLAKE2b-256 checksum
How to use checksums
3a5b894552ac0696e108e912971617a80aceb2b3a9ad9552d0d48df25e80e6de
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Security for MonkeyType 18.1.13

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page