mirror/notebook
2
0
Fork 0
mirror of https://github.com/jupyter/notebook.git synced 2025-02-17 12:39:54 +08:00
Code Issues Packages Projects Releases Wiki Activity

Day 1

Browse Source
This commit is contained in:
Jonathan Frederic 2015-05-28 16:43:07 -07:00
parent 5c18ecb151
commit af5fbc5fc9
7 changed files with 57 additions and 654 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/source/index.rst
View File

@ -1,14 +1,11 @@
====================
The IPython notebook
The Jupyter notebook
====================
.. toctree::
:maxdepth: 2
notebook
nbformat
nbconvert
public_server
security
development

18
docs/source/links.txt
View File

@ -16,23 +16,23 @@
NOTE: Some of these were taken from the nipy links compendium.
.. Main IPython links
.. Main Jupyter notebook links
.. _Basic Output: notebook_p2_
.. _notebook_p2: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%202%20-%20Basic%20Output.ipynb
.. _Notebook Basics: notebook_p2_
.. _notebook_p2: https://nbviewer.jupyter.org/urls/raw.github.com/ipython/ipython/3.x/examples/Notebook/Notebook%20Basics.ipynb
.. _Running Code in the IPython Notebook: notebook_p1_
.. _notebook_p1: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%25201%2520-%2520Running%2520Code.ipynb
.. _Running Code in the Jupyter Notebook: notebook_p1_
.. _notebook_p1: https://nbviewer.jupyter.org/urls/raw.github.com/ipython/ipython/3.x/examples/Notebook/Running%20Code.ipynb
.. Other python projects
.. _matplotlib: http://matplotlib.org
.. _nbviewer: http://nbviewer.ipython.org
.. _nbviewer: http://nbviewer.jupyter.org
.. Other tools and projects
.. _Markdown: http://daringfireball.net/projects/markdown/syntax
.. _Rich Display System: notebook_p5_
.. _notebook_p5: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%205%20-%20Rich%20Display%20System.ipynb
.. _Rich Output: notebook_p5_
.. _notebook_p5: https://nbviewer.jupyter.org/urls/raw.github.com/ipython/ipython/3.x/examples/IPython%20Kernel/Rich%20Output.ipynb
.. _Plotting with Matplotlib: notebook_p3_
.. _notebook_p3: http://nbviewer.ipython.org/urls/raw.github.com/ipython/ipython/1.x/examples/notebooks/Part%203%20-%20Plotting%20with%20Matplotlib.ipynb
.. _notebook_p3: https://nbviewer.jupyter.org/urls/raw.github.com/ipython/ipython/3.x/examples/IPython%20Kernel/Plotting%20in%20the%20Notebook.ipynb

168
docs/source/nbconvert.rst
View File

