IDE support

[rmarren1]

This builds on #271 and adds explicit arguments to generated dash component python class __init__ functions (rather than **kwargs), which improves experience in an IDE.

Atom example

Pycharm example

Jupyter Notebook example

Notes

• If dash_html_components or dash_core_components are updated build using this version of the dash module, a user must also update dash since a new function _explicitize_args is added to dash.development.base_component. There are workarounds for this (putting the new function in the archetype generator or into the init.py file, or any shared file in a component module), but I think they are messy since it separates base component code into multiple repositories. I will add an exception to both of the dash-*-components packages that say to download the new dash version.
• Autocomplete functions which rely on the inspect would not work for python2. They work for python 3 since we are able to change the function signature of Component.__init__ to be correct even though it is actually (*args, **kwargs) after the _explicitize_args decorator is applied. This did not matter for Atom and PyCharm, but it seems Jupyter uses the inspect module to perform autocomplete.
• Installing this new dash version and keeping old dash_*_components modules auto-magically adds the auto-complete functionality to Jupyter notebooks, but not Atom or PyCharm.

[rmarren1]

I've thought about the solution we discussed last stand-up, which would look something like this in a dash component

from dash.development.base_component import Component

DEFAULT = object()

class Button(Component):
    """docstring...'"""
    def __init__(self, children=DEFAULT, id=DEFAULT, n_clicks=DEFAULT, ...):

and the current solution in this PR looks like this:

from dash.development.base_component import Component, _explicitize_args


class Button(Component):
    docstirng...
    @_explicitize_args
    def __init__(self, children=None, id=None, n_clicks=None, ..., **kwargs):
        ...
        _explicit_args = kwargs.pop('_explicit_args')
        _locals = locals()
        _locals.update(kwargs)  # For wildcard attrs
        args = {k: _locals[k] for k in _explicit_args if k != 'children'}
        ...

the _explicitize_args decorator will check which arguments were set explicitly by the user and add those to a list _explicit_args which is sent also to the __init__ function.

The object based solution has two benefits over the solution I have implemented in this PR,

1. No new code (the _explicitize_args function) is introduced into the base component, so users who upgrade dash-html-components or dash-core-components do not have to upgrade dash.
2. The actual function signature of __init__ does not change, so auto complete tools which rely on the inspect module will work in Python 2 (so far, this seems to only be Jupyter Notebooks). In the current PR, the actual function signature is __init__(*args, **kwargs), and in Python3 we can use inspect.Signature introduced in Python 3.3 to change the arguments in the function signature. Most tools I have used (Atom, PyCharm) will just look at the module code so it would work for both.

and two drawback that I can think of:

1. Some IDE's (Atom with the autocomplete-python package) actually display the default value (e.g n_clicks=DEFAULT, which might be misleading since we do not (currently) set the property to its default value (e.g. 0 for n_clicks), we set it to None.
2. If we actually set default values, we would need to include the code to find and apply default properties in the __init__ function with special cases for properties where the default value is undefined. It would be nice if these were just taken from the arguments.

The current solution also may work better if the default arguments were included, for example if a property had undefined as a property (e.g. children), we could have in the function signature children='undefined' and it would behave as expected.

Anybody have thoughts on this or other drawbacks I haven't thought of, or have on opinion on which solution you prefer? I am personally for the current solution since I think the actual default value should be explicitly stated in the class code for documentation purposes (right now it is not in the docstring, the best place I know to look for it is the src/components/component.js).
@plotly/dash

[nicolaskruchten]

I think it might be nice to have a family of default values like RequiredString or OptionalInt and so on, which would signal to the user two bits of info: required vs optional and expected type. If "required" then that means you'll get run-time errors if not provided, and if "optional" it means at run-time the underlying component will provide a default value. The type could be inferred from the component prop-types (just at the first level to begin with, nothing like OptionalDictOfString or anything).

It's definitely not Pythonic, but it would make for a nicer experience than DEFAULT IMO :)

[nicolaskruchten]

(PS: the proposal above isn't just mine, it's something that was discussed briefly after the last call!)

[rmarren1]

That seems better than DEFAULT, but I think we would then introduce a dependence of new component library versions on the new dash version, since we should probably introduce all of those new objects in dash/development rather than the archetype or component modules. Not a big deal, I have a check for this right now: https://github.com/rmarren1/dash-html-components/blob/8ba05ba8cc8a0abf245498d2e61b604a669fe480/dash_html_components/__init__.py#L18

I think we have all the functionality of this already, albeit without the default value type being written out as they would be if we included those class names as default arguments (but that information is written in the docstring, the actual default value is not included there currently). E.g., errors are thrown if required arguments are not included, and optional and not included values are not passed to the base Component constructor and therefore get the default value defined in the react code.

[rmarren1]

Added more meaningful default arguments as discussed last standup, Component.UNDEFINED and Component.REQUIRED

[chriddyp]

Do you see room for improvement in making these classes even more minimal? I don't think we have to do it in this PR, but in the future it might be nice if these classes were able to inherit more of this logic, mainly because it looks pretty gnarly 😉

[rmarren1]

I think a lot of it could be moved into the base component (pretty much everything that is not an attribute assignment, and even some of those appear to be the same). I'll make a new issue for this

[chriddyp]

Alright, I'm very happy with this. 💃 from me!

[Akronix]

Awesome! any docs or hint on how to integrate this with our IDE or editor?

[rmarren1]

What editor are you using? A lot of editors I tested work out the box if you install dash-html-components and dash-core-components globally.

[Akronix]

I'm using geany.