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