If possible, we should provide a thin compatibility layer for code that instantiates IPython with the above call. There are many projects out there that use this call and it would be great if we can make them continue to work (while printing a DeprecationWarning) unmodified.
I'm not sure yet it can be done correctly with all the changes to our apis, but we should sort this out before 0.11 is out.
Part of the challenge of this is that different people enter our older API at different locations. Some through Shell, but others through the ipmaker stuff. But this pretty annoying though that these old things don't work (like isympy). Minimally, we should have a clear entry point for our new API.
Yes, it's not a pretty situation. But I think the start().mainloop() form is likely the most common entry point, I've seen it used in several high-profile tools, including gedit. So if we can at least cover that one, it will be a good help.
Is the embed function useful for this? I'm not particularly familiar with starting IPython from other situations in the old code.
The easiest way to start a terminal IPython is:
from IPython.frontend.terminal import ipapp
app = ipapp.TerminalIPythonApp.instance() # or just ...App() to prevent constructing global instance
The biggest question is what people expect to happen when they call this API. Are config files parsed? Are commend line arguments read? Are things like exec_files, exec_lines, gui support/pylab initialized? The code Min provides does all of that, but embed (as I remember) does not. We could provide the old IPython.Shell().start().mainloop() API, but I have a feeling it will cause more problems than it solves. The reason is the many of these usage cases involve (like isympy) situations where additional customization is wanted. Keeping IPython.Shell().start().mainloop() around falsely suggests that if you grab the resulting Shell() object, that it will have the same old APIs for customization, which of course it does not. Forcing people to adapt their code to use the new API from the start makes it clear that everything is different. I realize this is a pain for projects that use IPython in this manner though.
The start() call does process sys.argv automatically. Since all of that has changed so much, the sanest approach is probably indeed to simply document the suggested API for initialization. We should also in there, explain to users how the out-of-process kernel works, since some projects may opt instead to write their own client and communicate with a kernel, now that they have the option to do so.
In summary: let's not get dragged into the potential madness of attempting to provide compatibility when we really can't. That effort will be better spent just documenting the way forward...
Min, if you can drop your example above into the docs about embedding, that will already be a good start for now :)
Sure, I'll add a note somewhere.
While trying to find the logical place, I noticed that the interactive reference doc, and the embed examples all refer to the old code, so they need lots of updating. Even the 'new-embed' example which uses the new embed function doesn't work because the embed call signature is wrong.
Marking as critical and docs, because this is now principally a documentation issue, and one that really needs to be fixed.
This can be closed when 0d369cf067802420119b is merged, as part of the docs branch, which needs lots of work.
Merge branch 'docs'
So what is the suggested solution for replacing:
alias ipython='python -c '\''import IPython; IPython.Shell.IPShell().mainloop()'\'''
Solved my own problem here! Here is my new alias for this, which handles both.
alias ipython='python -c "python -c "from IPython import embed; embed()" 2>/dev/null || import IPython; IPython.Shell.IPShell().mainloop()"'