[IPython-dev] Flat is better than nested

[Fernando Perez]

On Mon, May 20, 2013 at 10:15 AM, W. Trevor King <wking at tremily.us> wrote:
> On Mon, May 20, 2013 at 12:00:04PM -0500, Carlos Córdoba wrote:
>> @Trevor: I think you are missing the point: these changes are not meant
>> for regular users but for projects that are using IPython as a library.
>> The idea is to put in __all__ the main pieces of qtconsole (not only
>> RichIPythonWidget, but also QtKernelManager, QtKernelClient, etc) to
>> tell those projects what elements they need to rely on to build a
>> customized frontend.
>
> It makes sense to pull important pieces into an easy to find location.
> I just think it makes sense to deprecate the overly-nested original
> location when you make the move.  After all [1]:
>
>   There should be one-- and preferably only one --obvious way to do it.

Well, it's a matter of balancing two constraints:

1- having a relatively flat public API, so that third-party projects
(what Carlos refers to) don't have to do very crazy from
IPython.this.that.foo.bar.baz import frob, which gets annoying.

2- allowing the IPython team to develop the libraries with smallish
files and a directory layout that lets people focus on a few things at
a time.

Flattening the actual filesystem completely works against 2, but
Python fortunately offers the __all__ attribute to expose a public
api.  The decorator trick is a convenient way of populating that which
remains close to the code being exposed, so I actually like it quite a
bit.

One more note: having these top-level entry points not only helps
third-party users keep shorter imports, it also lets us reorganize
things internally as needed without breaking the user-facing API.  It
can be handy as the project evolves to move things around in deeply
nested files: if projects are only importing those components from
high-level entry points, nothing will break for them.

I don't think we'll have the time to do a systematic run down of all
the APIs to achieve this before 1.0, but I'd certainly like to have
most of our 'official' entry points require only

from IPython.X import Y

with no deeper nesting.

Cheers,

f