htmlnotebook.txt
248 lines
| 10.9 KiB
| text/plain
|
TextLexer
|
r4524 | .. _htmlnotebook: | ||
========================= | ||||
An HTML Notebook IPython | ||||
========================= | ||||
|
r4856 | .. seealso:: | ||
:ref:`Installation requirements <installnotebook>` for the Notebook. | ||||
|
r4524 | The IPython Notebook consists of two related components: | ||
|
r4674 | * An JSON based Notebook document format for recording and distributing | ||
|
r4524 | Python code and rich text. | ||
* A web-based user interface for authoring and running notebook documents. | ||||
The Notebook can be used by starting the Notebook server with the | ||||
command:: | ||||
$ ipython notebook | ||||
|
r4671 | Note that by default, the notebook doesn't load pylab, it's just a normal | ||
IPython session like any other. If you want pylab support, you must use:: | ||||
$ ipython notebook --pylab | ||||
which will behave similar to the terminal and Qt console versions, using your | ||||
default matplotlib backend and providing floating interactive plot windows. If | ||||
you want inline figures, you must manually select the ``inline`` backend:: | ||||
|
r4674 | $ ipython notebook --pylab=inline | ||
|
r4671 | |||
|
r4524 | This server uses the same ZeroMQ-based two process kernel architecture as | ||
|
r4681 | the QT Console as well Tornado for serving HTTP/S requests. Some of the main | ||
|
r4524 | features of the Notebook include: | ||
* Display rich data (png/html/latex/svg) in the browser as a result of | ||||
computations. | ||||
* Compose text cells using HTML and Markdown. | ||||
|
r4674 | * Import and export notebook documents in range of formats (.ipynb, .py). | ||
|
r4524 | * In browser syntax highlighting, tab completion and autoindentation. | ||
* Inline matplotlib plots that can be stored in Notebook documents and opened | ||||
later. | ||||
See :ref:`our installation documentation <install_index>` for directions on | ||||
how to install the notebook and its dependencies. | ||||
|
r4671 | .. note:: | ||
You can start more than one notebook server at the same time, if you want to | ||||
work on notebooks in different directories. By default the first notebook | ||||
server starts in port 8888, later notebooks search for random ports near | ||||
that one. You can also manually specify the port with the ``--port`` | ||||
|
r4674 | option. | ||
|
r4671 | |||
|
r4524 | Basic Usage | ||
=========== | ||||
|
r4671 | The landing page of the notebook server application, which we call the IPython | ||
Notebook *dashboard*, shows the notebooks currently available in the directory | ||||
in which the application was started, and allows you to create new notebooks. | ||||
A notebook is a combination of two things: | ||||
|
r4674 | 1. An interactive session connected to an IPython kernel, controlled by a web | ||
|
r4671 | application that can send input to the console and display many types of output | ||
(text, graphics, mathematics and more). This is the same kernel used by the | ||||
|
r4673 | :ref:`Qt console <qtconsole>`, but in this case the web console sends input in | ||
|
r4671 | persistent cells that you can edit in-place instead of the vertically scrolling | ||
terminal style used by the Qt console. | ||||
|
r4674 | 2. A document that can save the inputs and outputs of the session as well as | ||
|
r4671 | additional text that accompanies the code but is not meant for execution. In | ||
this way, notebook files serve as a complete computational record of a session | ||||
including explanatory text and mathematics, code and resulting figures. These | ||||
documents are internally JSON files and are saved with the ``.ipynb`` | ||||
extension. | ||||
If you have ever used the Mathematica or Sage notebooks (the latter is also | ||||
web-based__) you should feel right at home. If you have not, you should be | ||||
able to learn how to use it in just a few minutes. | ||||
.. __: http://sagenb.org | ||||
Creating and editing notebooks | ||||
------------------------------ | ||||
You can create new notebooks from the dashboard with the ``New Notebook`` | ||||
button or open existing ones by clicking on their name. Once in a notebook, | ||||
your browser tab will reflect the name of that notebook (prefixed with "IPy:"). | ||||
|
r4674 | The URL for that notebook is not meant to be human-readable and is *not* | ||
persistent across invocations of the notebook server. | ||||
|
r4671 | |||
|
r4674 | You can also drag and drop into the area listing files any python file: it | ||
|
r4671 | will be imported into a notebook with the same name (but ``.ipynb`` extension) | ||
located in the directory where the notebook server was started. This notebook | ||||
will consist of a single cell with all the code in the file, which you can | ||||
later manually partition into individual cells for gradual execution, add text | ||||
and graphics, etc. | ||||
Workflow and limitations | ||||
------------------------ | ||||
The normal workflow in a notebook is quite similar to a normal IPython session, | ||||
with the difference that you can edit a cell in-place multiple times until you | ||||
obtain the desired results rather than having to rerun separate scripts with | ||||
the ``%run`` magic (though magics also work in the notebook). Typically | ||||
you'll work on a problem in pieces, organizing related pieces into cells and | ||||
moving forward as previous parts work correctly. This is much more convenient | ||||
for interactive exploration than breaking up a computation into scripts that | ||||
must be executed together, especially if parts of them take a long time to run | ||||
|
r4880 | (In the traditional terminal-based IPython, you can use tricks with namespaces | ||
and ``%run -i`` to achieve this capability, but we think the notebook is a more | ||||
natural solution for that kind of problem). | ||||
|
r4671 | |||
The only significant limitation the notebook currently has, compared to the qt | ||||
console, is that it can not run any code that expects input from the kernel | ||||
(such as scripts that call :func:`raw_input`). Very importantly, this means | ||||
that the ``%debug`` magic does *not* work in the notebook! We intend to | ||||
correct this limitation, but in the meantime, there is a way to debug problems | ||||
in the notebook: you can attach a Qt console to your existing notebook kernel, | ||||
|
r5014 | and run ``%debug`` from the Qt console. If your notebook is running on a local | ||
computer (i.e. if you are accessing it via your localhost address at | ||||
127.0.0.1), you can just type ``%qtconsole`` in the notebook and a Qt console | ||||
will open up connected to that same kernel. | ||||
In general, the notebook server prints the full details of how to connect to | ||||
each kernel at the terminal, with lines like: | ||||
|
r4671 | |||
[IPKernelApp] To connect another client to this kernel, use: | ||||
|
r5014 | [IPKernelApp] --existing kernel-3bb93edd-6b5a-455c-99c8-3b658f45dde5.json | ||
This is the name of a JSON file that contains all the port and validation | ||||
information necessary to connect to the kernel. You can manually start a | ||||
qt console with:: | ||||
ipython qtconsole --existing kernel-3bb93edd-6b5a-455c-99c8-3b658f45dde5.json | ||||
and if you only have a single kernel running, simply typing:: | ||||
|
r4671 | |||
|
r5014 | ipython qtconsole --existing | ||
|
r4671 | |||
|
r5014 | will automatically find it (it will always find the most recently started | ||
kernel if there is more than one). You can also request this connection data | ||||
by typing ``%connect_info``; this will print the same file information as well | ||||
as the content of the JSON data structure it contains. | ||||
|
r4671 | |||
Text input | ||||
---------- | ||||
|
r4880 | In addition to code cells and the output they produce (such as figures), you | ||
|
r4671 | can also type text not meant for execution. To type text, change the type of a | ||
|
r4674 | cell from ``Code`` to ``Markdown`` by using the button or the :kbd:`Ctrl-m m` | ||
|
r4671 | keybinding (see below). You can then type any text in Markdown_ syntax, as | ||
well as mathematical expressions if you use ``$...$`` for inline math or | ||||
``$$...$$`` for displayed math. | ||||
Exporting a notebook | ||||
-------------------- | ||||
If you want to provide others with a static HTML or PDF view of your notebook, | ||||
use the ``Print`` button. This opens a static view of the document, which you | ||||
can print to PDF using your operating system's facilities, or save to a file | ||||
with your web browser's 'Save' option (note that typically, this will create | ||||
both an html file *and* a directory called `notebook_name_files` next to it | ||||
that contains all the necessary style information, so if you intend to share | ||||
this, you must send the directory along with the main html file). | ||||
The `Download` button lets you save a notebook file to the Download area | ||||
configured by your web browser (particularly useful if you are running the | ||||
notebook server on a remote host and need a file locally). The notebook is | ||||
saved by default with the ``.ipynb`` extension and the files contain JSON data | ||||
that is not meant for human editing or consumption. But you can always export | ||||
the input part of a notebook to a plain python script by choosing Python format | ||||
in the `Download` drop list. This removes all output and saves the text cells | ||||
in comment areas. | ||||
.. warning:: | ||||
While in simple cases you can roundtrip a notebook to Python, edit the | ||||
python file and import it back without loss, this is in general *not | ||||
guaranteed to work at all*. As the notebook format evolves in complexity, | ||||
there will be attributes of the notebook that will not survive a roundtrip | ||||
through the Python form. You should think of the Python format as a way to | ||||
output a script version of a notebook and the import capabilities as a way | ||||
to load existing code to get a notebook started. But the Python version is | ||||
|
r4674 | *not* an alternate notebook format. | ||
|
r4671 | |||
Keyboard use | ||||
------------ | ||||
All actions in the notebook can be achieved with the mouse, but we have also | ||||
added keyboard shortcuts for the most common ones, so that productive use of | ||||
the notebook can be achieved with minimal mouse intervention. The main | ||||
key bindings you need to remember are: | ||||
* :kbd:`Shift-Enter`: execute the current cell (similar to the Qt console), | ||||
show output (if any) and create a new cell below. Note that in the notebook, | ||||
simply using :kbd:`Enter` *never* forces execution, it simply inserts a new | ||||
line in the current cell. Therefore, in the notebook you must always use | ||||
:kbd:`Shift-Enter` to get execution (or use the mouse and click on the ``Run | ||||
Selected`` button). | ||||
|
r4674 | * :kbd:`Ctrl-Enter`: execute the current cell in "terminal mode", where any | ||
|
r4880 | output is shown but the cursor stays in the current cell, whose input | ||
|
r4671 | area is flushed empty. This is convenient to do quick in-place experiments | ||
or query things like filesystem content without creating additional cells you | ||||
may not want saved in your notebook. | ||||
|
r4674 | * :kbd:`Ctrl-m`: this is the prefix for all other keybindings, which consist | ||
|
r4671 | of an additional single letter. Type :kbd:`Ctrl-m h` (that is, the sole | ||
letter :kbd:`h` after :kbd:`Ctrl-m`) and IPython will show you the remaining | ||||
available keybindings. | ||||
|
r5152 | Security | ||
======== | ||||
You can protect your notebook server with a *very* simple single-password by | ||||
setting the :attr:`NotebookApp.password` configurable. It is best to do this in | ||||
your :file:`ipython_notebook_config.py`, e.g.:: | ||||
# Password to use for web authentication | ||||
c.NotebookApp.password = u'super secret' | ||||
because specifying it on the command-line will make it visible to other | ||||
processes on your machine with access to :command:`ps`. | ||||
When using a password, it is a good idea to also use SSL, so that your password | ||||
is not sent in the clear. You can start the notebook to communicate via a secure | ||||
protocol mode using a self-signed certificate by typing:: | ||||
$ ipython notebook --certfile=mycert.pem | ||||
.. note:: | ||||
A self-signed certificate can be generated with openssl. For example:: | ||||
$ openssl req -x509 -nodes -days 365 -newkey rsa:1024 -keyout mycert.pem -out mycert.pem | ||||
|
r4671 | |||
|
r4524 | Notebook document format | ||
======================== | ||||