Thanks for the heads up. I think it is fine for me. (PS: is having the same name really an issue?)

@ellisonbg lost time to the confusion, so I think it makes sense to me to separate them. I don't have enough experience with it to have an opinion on the matter.

Fine with me to.

Hmm right now we have:

traitlets:

• link object
• directional_link object

widgets:

• Link and DirectionalLink objects
• link and dlink

I think they have the same APIs as each other. I propose that we make these two APIs completely parallel in structure and naming. Some options:

1. Use only objects (no wrapper functions) named Link, DirectionalLink, JSLink and JSDirectionalLink.
2. Use the same class names and also offer link, dlink, jslink and jsdlink function.

In either case, we need to add docstrings to the widget versions of whatever survives.

Pinging @jdfreder who will return tomorrow for input.

@ellisonbg interesting, that sounds like the opposite of what you described in #7410. I thought the issue was that they had the same names, but weren't the same thing. But now that sounds like exactly what you want to happen - identical names for two different things.

Sorry about the confusion language:

• They link two attributes in different ways and cannot be used
  interchangably. One works with any HasTraits subclass and doesn't use JS at
  all, the other only works on Widgets and uses JS.
• They have the same API. This is what made it possible for me to be so
  confused. Because the API was the same, there were no exceptions, it just
  didn't work.
• There are cases where you could replace one by the other and things would
  still appear to work fine.

I am trying to find names that reflect that they have the same API (other
than the naming diffs) and similar, but not identical functionality.

On Thu, Jan 15, 2015 at 2:43 PM, Min RK notifications@github.com wrote:

@ellisonbg https://github.com/ellisonbg interesting, that sounds like
the opposite of what you described in #7410
#7410. I thought the issue was
that they had the same names, but weren't the same thing. But now that
sounds like exactly what you want to happen - identical names for two
different things.

—
Reply to this email directly or view it on GitHub
#7468 (comment).

Brian E. Granger
Cal Poly State University, San Luis Obispo
@ellisonbg on Twitter and GitHub
bgranger@calpoly.edu and ellisonbg@gmail.com

ok, I'll wait for resolution on that

I see why this could be confusing. I think they should either share the same names, I prefer link and dlink, and the namespaces should be considered enough to separate the two OR the widget variations of link and dlink should actually be called widget_link and widget_dlink.

Additionally, the widget classes themselve should probably have long names, LinkWidget and DlinkWidget. I do realize this is the old naming scheme, but I think it's important to differentiate the widgets from the helper functions.

@jdfreder and i will sit down and try to come up with good names.

Great. I can implement whatever you decide here, or you guys can make your own PR, if that would be easier.

I've added docstrings and argument validation, which should reduce the confusion. You use link, dlink exactly the same:

link((obj, 'trait_name'), (obj, 'trait_name'), *etc)

The difference is that traitlets.link accepts any HasTraits for obj and the name of any trait for trait_name, and widgets.link only accepts Widgets for obj and names of sync=True traits for trait_name. Both sets of functions now raise an informative TypeError if these assumptions are not valid.

@ellisonbg are you happy with Min's proposal, or do you still think those functions need renaming?

I do think they should have truly different names because of the strong
chance they will be imported at the same time.

On Mon, Jan 26, 2015 at 2:57 PM, Thomas Kluyver notifications@github.com
wrote:

@ellisonbg https://github.com/ellisonbg are you happy with Min's
proposal, or do you still think those functions need renaming?

—
Reply to this email directly or view it on GitHub
#7468 (comment).

Brian E. Granger
Cal Poly State University, San Luis Obispo
@ellisonbg on Twitter and GitHub
bgranger@calpoly.edu and ellisonbg@gmail.com

Is there a strong chance they'll be imported at the same time? It seems to be like you'd use one or the other, but not a combination of both.

Also, like @SylvainCorlay says "names spaces are one honking great idea". Isn't Python's from X import Y as Z designed to allow the users to get around this problem?

Here is what I did:

from IPython.utils.traitlets import link
from IPython.html.widgets import *

And I ended up with the widget link without knowing it...I agree that
namespaces are a great idea, but in this case, I think a bit more
distinction for the user would be helpful (link versus jslink).

On Mon, Jan 26, 2015 at 4:14 PM, Jonathan Frederic <notifications@github.com

wrote:

Is there a strong chance they'll be imported at the same time? It seems to
be like you'd use one or the other, but not a combination of both.

Also, like @SylvainCorlay https://github.com/SylvainCorlay says "names
spaces are one honking great idea". Isn't Python's from X import Y as Z
designed to allow the users to get around this problem?

—
Reply to this email directly or view it on GitHub
#7468 (comment).

Brian E. Granger
Cal Poly State University, San Luis Obispo
@ellisonbg on Twitter and GitHub
bgranger@calpoly.edu and ellisonbg@gmail.com

(GitHub related) Strange that your verbatim block isn't getting parsed by GFM correctly...

Hmm, I sent that comment from email.

On Mon, Jan 26, 2015 at 5:17 PM, Jonathan Frederic <notifications@github.com

wrote:

(GitHub related) Strange that your verbatim block isn't getting parsed by
GFM correctly...

—
Reply to this email directly or view it on GitHub
#7468 (comment).

Brian E. Granger
Cal Poly State University, San Luis Obispo
@ellisonbg on Twitter and GitHub
bgranger@calpoly.edu and ellisonbg@gmail.com

@github there's a bug in GFM parsing 3 comments above this one.

@ellisonbg an important change here - If you try to use widgets.link as if it's traitlets.link, there should be only two cases after this PR:

1. it's one of the subset of cases where the two behave the same (Widget.sync_trait).
2. it's in the traitlets.link superset, where HasTraits.trait works in traitlets.link, but not widgets.link.

In case 1, the link should work fine. In case 2, it will fail immediately with an informative TypeError that only Widget sync traits can be linked. I think this type checking is the important improvement in this PR. If you still think the names shouldn't match, I'm happy to add a js_ prefix to both, or something similar.

I would add a comment that due to exactly this hazard, if avoiding import * is not acceptable, it's typically a good idea to do your import * before doing any explicit imports, since it's a safe assumption that import * will clobber something.

Per @ellisonbg's comments, js link functions are renamed jslink, jsdlink, so we have only:

• jslink (javascript link)
• jsdlink (javascript directional link)
• link (traitlets link)
• dlink (traitlets link)

The classes are implementation details, and removed from the public widgets.__init__ API namespace.

Test failure was sporadic, which earned Travis a good kick in the rear. Success should be up soon.

I'm happy with those names. @ellisonbg do you like the names @minrk is using now, jslink and jsdlink ?

Yep, sounds good.

It seems like everyone is happy with this. I'll merge in an hour or two unless anyone objects.