Show More
1 | NO CONTENT: new file 100644, binary diff hidden |
|
NO CONTENT: new file 100644, binary diff hidden |
1 | NO CONTENT: new file 100644, binary diff hidden |
|
NO CONTENT: new file 100644, binary diff hidden |
1 | NO CONTENT: new file 100644, binary diff hidden |
|
NO CONTENT: new file 100644, binary diff hidden |
1 | NO CONTENT: new file 100644, binary diff hidden |
|
NO CONTENT: new file 100644, binary diff hidden |
1 | NO CONTENT: new file 100644, binary diff hidden |
|
NO CONTENT: new file 100644, binary diff hidden |
1 | NO CONTENT: new file 100644, binary diff hidden |
|
NO CONTENT: new file 100644, binary diff hidden |
1 | NO CONTENT: new file 100644, binary diff hidden |
|
NO CONTENT: new file 100644, binary diff hidden |
1 | NO CONTENT: new file 100644, binary diff hidden |
|
NO CONTENT: new file 100644, binary diff hidden |
1 | NO CONTENT: new file 100644, binary diff hidden |
|
NO CONTENT: new file 100644, binary diff hidden |
@@ -1,108 +1,109 | |||||
1 | .. _extensions_overview: |
|
1 | .. _extensions_overview: | |
2 |
|
2 | |||
3 | ================== |
|
3 | ================== | |
4 | IPython extensions |
|
4 | IPython extensions | |
5 | ================== |
|
5 | ================== | |
6 |
|
6 | |||
7 | A level above configuration are IPython extensions, Python modules which modify |
|
7 | A level above configuration are IPython extensions, Python modules which modify | |
8 | the behaviour of the shell. They are referred to by an importable module name, |
|
8 | the behaviour of the shell. They are referred to by an importable module name, | |
9 | and can be placed anywhere you'd normally import from, or in |
|
9 | and can be placed anywhere you'd normally import from, or in | |
10 | ``$IPYTHONDIR/extensions/``. |
|
10 | ``$IPYTHONDIR/extensions/``. | |
11 |
|
11 | |||
12 | Getting extensions |
|
12 | Getting extensions | |
13 | ================== |
|
13 | ================== | |
14 |
|
14 | |||
15 | A few important extensions are :ref:`bundled with IPython <bundled_extensions>`. |
|
15 | A few important extensions are :ref:`bundled with IPython <bundled_extensions>`. | |
16 | Others can be found on the `extensions index |
|
16 | Others can be found on the `extensions index | |
17 | <http://wiki.ipython.org/Extensions_Index>`_ on the wiki, and installed with |
|
17 | <http://wiki.ipython.org/Extensions_Index>`_ on the wiki, and installed with | |
18 | the ``%install_ext`` magic function. |
|
18 | the ``%install_ext`` magic function. | |
19 |
|
19 | |||
20 | Using extensions |
|
20 | Using extensions | |
21 | ================ |
|
21 | ================ | |
22 |
|
22 | |||
23 | To load an extension while IPython is running, use the ``%load_ext`` magic: |
|
23 | To load an extension while IPython is running, use the ``%load_ext`` magic: | |
24 |
|
24 | |||
25 | .. sourcecode:: ipython |
|
25 | .. sourcecode:: ipython | |
26 |
|
26 | |||
27 | In [1]: %load_ext myextension |
|
27 | In [1]: %load_ext myextension | |
28 |
|
28 | |||
29 | To load it each time IPython starts, list it in your configuration file:: |
|
29 | To load it each time IPython starts, list it in your configuration file:: | |
30 |
|
30 | |||
31 | c.InteractiveShellApp.extensions = [ |
|
31 | c.InteractiveShellApp.extensions = [ | |
32 | 'myextension' |
|
32 | 'myextension' | |
33 | ] |
|
33 | ] | |
34 |
|
34 | |||
35 | Writing extensions |
|
35 | Writing extensions | |
36 | ================== |
|
36 | ================== | |
37 |
|
37 | |||
38 | An IPython extension is an importable Python module that has a couple of special |
|
38 | An IPython extension is an importable Python module that has a couple of special | |
39 | functions to load and unload it. Here is a template:: |
|
39 | functions to load and unload it. Here is a template:: | |
40 |
|
40 | |||
41 | # myextension.py |
|
41 | # myextension.py | |
42 |
|
42 | |||
43 | def load_ipython_extension(ipython): |
|
43 | def load_ipython_extension(ipython): | |
44 | # The `ipython` argument is the currently active `InteractiveShell` |
|
44 | # The `ipython` argument is the currently active `InteractiveShell` | |
45 | # instance, which can be used in any way. This allows you to register |
|
45 | # instance, which can be used in any way. This allows you to register | |
46 | # new magics, plugins or aliases, for example. |
|
46 | # new magics, plugins or aliases, for example. | |
47 |
|
47 | |||
48 | def unload_ipython_extension(ipython): |
|
48 | def unload_ipython_extension(ipython): | |
49 | # If you want your extension to be unloadable, put that logic here. |
|
49 | # If you want your extension to be unloadable, put that logic here. | |
50 |
|
50 | |||
51 | This :func:`load_ipython_extension` function is called after your extension is |
|
51 | This :func:`load_ipython_extension` function is called after your extension is | |
52 | imported, and the currently active :class:`~IPython.core.interactiveshell.InteractiveShell` |
|
52 | imported, and the currently active :class:`~IPython.core.interactiveshell.InteractiveShell` | |
53 | instance is passed as the only argument. You can do anything you want with |
|
53 | instance is passed as the only argument. You can do anything you want with | |
54 | IPython at that point. |
|
54 | IPython at that point. | |
55 |
|
55 | |||
56 | :func:`load_ipython_extension` will be called again if you load or reload |
|
56 | :func:`load_ipython_extension` will be called again if you load or reload | |
57 | the extension again. It is up to the extension author to add code to manage |
|
57 | the extension again. It is up to the extension author to add code to manage | |
58 | that. |
|
58 | that. | |
59 |
|
59 | |||
60 | Useful :class:`InteractiveShell` methods include :meth:`~IPython.core.interactiveshell.InteractiveShell.define_magic`, |
|
60 | Useful :class:`InteractiveShell` methods include :meth:`~IPython.core.interactiveshell.InteractiveShell.define_magic`, | |
61 | :meth:`~IPython.core.interactiveshell.InteractiveShell.push` (to add variables to the user namespace) and |
|
61 | :meth:`~IPython.core.interactiveshell.InteractiveShell.push` (to add variables to the user namespace) and | |
62 | :meth:`~IPython.core.interactiveshell.InteractiveShell.drop_by_id` (to remove variables on unloading). |
|
62 | :meth:`~IPython.core.interactiveshell.InteractiveShell.drop_by_id` (to remove variables on unloading). | |
63 |
|
63 | |||
64 | You can put your extension modules anywhere you want, as long as they can be |
|
64 | You can put your extension modules anywhere you want, as long as they can be | |
65 | imported by Python's standard import mechanism. However, to make it easy to |
|
65 | imported by Python's standard import mechanism. However, to make it easy to | |
66 | write extensions, you can also put your extensions in |
|
66 | write extensions, you can also put your extensions in | |
67 | ``os.path.join(ip.ipython_dir, 'extensions')``. This directory is added to |
|
67 | ``os.path.join(ip.ipython_dir, 'extensions')``. This directory is added to | |
68 | ``sys.path`` automatically. |
|
68 | ``sys.path`` automatically. | |
69 |
|
69 | |||
70 | When your extension is ready for general use, please add it to the `extensions |
|
70 | When your extension is ready for general use, please add it to the `extensions | |
71 | index <http://wiki.ipython.org/Extensions_Index>`_. |
|
71 | index <http://wiki.ipython.org/Extensions_Index>`_. | |
72 |
|
72 | |||
73 | Plugin class |
|
73 | Plugin class | |
74 | ------------ |
|
74 | ------------ | |
75 |
|
75 | |||
76 | More advanced extensions might want to subclass :class:`IPython.core.plugin.Plugin`. |
|
76 | More advanced extensions might want to subclass :class:`IPython.core.plugin.Plugin`. | |
77 | A plugin can have options configured by IPython's main :ref:`configuration |
|
77 | A plugin can have options configured by IPython's main :ref:`configuration | |
78 | system <config_overview>`. The code to load and unload it looks like this:: |
|
78 | system <config_overview>`. The code to load and unload it looks like this:: | |
79 |
|
79 | |||
80 | def load_ipython_extension(ip): |
|
80 | def load_ipython_extension(ip): | |
81 | """Load the plugin in IPython.""" |
|
81 | """Load the plugin in IPython.""" | |
82 | plugin = MyPlugin(shell=ip, config=ip.config) |
|
82 | plugin = MyPlugin(shell=ip, config=ip.config) | |
83 | try: |
|
83 | try: | |
84 | ip.plugin_manager.register_plugin('myplugin', plugin) |
|
84 | ip.plugin_manager.register_plugin('myplugin', plugin) | |
85 | except KeyError: |
|
85 | except KeyError: | |
86 | print("Already loaded") |
|
86 | print("Already loaded") | |
87 |
|
87 | |||
88 | def unload_ipython_extension(ip): |
|
88 | def unload_ipython_extension(ip): | |
89 | ip.plugin_manager.unregister_plugin('myplugin') |
|
89 | ip.plugin_manager.unregister_plugin('myplugin') | |
90 |
|
90 | |||
91 | For examples, see these files: |
|
91 | For examples, see these files: | |
92 |
|
92 | |||
93 | * :file:`IPython/extensions/autoreload.py` |
|
93 | * :file:`IPython/extensions/autoreload.py` | |
94 | * :file:`IPython/extensions/storemagic.py` |
|
94 | * :file:`IPython/extensions/storemagic.py` | |
95 |
|
95 | |||
96 | .. _bundled_extensions: |
|
96 | .. _bundled_extensions: | |
97 |
|
97 | |||
98 | Extensions bundled with IPython |
|
98 | Extensions bundled with IPython | |
99 | =============================== |
|
99 | =============================== | |
100 |
|
100 | |||
101 | .. toctree:: |
|
101 | .. toctree:: | |
102 | :maxdepth: 1 |
|
102 | :maxdepth: 1 | |
103 |
|
103 | |||
104 | autoreload |
|
104 | autoreload | |
105 | cythonmagic |
|
105 | cythonmagic | |
|
106 | octavemagic | |||
106 | rmagic |
|
107 | rmagic | |
107 | storemagic |
|
108 | storemagic | |
108 | sympyprinting |
|
109 | sympyprinting |
@@ -1,99 +1,6 | |||||
1 | ===================== |
|
1 | ===================== | |
2 | Development version |
|
2 | Development version | |
3 | ===================== |
|
3 | ===================== | |
4 |
|
4 | |||
5 | This document describes in-flight development work. |
|
5 | This document describes in-flight development work. | |
6 |
|
6 | |||
7 | Redesigned IPython notebook user interface |
|
|||
8 | ------------------------------------------ |
|
|||
9 |
|
||||
10 | (Add description & screenshots of the many changes to the notebook) |
|
|||
11 |
|
||||
12 | Improved tooltips |
|
|||
13 | ~~~~~~~~~~~~~~~~~ |
|
|||
14 |
|
||||
15 | The object tooltips have gained some new functionality. By pressing tab several |
|
|||
16 | times, you can expand them to see more of a docstring, keep them visible as you |
|
|||
17 | fill in a function's parameters, or transfer the information to the pager at the |
|
|||
18 | bottom of the screen. For the details, look at the example notebook |
|
|||
19 | :file:`01_notebook_introduction.ipynb`. |
|
|||
20 |
|
||||
21 | Cell magics |
|
|||
22 | ----------- |
|
|||
23 |
|
||||
24 | IPython's ``%magic`` functions have been extended to let you change the meaning |
|
|||
25 | of a whole cell using the first line. For example, to time the execution of |
|
|||
26 | several statements:: |
|
|||
27 |
|
||||
28 | %%timeit x = 0 # setup |
|
|||
29 | for i in range(100000): |
|
|||
30 | x += i**2 |
|
|||
31 |
|
||||
32 | This is particularly useful to integrate code in another language, and cell |
|
|||
33 | magics already exist for shell scripts, Cython, R and Octave. Using ``%%script |
|
|||
34 | /usr/bin/foo``, you can run a cell in any interpreter that accepts code via |
|
|||
35 | stdin. |
|
|||
36 |
|
||||
37 | Another handy cell magic makes it easy to write short text files: ``%%file |
|
|||
38 | ~/save/to/here.txt``. |
|
|||
39 |
|
||||
40 | To allow these features, the API for magic functions has been refactored and |
|
|||
41 | made more powerful (:ghpull:`1732`). |
|
|||
42 |
|
||||
43 | Tab completer improvements |
|
|||
44 | -------------------------- |
|
|||
45 |
|
||||
46 | Useful tab-completion based on live inspection of objects is one of the most |
|
|||
47 | popular features of IPython. To make this process even more user-friendly, the |
|
|||
48 | completers of both the Qt console and the Notebook have been reworked. |
|
|||
49 |
|
||||
50 | The Qt console comes with a new ncurses-like tab completer, activated by |
|
|||
51 | default, which lets you cycle through the available completions by pressing tab, |
|
|||
52 | or select a completion with the arrow keys (:ghpull:`1851`). |
|
|||
53 |
|
||||
54 | .. figure:: ../_static/ipy_o13_qtconsole_completer.png |
|
|||
55 | :width: 400px |
|
|||
56 | :alt: ncurses-like completer, with highlighted selection. |
|
|||
57 | :align: center |
|
|||
58 | :target: ../_static/ipy_o13_qtconsole_completer.png |
|
|||
59 |
|
||||
60 | The new improved Qt console's ncurses-like completer allows to easily |
|
|||
61 | navigate thought long list of completions. |
|
|||
62 |
|
||||
63 | In the notebook, completions are now sourced both from object introspection and |
|
|||
64 | analysis of surrounding code, so limited completions can be offered for |
|
|||
65 | variables defined in the current cell, or while the kernel is busy |
|
|||
66 | (:ghpull:`1711`). |
|
|||
67 |
|
||||
68 | Other new features |
|
|||
69 | ------------------ |
|
|||
70 |
|
||||
71 | * **%install_ext**: A new magic function to install an IPython extension from |
|
|||
72 | a URL. E.g. ``%install_ext |
|
|||
73 | https://bitbucket.org/birkenfeld/ipython-physics/raw/default/physics.py``. |
|
|||
74 |
|
||||
75 | * The ``%loadpy`` magic is no longer restricted to Python files, and has been |
|
|||
76 | renamed ``%load``. The old name remains as an alias. |
|
|||
77 |
|
||||
78 | * New command line arguments will help external programs find IPython folders: |
|
|||
79 | ``ipython locate`` finds the user's IPython directory, and ``ipython locate |
|
|||
80 | profile foo`` finds the folder for the 'foo' profile (if it exists). |
|
|||
81 |
|
||||
82 | * The :envvar:`IPYTHON_DIR` environment variable, introduced in the Great |
|
|||
83 | Reorganization of 0.11 and existing only in versions 0.11-0.13, has been |
|
|||
84 | deprecated. As described in :ghissue:`1167`, the complexity and confusion of |
|
|||
85 | migrating to this variable is not worth the aesthetic improvement. Please use |
|
|||
86 | the historical :envvar:`IPYTHONDIR` environment variable instead. |
|
|||
87 |
|
||||
88 | * The default value of *interactivity* passed from |
|
|||
89 | :meth:`~IPython.core.interactiveshell.InteractiveShell.run_cell` to |
|
|||
90 | :meth:`~IPython.core.interactiveshell.InteractiveShell.run_ast_nodes` |
|
|||
91 | is now configurable. |
|
|||
92 |
|
||||
93 | Backwards incompatible changes |
|
|||
94 | ------------------------------ |
|
|||
95 |
|
||||
96 | * The exception :exc:`IPython.core.error.TryNext` previously accepted |
|
|||
97 | arguments and keyword arguments to be passed to the next implementation |
|
|||
98 | of the hook. This feature was removed as it made error message propagation |
|
|||
99 | difficult and violated the principle of loose coupling. |
|
@@ -1,33 +1,34 | |||||
1 | .. Developers should add in this file, during each release cycle, information |
|
1 | .. Developers should add in this file, during each release cycle, information | |
2 | .. about important changes they've made, in a summary format that's meant for |
|
2 | .. about important changes they've made, in a summary format that's meant for | |
3 | .. end users. For each release we normally have three sections: features, bug |
|
3 | .. end users. For each release we normally have three sections: features, bug | |
4 | .. fixes and api breakage. |
|
4 | .. fixes and api breakage. | |
5 | .. Please remember to credit the authors of the contributions by name, |
|
5 | .. Please remember to credit the authors of the contributions by name, | |
6 | .. especially when they are new users or developers who do not regularly |
|
6 | .. especially when they are new users or developers who do not regularly | |
7 | .. participate in IPython's development. |
|
7 | .. participate in IPython's development. | |
8 |
|
8 | |||
9 | .. _whatsnew_index: |
|
9 | .. _whatsnew_index: | |
10 |
|
10 | |||
11 | ===================== |
|
11 | ===================== | |
12 | What's new in IPython |
|
12 | What's new in IPython | |
13 | ===================== |
|
13 | ===================== | |
14 |
|
14 | |||
15 | This section documents the changes that have been made in various versions of |
|
15 | This section documents the changes that have been made in various versions of | |
16 | IPython. Users should consult these pages to learn about new features, bug |
|
16 | IPython. Users should consult these pages to learn about new features, bug | |
17 | fixes and backwards incompatibilities. Developers should summarize the |
|
17 | fixes and backwards incompatibilities. Developers should summarize the | |
18 | development work they do here in a user friendly format. |
|
18 | development work they do here in a user friendly format. | |
19 |
|
19 | |||
20 | .. toctree:: |
|
20 | .. toctree:: | |
21 | :maxdepth: 1 |
|
21 | :maxdepth: 1 | |
22 |
|
22 | |||
23 | development |
|
23 | development | |
|
24 | version0.13 | |||
24 | github-stats-0.13 |
|
25 | github-stats-0.13 | |
25 | version0.12 |
|
26 | version0.12 | |
26 | github-stats-0.12 |
|
27 | github-stats-0.12 | |
27 | version0.11 |
|
28 | version0.11 | |
28 | github-stats-0.11 |
|
29 | github-stats-0.11 | |
29 | version0.10 |
|
30 | version0.10 | |
30 | version0.9 |
|
31 | version0.9 | |
31 | version0.8 |
|
32 | version0.8 | |
32 |
|
33 | |||
33 |
|
34 |
General Comments 0
You need to be logged in to leave comments.
Login now