Signature discovery and printing

[tommyod]

I would like to have a function format_signature(object, verbosity) which takes an object and formats a docstring for printing and returns it.

Something like the following suggestion (it's only a suggestion though!):

• Verbosity 0: return ''
• Verbosity 1: return (...) if the object has a signature, else return None
• Verbosity 2: Same as above, but with argument names, i.e. return (a, b, c)
• Verbosity 3: Same as above, but with argument defaults, i.e. return (a, b=2, c=4)
• Verbosity 4: Same as above, but with type hints if they exist, i.e. return (a:str, b:int=2, c:int=4)
• Verbosity 5: Can we make it more verbose?

Notes:

• I think inspect.Signature is our best bet.
• Beware that some built-in classes have methods implemented in C, so standard methods for getting the signature might not work. See inspect.Signature.from_builtin.
• We must have tests. Both for test objects which we define, and for built-in objects.

This is a very isolated task, and a good introduction to writing some tests. Do you want it @smu095 ?

[smu095]

Yes, thank you! Do you have any useful resources/thoughts on type-checking and assertion statements for a task like this?

[tommyod]

I'm not sure what you specifically mean with regards to type checking and assertions here. In general I think this task amounts to using the inspect library properly, in particular inspect.Signature. Then a few unit tests on user-defined functions and builtins like list.index must be added. Finally you can add the newly created function to the doctree output, run doctree pandas, doctree collections, etc and see if the output is as expected. If not, patch it up the code and add some more tests.

Let's discuss specifics in a WIP PR instead of here :)

[tommyod]

Closed by #9 .