Show More
|
1 | NO CONTENT: new file 100644, binary diff hidden |
|
1 | NO CONTENT: new file 100644, binary diff hidden |
|
1 | NO CONTENT: new file 100644, binary diff hidden |
|
1 | NO CONTENT: new file 100644, binary diff hidden |
|
1 | NO CONTENT: new file 100644, binary diff hidden |
|
1 | NO CONTENT: new file 100644, binary diff hidden |
|
1 | NO CONTENT: new file 100644, binary diff hidden |
|
1 | NO CONTENT: new file 100644, binary diff hidden |
|
1 | NO CONTENT: new file 100644, binary diff hidden |
@@ -1,108 +1,109 | |||
|
1 | 1 | .. _extensions_overview: |
|
2 | 2 | |
|
3 | 3 | ================== |
|
4 | 4 | IPython extensions |
|
5 | 5 | ================== |
|
6 | 6 | |
|
7 | 7 | A level above configuration are IPython extensions, Python modules which modify |
|
8 | 8 | the behaviour of the shell. They are referred to by an importable module name, |
|
9 | 9 | and can be placed anywhere you'd normally import from, or in |
|
10 | 10 | ``$IPYTHONDIR/extensions/``. |
|
11 | 11 | |
|
12 | 12 | Getting extensions |
|
13 | 13 | ================== |
|
14 | 14 | |
|
15 | 15 | A few important extensions are :ref:`bundled with IPython <bundled_extensions>`. |
|
16 | 16 | Others can be found on the `extensions index |
|
17 | 17 | <http://wiki.ipython.org/Extensions_Index>`_ on the wiki, and installed with |
|
18 | 18 | the ``%install_ext`` magic function. |
|
19 | 19 | |
|
20 | 20 | Using extensions |
|
21 | 21 | ================ |
|
22 | 22 | |
|
23 | 23 | To load an extension while IPython is running, use the ``%load_ext`` magic: |
|
24 | 24 | |
|
25 | 25 | .. sourcecode:: ipython |
|
26 | 26 | |
|
27 | 27 | In [1]: %load_ext myextension |
|
28 | 28 | |
|
29 | 29 | To load it each time IPython starts, list it in your configuration file:: |
|
30 | 30 | |
|
31 | 31 | c.InteractiveShellApp.extensions = [ |
|
32 | 32 | 'myextension' |
|
33 | 33 | ] |
|
34 | 34 | |
|
35 | 35 | Writing extensions |
|
36 | 36 | ================== |
|
37 | 37 | |
|
38 | 38 | An IPython extension is an importable Python module that has a couple of special |
|
39 | 39 | functions to load and unload it. Here is a template:: |
|
40 | 40 | |
|
41 | 41 | # myextension.py |
|
42 | 42 | |
|
43 | 43 | def load_ipython_extension(ipython): |
|
44 | 44 | # The `ipython` argument is the currently active `InteractiveShell` |
|
45 | 45 | # instance, which can be used in any way. This allows you to register |
|
46 | 46 | # new magics, plugins or aliases, for example. |
|
47 | 47 | |
|
48 | 48 | def unload_ipython_extension(ipython): |
|
49 | 49 | # If you want your extension to be unloadable, put that logic here. |
|
50 | 50 | |
|
51 | 51 | This :func:`load_ipython_extension` function is called after your extension is |
|
52 | 52 | imported, and the currently active :class:`~IPython.core.interactiveshell.InteractiveShell` |
|
53 | 53 | instance is passed as the only argument. You can do anything you want with |
|
54 | 54 | IPython at that point. |
|
55 | 55 | |
|
56 | 56 | :func:`load_ipython_extension` will be called again if you load or reload |
|
57 | 57 | the extension again. It is up to the extension author to add code to manage |
|
58 | 58 | that. |
|
59 | 59 | |
|
60 | 60 | Useful :class:`InteractiveShell` methods include :meth:`~IPython.core.interactiveshell.InteractiveShell.define_magic`, |
|
61 | 61 | :meth:`~IPython.core.interactiveshell.InteractiveShell.push` (to add variables to the user namespace) and |
|
62 | 62 | :meth:`~IPython.core.interactiveshell.InteractiveShell.drop_by_id` (to remove variables on unloading). |
|
63 | 63 | |
|
64 | 64 | You can put your extension modules anywhere you want, as long as they can be |
|
65 | 65 | imported by Python's standard import mechanism. However, to make it easy to |
|
66 | 66 | write extensions, you can also put your extensions in |
|
67 | 67 | ``os.path.join(ip.ipython_dir, 'extensions')``. This directory is added to |
|
68 | 68 | ``sys.path`` automatically. |
|
69 | 69 | |
|
70 | 70 | When your extension is ready for general use, please add it to the `extensions |
|
71 | 71 | index <http://wiki.ipython.org/Extensions_Index>`_. |
|
72 | 72 | |
|
73 | 73 | Plugin class |
|
74 | 74 | ------------ |
|
75 | 75 | |
|
76 | 76 | More advanced extensions might want to subclass :class:`IPython.core.plugin.Plugin`. |
|
77 | 77 | A plugin can have options configured by IPython's main :ref:`configuration |
|
78 | 78 | system <config_overview>`. The code to load and unload it looks like this:: |
|
79 | 79 | |
|
80 | 80 | def load_ipython_extension(ip): |
|
81 | 81 | """Load the plugin in IPython.""" |
|
82 | 82 | plugin = MyPlugin(shell=ip, config=ip.config) |
|
83 | 83 | try: |
|
84 | 84 | ip.plugin_manager.register_plugin('myplugin', plugin) |
|
85 | 85 | except KeyError: |
|
86 | 86 | print("Already loaded") |
|
87 | 87 | |
|
88 | 88 | def unload_ipython_extension(ip): |
|
89 | 89 | ip.plugin_manager.unregister_plugin('myplugin') |
|
90 | 90 | |
|
91 | 91 | For examples, see these files: |
|
92 | 92 | |
|
93 | 93 | * :file:`IPython/extensions/autoreload.py` |
|
94 | 94 | * :file:`IPython/extensions/storemagic.py` |
|
95 | 95 | |
|
96 | 96 | .. _bundled_extensions: |
|
97 | 97 | |
|
98 | 98 | Extensions bundled with IPython |
|
99 | 99 | =============================== |
|
100 | 100 | |
|
101 | 101 | .. toctree:: |
|
102 | 102 | :maxdepth: 1 |
|
103 | 103 | |
|
104 | 104 | autoreload |
|
105 | 105 | cythonmagic |
|
106 | octavemagic | |
|
106 | 107 | rmagic |
|
107 | 108 | storemagic |
|
108 | 109 | sympyprinting |
@@ -1,99 +1,6 | |||
|
1 | 1 | ===================== |
|
2 | 2 | Development version |
|
3 | 3 | ===================== |
|
4 | 4 | |
|
5 | 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 | 1 | .. Developers should add in this file, during each release cycle, information |
|
2 | 2 | .. about important changes they've made, in a summary format that's meant for |
|
3 | 3 | .. end users. For each release we normally have three sections: features, bug |
|
4 | 4 | .. fixes and api breakage. |
|
5 | 5 | .. Please remember to credit the authors of the contributions by name, |
|
6 | 6 | .. especially when they are new users or developers who do not regularly |
|
7 | 7 | .. participate in IPython's development. |
|
8 | 8 | |
|
9 | 9 | .. _whatsnew_index: |
|
10 | 10 | |
|
11 | 11 | ===================== |
|
12 | 12 | What's new in IPython |
|
13 | 13 | ===================== |
|
14 | 14 | |
|
15 | 15 | This section documents the changes that have been made in various versions of |
|
16 | 16 | IPython. Users should consult these pages to learn about new features, bug |
|
17 | 17 | fixes and backwards incompatibilities. Developers should summarize the |
|
18 | 18 | development work they do here in a user friendly format. |
|
19 | 19 | |
|
20 | 20 | .. toctree:: |
|
21 | 21 | :maxdepth: 1 |
|
22 | 22 | |
|
23 | 23 | development |
|
24 | version0.13 | |
|
24 | 25 | github-stats-0.13 |
|
25 | 26 | version0.12 |
|
26 | 27 | github-stats-0.12 |
|
27 | 28 | version0.11 |
|
28 | 29 | github-stats-0.11 |
|
29 | 30 | version0.10 |
|
30 | 31 | version0.9 |
|
31 | 32 | version0.8 |
|
32 | 33 | |
|
33 | 34 |
General Comments 0
You need to be logged in to leave comments.
Login now