@ -1,168 +0,0 @@
.. _nbconvert:
Converting notebooks to other formats
=====================================
Newly added in the 1.0 release of IPython is the ``nbconvert`` tool, which
allows you to convert an ``.ipynb`` notebook document file into various static
formats.
Currently, ``nbconvert`` is provided as a command line tool, run as a script
using IPython. A direct export capability from within the
IPython Notebook web app is planned.
The command-line syntax to run the ``nbconvert`` script is::
$ ipython nbconvert --to FORMAT notebook.ipynb
This will convert the IPython document file ``notebook.ipynb`` into the output
format given by the ``FORMAT`` string.
The default output format is html, for which the ``--to`` argument may be
omitted::
$ ipython nbconvert notebook.ipynb
IPython provides a few templates for some output formats, and these can be
specified via an additional ``--template`` argument.
The currently supported export formats are:
* ``--to html``
- ``--template full`` (default)
A full static HTML render of the notebook.
This looks very similar to the interactive view.
- ``--template basic``
Simplified HTML, useful for embedding in webpages, blogs, etc.
This excludes HTML headers.
* ``--to latex``
Latex export. This generates ``NOTEBOOK_NAME.tex`` file,
ready for export.
- ``--template article`` (default)
Latex article, derived from Sphinx's howto template.
- ``--template report``
Latex report, providing a table of contents and chapters.
- ``--template basic``
Very basic latex output - mainly meant as a starting point for custom templates.
* ``--to pdf``
Generates a PDF via latex. Supports the same templates as ``--to latex``.
* ``--to slides``
This generates a Reveal.js HTML slideshow.
It must be served by an HTTP server. The easiest way to do this is adding
``--post serve`` on the command-line. The ``serve`` post-processor proxies
Reveal.js requests to a CDN if no local Reveal.js library is present.
To make slides that don't require an internet connection, just place the
Reveal.js library in the same directory where your_talk.slides.html is located,
or point to another directory using the ``--reveal-prefix`` alias.
* ``--to markdown``
Simple markdown output. Markdown cells are unaffected,
and code cells indented 4 spaces.
* ``--to rst``
Basic reStructuredText output. Useful as a starting point for embedding notebooks
in Sphinx docs.
* ``--to script``
Convert a notebook to an executable script.
This is the simplest way to get a Python (or other language, depending on the kernel) script out of a notebook.
If there were any magics in an IPython notebook, this may only be executable from
an IPython session.
* ``--to notebook``
.. versionadded:: 3.0
This doesn't convert a notebook to a different format *per se*,
instead it allows the running of nbconvert preprocessors on a notebook,
and/or conversion to other notebook formats. For example::
ipython nbconvert --to notebook --execute mynotebook.ipynb
will open the notebook, execute it, capture new output, and save the result in
:file:`mynotebook.nbconvert.ipynb`.
::
ipython nbconvert --to notebook --nbformat 3 mynotebook
will create a copy of :file:`mynotebook.ipynb` in :file:`mynotebook.v3.ipynb`
in version 3 of the :ref:`notebook format <nbformat>`.
If you want to convert a notebook in-place,
you can specify the ouptut file to be the same as the input file::
ipython nbconvert --to notebook mynb --output mynb
Be careful with that, since it will replace the input file.
.. note::
nbconvert uses pandoc_ to convert between various markup languages,
so pandoc is a dependency when converting to latex or reStructuredText.
.. _pandoc: http://johnmacfarlane.net/pandoc/
The output file created by ``nbconvert`` will have the same base name as
the notebook and will be placed in the current working directory. Any
supporting files (graphics, etc) will be placed in a new directory with the
same base name as the notebook, suffixed with ``_files``::
$ ipython nbconvert notebook.ipynb
$ ls
notebook.ipynb notebook.html notebook_files/
For simple single-file output, such as html, markdown, etc.,
the output may be sent to standard output with::
$ ipython nbconvert --to markdown notebook.ipynb --stdout
Multiple notebooks can be specified from the command line::
$ ipython nbconvert notebook*.ipynb
$ ipython nbconvert notebook1.ipynb notebook2.ipynb
or via a list in a configuration file, say ``mycfg.py``, containing the text::
c = get_config()
c.NbConvertApp.notebooks = ["notebook1.ipynb", "notebook2.ipynb"]
and using the command::
$ ipython nbconvert --config mycfg.py
LaTeX citations
---------------
``nbconvert`` now has support for LaTeX citations. With this capability you
can:
* Manage citations using BibTeX.
* Cite those citations in Markdown cells using HTML data attributes.
* Have ``nbconvert`` generate proper LaTeX citations and run BibTeX.
For an example of how this works, please see the citations example in
the nbconvert-examples_ repository.
.. _nbconvert-examples: https://github.com/ipython/nbconvert-examples

358
docs/source/nbformat.rst
View File

