From fed72595f462ec5a060aa4b5a2b1621e7b682b54 2013-07-29 19:04:13 From: Min RK Date: 2013-07-29 19:04:13 Subject: [PATCH] Merge pull request #3812 from minrk/start_ip Describe differences between start_ipython and embed in what's new and the embedding section closes #3726 --- diff --git a/docs/source/interactive/reference.rst b/docs/source/interactive/reference.rst index 96a172b..04818b8 100644 --- a/docs/source/interactive/reference.rst +++ b/docs/source/interactive/reference.rst @@ -784,17 +784,27 @@ command-line options, as those are trapped first by Python itself. Embedding IPython ================= -It is possible to start an IPython instance inside your own Python -programs. This allows you to evaluate dynamically the state of your -code, operate with your variables, analyze them, etc. Note however that +You can start a regular IPython session with + +.. sourcecode:: python + + import IPython + IPython.start_ipython() + +at any point in your program. This will load IPython configuration, +startup files, and everything, just as if it were a normal IPython session. +In addition to this, +it is possible to embed an IPython instance inside your own Python programs. +This allows you to evaluate dynamically the state of your code, +operate with your variables, analyze them, etc. Note however that any changes you make to values while in the shell do not propagate back to the running code, so it is safe to modify your values because you won't break your code in bizarre ways by doing so. .. note:: - At present, trying to embed IPython from inside IPython causes problems. Run - the code samples below outside IPython. + At present, embedding IPython cannot be done from inside IPython. + Run the code samples below outside IPython. This feature allows you to easily have a fully functional python environment for doing object introspection anywhere in your code with a diff --git a/docs/source/whatsnew/version1.0.rst b/docs/source/whatsnew/version1.0.rst index 8038338..aa1b8f2 100644 --- a/docs/source/whatsnew/version1.0.rst +++ b/docs/source/whatsnew/version1.0.rst @@ -63,6 +63,9 @@ there is an official public API for starting IPython: This is what packages should use that start their own IPython session, but don't actually want embedded IPython (most cases). +:func:`IPython.embed()` is used for embedding IPython into the calling namespace, +similar to calling :func:`Pdb.set_trace`, whereas :func:`start_ipython` +will start a plain IPython session, loading config and startup files as normal. We also have added: