Hints file

Design a format for describing behavior of Python code in concise, yet complete, manner.

Use existing knowledge about side effects and types of descriptions people use already (see https://blueprints.launchpad.net/pythoscope/+spec/analyze-docstrings blueprint). Description should include at least the following information:
 - what should be the types of arguments,
 - what is the expected type of an output value,
 - can we test the callable on different input types than those provided,
 - what are the side effects of calling this callable,
 - is this callable dependent on some shared state.

Pythoscope can derive some of this information by itself, from static and dynamic analysis. It should store this information in a human-readable format ("hints file"), which can be modified by the developer to enhance test generation. So we need a way to distinguish between generated information and information provided/corrected by the user.

Moreover, for people that want to keep all information in one place (their source code), documentation should be provided on how to extend docstrings to allow Pythoscope picking up those hints from there.