@ -1,358 +0,0 @@
.. _nbformat:
===========================
The Jupyter Notebook Format
===========================
Introduction
============
Jupyter (né IPython) notebook files are simple JSON documents,
containing text, source code, rich media output, and metadata.
each segment of the document is stored in a cell.
Some general points about the notebook format:
.. note::
*All* metadata fields are optional.
While the type and values of some metadata are defined,
no metadata values are required to be defined.
Top-level structure
===================
At the highest level, a Jupyter notebook is a dictionary with a few keys:
- metadata (dict)
- nbformat (int)
- nbformat_minor (int)
- cells (list)
.. sourcecode:: python
{
"metadata" : {
"signature": "hex-digest", # used for authenticating unsafe outputs on load
"kernel_info": {
# if kernel_info is defined, its name field is required.
"name" : "the name of the kernel"
},
"language_info": {
# if language_info is defined, its name field is required.
"name" : "the programming language of the kernel",
"version": "the version of the language",
"codemirror_mode": "The name of the codemirror mode to use [optional]"
}
},
"nbformat": 4,
"nbformat_minor": 0,
"cells" : [
# list of cell dictionaries, see below
],
}
Some fields, such as code input and text output, are characteristically multi-line strings.
When these fields are written to disk, they **may** be written as a list of strings,
which should be joined with ``''`` when reading back into memory.
In programmatic APIs for working with notebooks (Python, Javascript),
these are always re-joined into the original multi-line string.
If you intend to work with notebook files directly,
you must allow multi-line string fields to be either a string or list of strings.
Cell Types
==========
There are a few basic cell types for encapsulating code and text.
All cells have the following basic structure:
.. sourcecode:: python
{
"cell_type" : "name",
"metadata" : {},
"source" : "single string or [list, of, strings]",
}
Markdown cells
--------------
Markdown cells are used for body-text, and contain markdown,
as defined in `GitHub-flavored markdown`_, and implemented in marked_.
.. _GitHub-flavored markdown: https://help.github.com/articles/github-flavored-markdown
.. _marked: https://github.com/chjj/marked
.. sourcecode:: python
{
"cell_type" : "markdown",
"metadata" : {},
"source" : ["some *markdown*"],
}
.. versionchanged:: nbformat 4.0
Heading cells have been removed, in favor of simple headings in markdown.
Code cells
----------
Code cells are the primary content of Jupyter notebooks.
They contain source code in the language of the document's associated kernel,
and a list of outputs associated with executing that code.
They also have an execution_count, which must be an integer or ``null``.
.. sourcecode:: python
{
"cell_type" : "code",
"execution_count": 1, # integer or null
"metadata" : {
"collapsed" : True, # whether the output of the cell is collapsed
"autoscroll": False, # any of true, false or "auto"
},
"source" : ["some code"],
"outputs": [{
# list of output dicts (described below)
"output_type": "stream",
...
}],
}
.. versionchanged:: nbformat 4.0
``input`` was renamed to ``source``, for consistency among cell types.
.. versionchanged:: nbformat 4.0
``prompt_number`` renamed to ``execution_count``
Code cell outputs
-----------------
A code cell can have a variety of outputs (stream data or rich mime-type output).
These correspond to :ref:`messages <messaging>` produced as a result of executing the cell.
All outputs have an ``output_type`` field,
which is a string defining what type of output it is.
stream output
*************
.. sourcecode:: python
{
"output_type" : "stream",
"name" : "stdout", # or stderr
"text" : ["multiline stream text"],
}
.. versionchanged:: nbformat 4.0
The keys ``stream`` key was changed to ``name`` to match
the stream message.
display_data
************
Rich display outputs, as created by ``display_data`` messages,
contain data keyed by mime-type. This is often called a mime-bundle,
and shows up in various locations in the notebook format and message spec.
The metadata of these messages may be keyed by mime-type as well.
.. sourcecode:: python
{
"output_type" : "display_data",
"data" : {
"text/plain" : ["multiline text data"],
"image/png": ["base64-encoded-png-data"],
"application/json": {
# JSON data is included as-is
"json": "data",
},
},
"metadata" : {
"image/png": {
"width": 640,
"height": 480,
},
},
}
.. versionchanged:: nbformat 4.0
``application/json`` output is no longer double-serialized into a string.
.. versionchanged:: nbformat 4.0
mime-types are used for keys, instead of a combination of short names (``text``)
and mime-types, and are stored in a ``data`` key, rather than the top-level.
i.e. ``output.data['image/png']`` instead of ``output.png``.
execute_result
**************
Results of executing a cell (as created by ``displayhook`` in Python)
are stored in ``execute_result`` outputs.
`execute_result` outputs are identical to ``display_data``,
adding only a ``execution_count`` field, which must be an integer.
.. sourcecode:: python
{
"output_type" : "execute_result",
"execution_count": 42,
"data" : {
"text/plain" : ["multiline text data"],
"image/png": ["base64-encoded-png-data"],
"application/json": {
# JSON data is included as-is
"json": "data",
},
},
"metadata" : {
"image/png": {
"width": 640,
"height": 480,
},
},
}
.. versionchanged:: nbformat 4.0
``pyout`` renamed to ``execute_result``
.. versionchanged:: nbformat 4.0
``prompt_number`` renamed to ``execution_count``
error
*****
Failed execution may show a traceback
.. sourcecode:: python
{
'ename' : str, # Exception name, as a string
'evalue' : str, # Exception value, as a string
# The traceback will contain a list of frames,
# represented each as a string.
'traceback' : list,
}
.. versionchanged:: nbformat 4.0
``pyerr`` renamed to ``error``
.. _raw nbconvert cells:
Raw NBConvert cells
-------------------
A raw cell is defined as content that should be included *unmodified* in :ref:`nbconvert <nbconvert>` output.
For example, this cell could include raw LaTeX for nbconvert to pdf via latex,
or restructured text for use in Sphinx documentation.
The notebook authoring environment does not render raw cells.
The only logic in a raw cell is the `format` metadata field.
If defined, it specifies which nbconvert output format is the intended target
for the raw cell. When outputting to any other format,
the raw cell's contents will be excluded.
In the default case when this value is undefined,
a raw cell's contents will be included in any nbconvert output,
regardless of format.
.. sourcecode:: python
{
"cell_type" : "raw",
"metadata" : {
# the mime-type of the target nbconvert format.
# nbconvert to formats other than this will exclude this cell.
"format" : "mime/type"
},
"source" : ["some nbformat mime-type data"]
}
Backward-compatible changes
===========================
The notebook format is an evolving format. When backward-compatible changes are made,
the notebook format minor version is incremented. When backward-incompatible changes are made,
the major version is incremented.
As of nbformat 4.x, backward-compatible changes include:
- new fields in any dictionary (notebook, cell, output, metadata, etc.)
- new cell types
- new output types
New cell or output types will not be rendered in versions that do not recognize them,
but they will be preserved.
Metadata
========
Metadata is a place that you can put arbitrary JSONable information about
your notebook, cell, or output. Because it is a shared namespace,
any custom metadata should use a sufficiently unique namespace,
such as `metadata.kaylees_md.foo = "bar"`.
Metadata fields officially defined for Jupyter notebooks are listed here:
Notebook metadata
-----------------
The following metadata keys are defined at the notebook level:
=========== =============== ==============
Key Value Interpretation
=========== =============== ==============
kernelspec dict A :ref:`kernel specification <kernelspecs>`
signature str A hashed :ref:`signature <notebook_security>` of the notebook
=========== =============== ==============
Cell metadata
-------------
The following metadata keys are defined at the cell level:
=========== =============== ==============
Key Value Interpretation
=========== =============== ==============
collapsed bool Whether the cell's output container should be collapsed
autoscroll bool or 'auto' Whether the cell's output is scrolled, unscrolled, or autoscrolled
deletable bool If False, prevent deletion of the cell
format 'mime/type' The mime-type of a :ref:`Raw NBConvert Cell <raw nbconvert cells>`
name str A name for the cell. Should be unique
tags list of str A list of string tags on the cell. Commas are not allowed in a tag
=========== =============== ==============
Output metadata
---------------
The following metadata keys are defined for code cell outputs:
=========== =============== ==============
Key Value Interpretation
=========== =============== ==============
isolated bool Whether the output should be isolated into an IFrame
=========== =============== ==============

