Package: kutuzov
What?Extracts type annotations from Python source documented with Sphinx-compatible docstrings.Why?Existing tools likePyAnnotaterequire you to write a driver to exercise your application, while a special hook collects type information and converts it to annotations.
This works really well, but requires significant effort in writing a comprehensive driver that covers your entire application.If your application already has type information in its docstrings, it may be simpler to convert that information to annotations directly.
Kutuzov will help you with that.How?Kutuzov does this:Scans packages and submodules for docstringsParses the docstrings, extracts type information about each parameterWrites a PyAnnotate-compatible JSON fileWhat remains for you is:Run PyAnnotate and consume the generated JSON fileTweak the results by handPROFITThe amount of tweaking you have to do may vary.
It significantly depends on the quality and accuracy of your docstrings.ExampleWe will be annotating the example.py file.
You will need pyannotate (pip install pyannotate) to proceed.$ python -m kutuzov example.py > type_info.json
$ cat type_info.json
[
    {
        "func_name": "Dog.__init__",
        "line": 2,
        "path": "example.py",
        "samples": 1,
        "type_comments": [
            "(str) -> None"
        ]
    },
    {
        "func_name": "Dog.bark",
        "line": 16,
        "path": "example.py",
        "samples": 1,
        "type_comments": [
            "(str) -> str"
        ]
    }
]
$ pyannotate example.py --py3
Refactored example.py
--- example.py  (original)
+++ example.py  (refactored)
@@ -1,5 +1,5 @@
 class Dog:
-    def __init__(self, name):
+    def __init__(self, name: str) -> None:
         """
         :param str name: The name of this dog.
         """
@@ -13,7 +13,7 @@
         """
         return self._name

-    def bark(self, language='en'):
+    def bark(self, language: str = 'en') -> str:
         """
         Make some noise!

Files that need to be modified:
example.py
NOTE: this was a dry run; use -w to write filesYou may have noticed that [example.py](example.py) already contains a PyAnnotate driver in the mainline.$ cat type_info.json
[
    {
        "path": "example.py",
        "line": 2,
        "func_name": "Dog.__init__",
        "type_comments": [
            "(str) -> None"
        ],
        "samples": 1
    },
    {
        "path": "example.py",
        "line": 8,
        "func_name": "name",
        "type_comments": [
            "() -> str"
        ],
        "samples": 1
    },
    {
        "path": "example.py",
        "line": 16,
        "func_name": "Dog.bark",
        "type_comments": [
            "(str) -> str"
        ],
        "samples": 1
    }
]If you compare that to the previously generated JSON, you will see that it is mostly similar.
The greatest difference is that Kutuzov missed thenameproperty - it doesn’t know how to handle those yet.What’s in a name?Mikhail Kutuzovwas a contemporary ofNapoleon Bonaparte.
Aparticular paintingdepicts Napoleon before the Sphinx.
AndSphinx, of course, is the project that we all love for our Python documentation needs.This project was partially inspired bysphinx.ext.napoleon, which does something similar, but for a different docstring format.