ioam/param — pull request #72 by jlstevens (2014-12-12 00:33:01+00:00)
Title: ParameterizedMetaclass now sets the docstring of __init__ method

Introduction
---------------

This implements my suggestion for better IPython support (#71).

In the end, this was surprisingly easy to implement! Nothing particularly fancy is going on here but I have made this feature optional. You can disable this behavior using the ``DOCSTRING_SIGNATURE`` global variable.

Given that the time taken for class definition (e.g. on import) is rarely a performance issue, this global flag might not be necessary (assuming you are happy enabling this behavior by default).

Demo
-------

```python

class Foo(param.Parameterized):
"""
This is the Foo class.
"""

foo = param.Number(default=42)

def __init__(self, **kwargs):
super(Foo, self).__init__(**kwargs)
```

Now if in IPython Notebook I do:

```python
>>> Foo(
```

I see the following pop-up message:

```
Foo(self, **kwargs)

Foo(*args, **kwargs, foo=42)
```

(The first usless line is automatically generated by IPython - it would be nice to suppress it!)

If I now press the ``+`` button, the pop-up expands to show the following message underneath:

```
This is the Foo class.
```

Note that if a docstring is explicitly supplied to the ``__init__`` method, it will be left untouched.

The crucial features is that you can now tab-complete the 'foo' keyword and see a list all the parameters by pressing TAB (before a unique match is specified).

Limitations
--------------

* I simply sort all the keywords alphanumerically. A fancier implementation could maybe list parameters according to the method resolution order (mro).

* The values used in the signature are not updated if the user overrides the default values of class parameters.

* Param seems to do something special if there is no ``__init__`` for the particular subclass. For instance:

```python
class Bar(param.Parameterized):

bar = param.String(default='bar')

>>> print Bar.__init__.__doc__
Initialize this Parameterized instance.

The values of parameters can be supplied as keyword arguments
to the constructor (using parametername=parametervalue); these
values will override the class default values for this one
instance.

If no 'name' parameter is supplied, self.name defaults to the
object's class name with a unique number appended to it.
```

* The auto-generated signature created by IPython is useless and annoying. Maybe this is something we could disable for Parameterized objects in the IPython extension?

* Perhaps if the output is particularly good, this could replace the ``%params`` magic, listing all the parameters together with their docstrings? Note that pressing the ``^`` button expands all the output in the pager (which is where the ``%param`` magic also displays its output).

* No fancy string formatting. Perhaps this is a feature. :-)

Conclusion
--------------

For now, I just want to sketch out a basic implementation in this PR. The inclusion of fancier features and improvements now depend on your feedback!