Generate type hints from unit tests
Project description
Python source code may contain type hints in the form of docstrings or comments. These are useful for the human reader as well as static code analysers. ducktest is a command line tool to generate such type hints.
Python unit tests contain type information. Whether they contain complete type information seems to be a mere matter of style. I consider it good practice to unit test code with the types (or corresponding mocks from mock.create_autospec) that are actually used in production code. Therefore, manually writing :type and :rtype tags into method docstrings seems to be a form of duplication.
ducktest remedies that situation by collecting type information from unit tests. It executes unit tests and collects the types of method parameters and return values of methods called in the process. It also collects the spec classes of mock.Mock objects that are passed into or returned from methods. Then ducktest writes that information into the :type and :rtype tags of the corresponding method docstrings.
installation
install ducktest via pip: pip install ducktest
usage
call ducktest from the command line: ducktest configuration_file
The configuration_file is assumed to be on the top level of your project folder. All given paths in that file are relative to its location. It is good practice to keep the configuration_file in your version control system (e.g. git), so that all contributors can use the same configuration. Slash and backslash both work as path separators, to reduce cross-platform problems between linux or windows users. A # symbol marks the rest of the line as comment.
The file is organized in whitespace separated lines: parameter_name value1 value2 All given parameters are added to lists, so:
a_parameter value1 value2
is equivalent to:
a_paramter value1 a_paramter value2
An example configuration file:
# top_level_dir py/ execute_tests_in py/demo/ write_to py/demo/ exclude_parameter_names self cls
parameter |
description |
---|---|
top_level_dir |
This is the first upward folder of your project, that is not a python package (relative to the configuration_file). If the configuration_file resides in such a folder, this parameter should be omitted. There must one or zero top_level_dir values in the configuration_file, not several. |
execute_tests_in |
Execute unit tests that reside in this folders. |
write_to |
Write type information to source code files residing in this folders. |
exclude_parameter_names |
Do not write type information for parameters with these names. Currently used to exclude pretty redundant information for self and cls parameters. |
ducktest deletes all previous :type and :rtype tags in edited docstrings ducktest does not write tags for NoneType or a plain mock.Mock (without _spec_class)
known problems/bugs/TODOs
Currently failing tests contribute type information, although it is potentially incorrect. Execute ducktest only while all tests pass.
ducktest collects all types used in tests, even if they are sub- or supertypes of each other
When a parameter is a class (not an instance), its type is type or metaclass. Calls to its classmethods will create warnings in static type checkers.
Old style classes are not resolved yet
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ducktest-0.1.4-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 973f0bb637f386f9b5593f7431117f274d362935a47a496bb4e1b5ae26e760ca |
|
MD5 | 4deb4ebe8978b64a619e3705b7c546a4 |
|
BLAKE2b-256 | 10939b76bd6600d0ffe351576f900e874220c890bce4833e2b0e63ec37ed4296 |