136
docs/source/notebook.rst
View File

@ -1,6 +1,6 @@
.. _htmlnotebook:
The IPython Notebook
The Jupyter Notebook
====================
Introduction
@ -9,7 +9,7 @@ Introduction
The notebook extends the console-based approach to interactive computing in
a qualitatively new direction, providing a web-based application suitable for
capturing the whole computation process: developing, documenting, and
executing code, as well as communicating the results. The IPython notebook
executing code, as well as communicating the results. The Jupyter notebook
combines two components:
**A web application**: a browser-based tool for interactive authoring of
@ -65,22 +65,22 @@ colleagues.
Notebooks may be exported to a range of static formats, including HTML (for
example, for blog posts), reStructuredText, LaTeX, PDF, and slide shows, via
the new :ref:`nbconvert <nbconvert>` command.
the new :ref:`nbconvert <nbconvert:index>` command.
Furthermore, any ``.ipynb`` notebook document available from a public
URL can be shared via the `IPython Notebook Viewer <nbviewer>`_ (nbviewer_).
URL can be shared via the `Jupyter Notebook Viewer <nbviewer>`_ (nbviewer_).
This service loads the notebook document from the URL and renders it as a
static web page. The results may thus be shared with a colleague, or as a
public blog post, without other users needing to install IPython themselves.
In effect, nbviewer_ is simply :ref:`nbconvert <nbconvert>` as a web service,
so you can do your own static conversions with nbconvert, without relying on
nbviewer.
public blog post, without other users needing to install the Jupyter notebook
themselves. In effect, nbviewer_ is simply :ref:`nbconvert <nbconvert:index>` as
a web service, so you can do your own static conversions with nbconvert,
without relying on nbviewer.
.. seealso::
:ref:`Details on the notebook JSON file format <nbformat>`
:ref:`Details on the notebook JSON file format <nbformat:format_description>`
Starting the notebook server
@ -89,13 +89,13 @@ Starting the notebook server
You can start running a notebook server from the command line using the
following command::
ipython notebook
jupyter notebook
This will print some information about the notebook server in your console,
and open a web browser to the URL of the web application (by default,
``http://127.0.0.1:8888``).
The landing page of the IPython notebook web application, the **dashboard**,
The landing page of the Jupyter notebook web application, the **dashboard**,
shows the notebooks currently available in the notebook directory (by default,
the directory from which the notebook server was started).
@ -105,7 +105,7 @@ and drop ``.ipynb`` notebooks and standard ``.py`` Python source code files
into the notebook list area.
When starting a notebook server from the command line, you can also open a
particular notebook directly, bypassing the dashboard, with ``ipython notebook
particular notebook directly, bypassing the dashboard, with ``jupyter notebook
my_notebook.ipynb``. The ``.ipynb`` extension is assumed if no extension is
given.
@ -225,7 +225,7 @@ example, in the ``pandas`` data analysis package). This is known as IPython's
`Basic Output`_ example notebook
`Rich Display System`_ example notebook
`Rich Output`_ example notebook
Markdown cells
~~~~~~~~~~~~~~
@ -267,7 +267,7 @@ Raw cells
*Raw* cells provide a place in which you can write *output* directly.
Raw cells are not evaluated by the notebook.
When passed through :ref:`nbconvert <nbconvert>`, raw cells arrive in the
When passed through :ref:`nbconvert <nbconvert:index>`, raw cells arrive in the
destination format unmodified. For example, this allows you to type full LaTeX
into a raw cell, which will only be rendered by LaTeX after conversion by
nbconvert.
@ -312,9 +312,9 @@ content of markdown cells have been inserted as comments.
.. seealso::
`Running Code in the IPython Notebook`_ example notebook
`Running Code in the Jupyter Notebook`_ example notebook
`Basic Output`_ example notebook
`Notebook Basics`_ example notebook
:ref:`a warning about doing "roundtrip" conversions <note_about_roundtrip>`.
@ -358,56 +358,31 @@ For the full list of available shortcuts, click :guilabel:`Help`,
Plotting
--------
One major feature of the notebook is the ability to display plots that are the
output of running code cells. IPython is designed to work seamlessly with the
matplotlib_ plotting library to provide this functionality.
One major feature of the Jupyter notebook is the ability to display plots that
are the output of running code cells. The IPython kernel is designed to work
seamlessly with the matplotlib_ plotting library to provide this functionality.
Specific plotting library integration is a feature of the kernel. See the
:ref:`plotting document <ipykernel:plotting>` of the IPython kernel for more
information.
To set this up, before any plotting is performed you must execute the
``%matplotlib`` :ref:`magic command <magics_explained>`. This performs the
necessary behind-the-scenes setup for IPython to work correctly hand in hand
with ``matplotlib``; it does *not*, however, actually execute any Python
``import`` commands, that is, no names are added to the namespace.
If the ``%matplotlib`` magic is called without an argument, the
output of a plotting command is displayed using the default ``matplotlib``
backend in a separate window. Alternatively, the backend can be explicitly
requested using, for example::
%matplotlib gtk
A particularly interesting backend, provided by IPython, is the ``inline``
backend. This is available only for the IPython Notebook and the
:ref:`IPython QtConsole <qtconsole>`. It can be invoked as follows::
%matplotlib inline
With this backend, the output of plotting commands is displayed *inline*
within the notebook, directly below the code cell that produced it. The
resulting plots will then also be stored in the notebook document.
.. seealso::
`Plotting with Matplotlib`_ example notebook
Configuring the IPython Notebook
Configuring the Jupyter Notebook
--------------------------------
The notebook server can be run with a variety of command line arguments.
To see a list of available options enter::
$ ipython notebook --help
$ jupyter notebook --help
Defaults for these options can also be set by creating a file named
``ipython_notebook_config.py`` in your IPython *profile folder*. The profile
folder is a subfolder of your IPython directory; to find out where it is
``ipython_notebook_config.py`` in your Jupyter *profile folder*. The profile
folder is a subfolder of your Jupyter directory; to find out where it is
located, run::
$ ipython locate
$ jupyter locate
To create a new set of default configuration files, with lots of information
on available options, use::
$ ipython profile create
$ jupyter profile create
.. seealso::
@ -417,21 +392,11 @@ on available options, use::
:ref:`notebook_public_server`
Installing new kernels
----------------------
Installing kernels
------------------
Running the notebook makes the current python installation available as a kernel. Other
python installations (different python versions, virtualenv or conda environments) can
be installed as kernels by following these steps:
* make sure that the desired python installation is active (e.g. activate the environment)
and ipython is installed
* run once ``ipython kernelspec install-self --user`` (or ``ipython2 ...`` or ``ipython3 ...``
if you want to install specific python versions)
The last command installs a kernel spec file for the current python installation in
``~/.ipython/kernels/``. Kernel spec files are JSON files, which can be viewed and changed with a
normal text editor.
For information on how to install a Python kernel, refer to :ref:`IPython kernel's
installation document <ipykernel:install>`
Kernels for other languages can be found in the `IPython wiki
<https://github.com/ipython/ipython/wiki/IPython%20kernels%20for%20other%20languages>`_.
@ -458,45 +423,12 @@ you can explicitly trust notebooks, such as those shared with you,
or those that you have written yourself prior to IPython 2.0,
at the command-line with::
$ ipython trust mynotebook.ipynb [other notebooks.ipynb]
$ jupyter trust mynotebook.ipynb [other notebooks.ipynb]
This just generates a new signature stored in each notebook.
You can generate a new notebook signing key with::
$ ipython trust --reset
Importing ``.py`` files
-----------------------
``.py`` files will be imported as a notebook with
the same basename, but an ``.ipynb`` extension, located in the notebook
directory. The notebook created will have just one cell, which will contain
all the code in the ``.py`` file. You can later manually partition this into
individual cells using the ``Edit | Split Cell`` menu option, or the
:kbd:`Ctrl-m -` keyboard shortcut.
Note that ``.py`` scripts obtained from a notebook document using :doc:`nbconvert <nbconvert>`
maintain the structure of the notebook in comments. Reimporting such a
script back into a notebook will preserve this structure.
.. _note_about_roundtrip:
.. warning::
While in simple cases you can "roundtrip" a notebook to Python, edit the
Python file, and then import it back without loss of main content, this is
in general *not guaranteed to work*. First, there is extra metadata
saved in the notebook that may not be saved to the ``.py`` format. And 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 *not* an alternate notebook
format.
.. seealso::
:ref:`nbformat`
$ jupyter trust --reset
.. include:: links.txt

