don't use get_ipython from builtins in library code

[minrk]

mainly adds IPython.get_ipython() as a library-level handle that does the same thing.

We still use get_ipython from builtins in two ways:

• We use it a lot in tests and I haven't changed those, but I can if we want to.
  The same instance mechanism should still work there, it doesn't need to be a special case.
• Some code uses get_ipython from globals as a test for 'are we in IPython?`,
  which seems appropriate, though we can perhaps define a single,
  official test for that and make sure we use that everywhere.

This also fixes the issue discussed in #3285

[takluyver]

We used to have a variable called something like __IPYTHON__ just to indicate that code was running in IPython. I forget what happened to it.

[minrk]

If I remember correctly, we removed it in 0.11 but put it back in 0.12.

[ellisonbg]

I am +1 on these changes, but I would rather create a new module than reusing ipapi which has been marked for death for a really long time. How about core.getipython?

[minrk]

What is the reasoning for removing a module that does one thing (just because it has a 'deprecation' note in the docstring, though we have actually been using it all along) and creating a new module that does the exact same thing?

[ellisonbg]

Mostly history. ipapi was originally the mutant nasty that almost killed IPython. I spent most of a summer trying to exorcise it. Originally, ipapi did much more that get_ipython does - that is what is being deprecated. For me there are two reasons to change the name:

• I don't think the name ipapi communicates what get_ipython actually does.
• I want to completely close the book on the ipapi experience.
• The official way of getting this should be at IPython.get_ipython. The function is simple enough that I am not sure it even warrants being anywhere other than IPython.__init__.py.

[fperez]

Why? I thought it was standard practice to leave the dates for which copyright applies (basically from file creation onwards)...

[minrk]

This is what we have been doing all over IPython - I believe you were a part of that conversation many months ago. Updating the copyright to the current date when we update a file.

[Carreau]

No, I guess it was keeping the starting date, omitting the -END one.
2008-2011 -> 2008[Nothing] so you don't have to update the second year every year.
But It is always confusing me too.

[minrk]

gotcha, thanks. in any case, this is a new file now, so 2013 seems right.

I still think per-file copyright is utterly pointless (like putting copyright notice on every page of a book).

[fperez]

I also agree that ipapi is a poor and nebulous name: our public api is large and complex, so there's no point in thinking that we can shove all of it into some mega-import wrapper called ipapi or somesuch.

I'm slightly -1 on putting actual code in __init__ files in general, out of a sense of cleanliness and keeping the code closer to its tests, etc.

As for the more generic question of how to detect that IPython is active, I think it's an important discussion we should try to sort out for 1.0. I don't think this PR is the place for it: perhaps it's better to wrap up this cleanup and think about that separately, as that question has lots of little edge cases we should consider carefully.

[minrk]

move core.ipapi to core.getipython and call this done, then? Since we are moving, I would remove the deprecation warning on get, since it would be in a new location.

[fperez]

Yup, looks good to me. Now's the time to break backwards compatibility :)

One last thing before merging: a note in the docs, in the backw. compat. section, indicating this break (the flat out removal of ipapi). Then we're good.

[minrk]

the core.ipapi deprecation has always seemed weird to me - we moved IPython.ipapi to IPython.core.ipapi, breaking all old code, at the same time as deprecating it, so there should never have been any code that ever used core.ipapi, since it was never anything but deprecated.

[ellisonbg]

I think this looks good now, is there anything left to finish?