##// END OF EJS Templates
Document date for actual release
Thomas Kluyver -
Show More
@@ -1,320 +1,322
1 1 ============
2 2 3.x Series
3 3 ============
4 4
5 5
6 6 Release 3.0
7 7 ===========
8 8
9 Coming February, 2015
9 Released February 27, 2015
10 10
11 11 This is a really big release. Over 150 contributors, and almost 6000 commits in a bit under a year.
12 12 Support for languages other than Python is greatly improved,
13 13 notebook UI has been significantly redesigned,
14 14 and a lot of improvement has happened in the experimental interactive widgets.
15 15 The message protocol and document format have both been updated,
16 16 while maintaining better compatibility with previous versions than prior updates.
17 17 The notebook webapp now enables editing of any text file, and even
18 18 a web-based terminal (on Unix platforms).
19 19
20 20 3.x will be the last monolithic release of IPython,
21 21 as the next release cycle will see the growing project split into its Python-specific and language-agnostic components.
22 22 Language-agnostic projects (notebook, qtconsole, etc.) will move under the umbrella of the new Project Jupyter name,
23 23 while Python-specific projects (interactive Python shell, Python kernel, IPython.parallel)
24 24 will remain under IPython, and be split into a few smaller packages.
25 25 To reflect this, IPython is in a bit of a transition state.
26 26 The logo on the notebook is now the Jupyter logo.
27 27 When installing kernels system-wide, they go in a `jupyter` directory.
28 28 We are going to do our best to ease this transition for users and developers.
29 29
30 30 Big changes are ahead.
31 31
32 32
33 33 Using different kernels
34 34 -----------------------
35 35
36 36 .. image:: ../_images/kernel_selector_screenshot.png
37 37 :alt: Screenshot of 'new' dropdown showing different kernels
38 38 :align: center
39 39
40 40 You can now choose a kernel for a notebook within the user interface, rather
41 41 than starting up a separate notebook server for each kernel you want to use. The
42 42 syntax highlighting adapts to match the language you're working in.
43 43
44 44 Information about the kernel is stored in the notebook file, so when you open a
45 45 notebook, it will automatically start the correct kernel.
46 46
47 47 It is also easier to use the Qt console and the terminal console with other
48 48 kernels, using the --kernel flag::
49 49
50 50 ipython qtconsole --kernel bash
51 51 ipython console --kernel bash
52 52
53 53 # To list available kernels
54 54 ipython kernelspec list
55 55
56 56 Kernel authors should see :ref:`kernelspecs` for how to register their kernels
57 57 with IPython so that these mechanisms work.
58 58
59 59 Typing unicode identifiers
60 60 --------------------------
61 61
62 62 .. image:: /_images/unicode_completion.png
63 63
64 64 Complex expressions can be much cleaner when written with a wider choice of
65 65 characters. Python 3 allows unicode identifiers, and IPython 3 makes it easier
66 66 to type those, using a feature from Julia. Type a backslash followed by a LaTeX
67 67 style short name, such as ``\alpha``. Press tab, and it will turn into Ξ±.
68 68
69 69 Widget migration guide
70 70 ----------------------
71 The widget framework has a lot of backwards incompatible changes. For information about migrating widget notebooks and custom widgets to 3.0 refer to the :doc:`widget migration guide<version3_widget_migration>`.
71 The widget framework has a lot of backwards incompatible changes.
72 For information about migrating widget notebooks and custom widgets to 3.0 refer
73 to the :doc:`widget migration guide<version3_widget_migration>`.
72 74
73 75 Other new features
74 76 ------------------
75 77
76 78 * :class:`~.TextWidget` and :class:`~.TextareaWidget` objects now include a
77 79 ``placeholder`` attribute, for displaying placeholder text before the
78 80 user has typed anything.
79 81
80 82 * The :magic:`load` magic can now find the source for objects in the user namespace.
81 83 To enable searching the namespace, use the ``-n`` option.
82 84
83 85 .. sourcecode:: ipython
84 86
85 87 In [1]: %load -n my_module.some_function
86 88
87 89 * :class:`~.DirectView` objects have a new :meth:`~.DirectView.use_cloudpickle`
88 90 method, which works like ``view.use_dill()``, but causes the ``cloudpickle``
89 91 module from PiCloud's `cloud`__ library to be used rather than dill or the
90 92 builtin pickle module.
91 93
92 94 __ https://pypi.python.org/pypi/cloud
93 95
94 96 * Added a .ipynb exporter to nbconvert. It can be used by passing `--to notebook`
95 97 as a commandline argument to nbconvert.
96 98
97 99 * New nbconvert preprocessor called :class:`~.ClearOutputPreprocessor`. This
98 100 clears the output from IPython notebooks.
99 101
100 102 * New preprocessor for nbconvert that executes all the code cells in a notebook.
101 103 To run a notebook and save its output in a new notebook::
102 104
103 105 ipython nbconvert InputNotebook --ExecutePreprocessor.enabled=True --to notebook --output Executed
104 106
105 107 * Consecutive stream (stdout/stderr) output is merged into a single output
106 108 in the notebook document.
107 109 Previously, all output messages were preserved as separate output fields in the JSON.
108 110 Now, the same merge is applied to the stored output as the displayed output,
109 111 improving document load time for notebooks with many small outputs.
110 112
111 113 * ``NotebookApp.webapp_settings`` is deprecated and replaced with
112 114 the more informatively named ``NotebookApp.tornado_settings``.
113 115
114 116 * Using :magic:`timeit` prints warnings if there is atleast a 4x difference in timings
115 117 between the slowest and fastest runs, since this might meant that the multiple
116 118 runs are not independent of one another.
117 119
118 120 * It's now possible to provide mechanisms to integrate IPython with other event
119 121 loops, in addition to the ones we already support. This lets you run GUI code
120 122 in IPython with an interactive prompt, and to embed the IPython
121 123 kernel in GUI applications. See :doc:`/config/eventloops` for details. As part
122 124 of this, the direct ``enable_*`` and ``disable_*`` functions for various GUIs
123 125 in :mod:`IPython.lib.inputhook` have been deprecated in favour of
124 126 :meth:`~.InputHookManager.enable_gui` and :meth:`~.InputHookManager.disable_gui`.
125 127
126 128 * A ``ScrollManager`` was added to the notebook. The ``ScrollManager`` controls how the notebook document is scrolled using keyboard. Users can inherit from the ``ScrollManager`` or ``TargetScrollManager`` to customize how their notebook scrolls. The default ``ScrollManager`` is the ``SlideScrollManager``, which tries to scroll to the nearest slide or sub-slide cell.
127 129
128 130 * The function :func:`~IPython.html.widgets.interaction.interact_manual` has been
129 131 added which behaves similarly to :func:`~IPython.html.widgets.interaction.interact`,
130 132 but adds a button to explicitly run the interacted-with function, rather than
131 133 doing it automatically for every change of the parameter widgets. This should
132 134 be useful for long-running functions.
133 135
134 136 * The ``%cython`` magic is now part of the Cython module. Use `%load_ext Cython` with a version of Cython >= 0.21 to have access to the magic now.
135 137
136 138 * The Notebook application now offers integrated terminals on Unix platforms,
137 139 intended for when it is used on a remote server. To enable these, install
138 140 the ``terminado`` Python package.
139 141
140 142 * The Notebook application can now edit any plain text files, via a full-page CodeMirror instance.
141 143
142 144 * Setting the default highlighting language for nbconvert with the config option
143 145 ``NbConvertBase.default_language`` is deprecated. Nbconvert now respects
144 146 metadata stored in the :ref:`kernel spec <kernelspecs>`.
145 147
146 148 * IPython can now be configured systemwide, with files in :file:`/etc/ipython`
147 149 or :file:`/usr/local/etc/ipython` on Unix systems,
148 150 or :file:`{%PROGRAMDATA%}\\ipython` on Windows.
149 151
150 152 * Added support for configurable user-supplied `Jinja
151 153 <http://jinja.pocoo.org/>`_ HTML templates for the notebook. Paths to
152 154 directories containing template files can be specified via
153 155 ``NotebookApp.extra_template_paths``. User-supplied template directories
154 156 searched first by the notebook, making it possible to replace existing
155 157 templates with your own files.
156 158
157 159 For example, to replace the notebook's built-in ``error.html`` with your own,
158 160 create a directory like ``/home/my_templates`` and put your override template
159 161 at ``/home/my_templates/error.html``. To start the notebook with your custom
160 162 error page enabled, you would run::
161 163
162 164 ipython notebook '--extra_template_paths=["/home/my_templates/"]'
163 165
164 166 It's also possible to override a template while also `inheriting
165 167 <http://jinja.pocoo.org/docs/dev/templates/#template-inheritance>`_ from that
166 168 template, by prepending ``templates/`` to the ``{% extends %}`` target of
167 169 your child template. This is useful when you only want to override a
168 170 specific block of a template. For example, to add additional CSS to the
169 171 built-in ``error.html``, you might create an override that looks like::
170 172
171 173 {% extends "templates/error.html" %}
172 174
173 175 {% block stylesheet %}
174 176 {{super()}}
175 177 <style type="text/css">
176 178 /* My Awesome CSS */
177 179 </style>
178 180 {% endblock %}
179 181
180 182 * Added a widget persistence API. This allows you to persist your notebooks interactive widgets.
181 183 Two levels of control are provided:
182 184 1. Higher level- ``WidgetManager.set_state_callbacks`` allows you to register callbacks for loading and saving widget state. The callbacks you register are automatically called when necessary.
183 185 2. Lower level- the ``WidgetManager`` Javascript class now has ``get_state`` and ``set_state`` methods that allow you to get and set the state of the widget runtime.
184 186
185 187 Example code for persisting your widget state to session data::
186 188
187 189 %%javascript
188 190 require(['widgets/js/manager'], function(manager) {
189 191 manager.WidgetManager.set_state_callbacks(function() { // Load
190 192 return JSON.parse(sessionStorage.widgets_state || '{}');
191 193 }, function(state) { // Save
192 194 sessionStorage.widgets_state = JSON.stringify(state);
193 195 });
194 196 });
195 197
196 198 * Enhanced support for :magic:`env` magic. As before, :magic:`env` with no
197 199 arguments displays all environment variables and values. Additionally,
198 200 :magic:`env` can be used to get or set individual environment variables. To
199 201 display an individual value, use the `%env var` syntax. To set a value, use
200 202 `env var val` or `env var=val`. Python value expansion using `$` works as usual.
201 203
202 204
203 205 Backwards incompatible changes
204 206 ------------------------------
205 207
206 208 * The :ref:`message protocol <messaging>` has been updated from version 4 to version 5.
207 209 Adapters are included, so IPython frontends can still talk to kernels that
208 210 implement protocol version 4.
209 211
210 212 * The :ref:`notebook format <nbformat>` has been updated from version 3 to version 4.
211 213 Read-only support for v4 notebooks has been backported to IPython 2.4.
212 214 Notable changes:
213 215
214 216 * heading cells are removed in favor or markdown headings
215 217 * notebook outputs and output messages are more consistent with each other
216 218 * use :func:`IPython.nbformat.read` and :func:`~IPython.nbformat.write`
217 219 to read and write notebook files
218 220 instead of the deprecated :mod:`IPython.nbformat.current` APIs.
219 221
220 222 You can downgrade a notebook to v3 via ``nbconvert``::
221 223
222 224 ipython nbconvert --to notebook --nbformat 3 <notebook>
223 225
224 226 which will create :file:`notebook.v3.ipynb`, a copy of the notebook in v3 format.
225 227
226 228 * :func:`IPython.core.oinspect.getsource` call specification has changed:
227 229
228 230 * `oname` keyword argument has been added for property source formatting
229 231 * `is_binary` keyword argument has been dropped, passing ``True`` had
230 232 previously short-circuited the function to return ``None`` unconditionally
231 233
232 234 * Removed the octavemagic extension: it is now available as ``oct2py.ipython``.
233 235
234 236 * Creating PDFs with LaTeX no longer uses a post processor.
235 237 Use `nbconvert --to pdf` instead of `nbconvert --to latex --post pdf`.
236 238
237 239 * Used https://github.com/jdfreder/bootstrap2to3 to migrate the Notebook to Bootstrap 3.
238 240
239 241 Additional changes:
240 242
241 243 - Set `.tab-content .row` `0px;` left and right margin (bootstrap default is `-15px;`)
242 244 - Removed `height: @btn_mini_height;` from `.list_header>div, .list_item>div` in `tree.less`
243 245 - Set `#header` div `margin-bottom: 0px;`
244 246 - Set `#menus` to `float: left;`
245 247 - Set `#maintoolbar .navbar-text` to `float: none;`
246 248 - Added no-padding convenience class.
247 249 - Set border of #maintoolbar to 0px
248 250
249 251 * Accessing the `container` DOM object when displaying javascript has been
250 252 deprecated in IPython 2.0 in favor of accessing `element`. Starting with
251 253 IPython 3.0 trying to access `container` will raise an error in browser
252 254 javascript console.
253 255
254 256 * ``IPython.utils.py3compat.open`` was removed: :func:`io.open` provides all
255 257 the same functionality.
256 258
257 259 * The NotebookManager and ``/api/notebooks`` service has been replaced by
258 260 a more generic ContentsManager and ``/api/contents`` service,
259 261 which supports all kinds of files.
260 262 * The Dashboard now lists all files, not just notebooks and directories.
261 263 * The ``--script`` hook for saving notebooks to Python scripts is removed,
262 264 use :samp:`ipython nbconvert --to python {notebook}` instead.
263 265
264 266 * The ``rmagic`` extension is deprecated, as it is now part of rpy2. See
265 267 :mod:`rpy2.ipython.rmagic`.
266 268
267 269 * :meth:`~.KernelManager.start_kernel` and :meth:`~.KernelManager.format_kernel_cmd`
268 270 no longer accept a ``executable`` parameter. Use the kernelspec machinery instead.
269 271
270 272 * The widget classes have been renamed from `*Widget` to `*`. The old names are
271 273 still functional, but are deprecated. i.e. `IntSliderWidget` has been renamed
272 274 to `IntSlider`.
273 275 * The ContainerWidget was renamed to Box and no longer defaults as a flexible
274 276 box in the web browser. A new FlexBox widget was added, which allows you to
275 277 use the flexible box model.
276 278
277 279 * The notebook now uses a single websocket at `/kernels/<kernel-id>/channels` instead of separate
278 280 `/kernels/<kernel-id>/{shell|iopub|stdin}` channels. Messages on each channel are identified by a
279 281 `channel` key in the message dict, for both send and recv.
280 282
281 283
282 284 Content Security Policy
283 285 ```````````````````````
284 286
285 287 The Content Security Policy is a web standard for adding a layer of security to
286 288 detect and mitigate certain classes of attacks, including Cross Site Scripting
287 289 (XSS) and data injection attacks. This was introduced into the notebook to
288 290 ensure that the IPython Notebook and its APIs (by default) can only be embedded
289 291 in an iframe on the same origin.
290 292
291 293 Override ``headers['Content-Security-Policy']`` within your notebook
292 294 configuration to extend for alternate domains and security settings.::
293 295
294 296 c.NotebookApp.tornado_settings = {
295 297 'headers': {
296 298 'Content-Security-Policy': "frame-ancestors 'self'"
297 299 }
298 300 }
299 301
300 302 Example policies::
301 303
302 304 Content-Security-Policy: default-src 'self' https://*.jupyter.org
303 305
304 306 Matches embeddings on any subdomain of jupyter.org, so long as they are served
305 307 over SSL.
306 308
307 309 There is a `report-uri <https://developer.mozilla.org/en-US/docs/Web/Security/CSP/CSP_policy_directives#report-uri>`_ endpoint available for logging CSP violations, located at
308 310 ``/api/security/csp-report``. To use it, set ``report-uri`` as part of the CSP::
309 311
310 312 c.NotebookApp.tornado_settings = {
311 313 'headers': {
312 314 'Content-Security-Policy': "frame-ancestors 'self'; report-uri /api/security/csp-report"
313 315 }
314 316 }
315 317
316 318 It simply provides the CSP report as a warning in IPython's logs. The default
317 319 CSP sets this report-uri relative to the ``base_url`` (not shown above).
318 320
319 321 For a more thorough and accurate guide on Content Security Policies, check out
320 322 `MDN's Using Content Security Policy <https://developer.mozilla.org/en-US/docs/Web/Security/CSP/Using_Content_Security_Policy>`_ for more examples.
General Comments 0
You need to be logged in to leave comments. Login now