4
docs/source/public_server.rst
View File

@ -4,9 +4,9 @@ Running a notebook server
=========================
The :ref:`IPython notebook <htmlnotebook>` web-application is based on a
The :ref:`Jupyter notebook <notebook>` web-application is based on a
server-client structure. This server uses a :ref:`two-process kernel
architecture <ipythonzmq>` based on ZeroMQ_, as well as Tornado_ for serving
architecture <ipython:ipythonzmq>` based on ZeroMQ_, as well as Tornado_ for serving
HTTP requests. By default, a notebook server runs on http://127.0.0.1:8888/
and is accessible only from `localhost`. This document describes how you can
:ref:`secure a notebook server <notebook_server_security>` and how to :ref:`run it on

22
docs/source/security.rst
View File

@ -1,9 +1,9 @@
.. _notebook_security:
Security in IPython notebooks
Security in Jupyter notebooks
=============================
As IPython notebooks become more popular for sharing and collaboration,
As Jupyter notebooks become more popular for sharing and collaboration,
the potential for malicious people to attempt to exploit the notebook
for their nefarious purposes increases. IPython 2.0 introduces a
security model to prevent execution of untrusted code without explicit
@ -12,11 +12,11 @@ user input.
The problem
-----------
The whole point of IPython is arbitrary code execution. We have no
The whole point of Jupyter is arbitrary code execution. We have no
desire to limit what can be done with a notebook, which would negatively
impact its utility.
Unlike other programs, an IPython notebook document includes output.
Unlike other programs, an Jupyter notebook document includes output.
Unlike other documents, that output exists in a context that can execute
code (via Javascript).
@ -40,12 +40,12 @@ Our security model
The details of trust
--------------------
IPython notebooks store a signature in metadata, which is used to answer
Jupyter notebooks store a signature in metadata, which is used to answer
the question "Did the current user do this?"
This signature is a digest of the notebooks contents plus a secret key,
known only to the user. The secret key is a user-only readable file in
the IPython profile's security directory. By default, this is::
the Jupyter profile's security directory. By default, this is::
~/.ipython/profile_default/security/notebook_secret
@ -85,7 +85,7 @@ long time. Users can explicitly trust a notebook in two ways:
- At the command-line, with::
ipython trust /path/to/notebook.ipynb
jupyter trust /path/to/notebook.ipynb
- After loading the untrusted notebook, with ``File / Trust Notebook``
@ -95,7 +95,7 @@ the user's key, and then store the newly signed notebook.
Reporting security issues
-------------------------
If you find a security vulnerability in IPython, either a failure of the
If you find a security vulnerability in Jupyter, either a failure of the
code to properly implement the model described here, or a failure of the
model itself, please report it to security@ipython.org.
@ -105,7 +105,7 @@ you can use :download:`this PGP public key <ipython_security.asc>`.
Affected use cases
------------------
Some use cases that work in IPython 1.0 will become less convenient in
Some use cases that work in Jupyter 1.0 will become less convenient in
2.0 as a result of the security changes. We do our best to minimize
these annoyance, but security is always at odds with convenience.
@ -133,9 +133,9 @@ collaborator's key will differ, this will result in each share starting
in an untrusted state. There are three basic approaches to this:
- re-run notebooks when you get them (not always viable)
- explicitly trust notebooks via ``ipython trust`` or the notebook menu
- explicitly trust notebooks via ``jupyter trust`` or the notebook menu
(annoying, but easy)
- share a notebook secret, and use an IPython profile dedicated to the
- share a notebook secret, and use an Jupyter profile dedicated to the
collaboration while working on the project.
Multiple profiles or machines