Metadata-Version: 2.1
Name: nbstripout
Version: 0.3.6
Summary: Strips outputs from Jupyter and IPython notebooks
Home-page: https://github.com/kynan/nbstripout
Author: Min RK
Author-email: benjaminrk@gmail.com
Maintainer: Florian Rathgeber, Michael McNeil Forbes
Maintainer-email: florian.rathgeber@gmail.com, michael.forbes+python@gmail.com
License: License :: OSI Approved :: MIT License
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Other Environment
Classifier: Framework :: IPython
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Topic :: Software Development :: Version Control
Provides: nbstripout
Requires-Dist: nbformat

.. image:: https://travis-ci.org/kynan/nbstripout.svg?branch=master
    :target: https://travis-ci.org/kynan/nbstripout
.. image:: https://img.shields.io/pypi/dm/nbstripout.svg
    :target: https://pypi.python.org/pypi/nbstripout
.. image:: https://img.shields.io/pypi/v/nbstripout.svg
    :target: https://pypi.python.org/pypi/nbstripout
.. image:: https://img.shields.io/badge/license-MIT-blue.svg
    :target: https://raw.githubusercontent.com/kynan/nbstripout/master/LICENSE.txt
.. image:: https://img.shields.io/pypi/pyversions/nbstripout.svg
    :target: https://pypi.python.org/pypi/nbstripout

nbstripout: strip output from Jupyter and IPython notebooks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Opens a notebook, strips its output, and writes the outputless version to the
original file.

Useful mainly as a git filter or pre-commit hook for users who don't want to
track output in VCS.

This does mostly the same thing as the `Clear All Output` command in the
notebook UI.

Based on https://gist.github.com/minrk/6176788.

Screencast
==========

This screencast demonstrates the use and working principles behind the
nbstripout utility and how to use it as a Git filter:

.. image:: http://i.imgur.com/7oQHuJ5.png
    :target: https://www.youtube.com/watch?v=BEMP4xacrVc

Installation
============

You can download and install the latest version of ``nbstripout`` from PyPI_,
the Python package index, as follows: ::

    pip install --upgrade nbstripout

When using the Anaconda_ Python distribution, install ``nbstripout`` via the
conda_ package manager from conda-forge_: ::

    conda install -c conda-forge nbstripout

Usage
=====

Strip output from IPython / Jupyter notebook (modifies the files in-place): ::

    nbstripout FILE.ipynb [FILE2.ipynb ...]

Force processing of non ``.ipynb`` files: ::

    nbstripout -f FILE.ipynb.bak

Write to stdout e.g. to use as part of a shell pipeline: ::

    cat FILE.ipynb | nbstripout > OUT.ipynb

or ::

    nbstripout -t FILE.ipynb | other-command

Set up the git filter and attributes as described in the manual installation
instructions below: ::

    nbstripout --install

Set up the git filter using ``.gitattributes`` ::

    nbstripout --install --attributes .gitattributes

Set up the git filter in your global ``~/.gitconfig`` ::

    nbstripout --install --global

Remove the git filter and attributes: ::

    nbstripout --uninstall

Remove the git filter from your global ``~/.gitconfig`` and attributes ::

    nbstripout --install --global

Remove the git filter and attributes from ``.gitattributes``: ::

    nbstripout --uninstall --attributes .gitattributes

Check if ``nbstripout`` is installed in the current repository
(exits with code 0 if installed, 1 otherwise): ::

    nbstripout --is-installed

Print status of ``nbstripout`` installation in the current repository and
configuration summary of filter and attributes if installed
(exits with code 0 if installed, 1 otherwise): ::

    nbstripout --status

Print the version: ::

    nbstripout --version

Show this help page: ::

    nbstripout --help

Configuration files
+++++++++++++++++++

The following table shows in which files the ``nbstripout`` filter and
attribute configuration is written to for given extra flags to ``--install``
and ``--uninstall``:

======================================== ================ ========================
flags                                    filters          attributes
======================================== ================ ========================
none                                     ``.git/config``  ``.git/info/attributes``
``--global``                             ``~/.gitconfig`` ``.git/info/attributes``
``--attributes=.gitattributes``          ``.git/config``  ``.gitattributes``
``--global --attributes=.gitattributes`` ``~/.gitconfig`` ``.gitattributes``
======================================== ================ ========================

Install globally
++++++++++++++++

Usually, ``nbstripout`` is installed per repository so you can choose where to
use it or not. You can choose to set the attributes in ``.gitattributes`` and
commit this file to your repository, however there is no way to have git set up
the filters automatically when someone clones a repository. This is by design,
to prevent you from executing arbitrary and potentially malicious code when
cloning a repository.

To install ``nbstripout`` for all your repositories such that you no longer
need to run the installation once per repository, install as follows: ::

    mkdir -p ~/.config/git  # This folder may not exist
    nbstripout --install --global --attributes=~/.config/git/attributes

This will set up the filters and diff driver in your ``~/.gitconfig`` and
instruct git to apply them to any ``.ipynb`` file in any repository.

Note that you need to uninstall with the same flags: ::

    nbstripout --uninstall --global --attributes=~/.config/git/attributes

Apply retroactively
+++++++++++++++++++

``nbstripout`` can be used to rewrite an existing Git repository using
``git filter-branch`` to strip output from existing notebooks. This invocation
uses ``--index-filter`` and operates on all ipynb-files in the repo: ::

    git filter-branch -f --index-filter '
        git checkout -- :*.ipynb
        find . -name "*.ipynb" -exec nbstripout "{}" +
        git add . --ignore-removal
    '

If the repository is large and the notebooks are in a subdirectory it will run
faster with ``git checkout -- :<subdir>/*.ipynb``. You will get a warning for
commits that do not contain any notebooks, which can be suppressed by piping
stderr to ``/dev/null``.

This is a potentially slower but simpler invocation using ``--tree-filter``: ::

    git filter-branch -f --tree-filter 'find . -name "*.ipynb" -exec nbstripout "{}" +'

Keeping some output
+++++++++++++++++++

Do not strip the execution count/prompt number ::

    nbstripout --keep-count

Do not strip the output ::

    nbstripout --keep-output

To mark special cells so that the output is not striped, set the
``"keep_output": true`` metadata on the cell.  To do this, select the
"Edit Metadata" Cell Toolbar, and then use the "Edit Metadata" button
on the desired cell to enter something like::

    {
      "keep_output": true,
    }

Another use-case is to preserve initialization cells that might load
customized CSS etc. critical for the display of the notebook.  To
support this, we also keep output for cells with::

    {
      "init_cell": true,
    }

This is the same metadata used by the `init_cell nbextension`__.

__ https://github.com/ipython-contrib/jupyter_contrib_nbextensions/tree/master/src/jupyter_contrib_nbextensions/nbextensions/init_cell

Stripping metadata
++++++++++++++++++

This is configurable via ``git config (--global) filter.nbstripout.extrakeys``.
An example would be: ::

    git config --global filter.nbstripout.extrakeys '
      metadata.celltoolbar metadata.kernel_spec.display_name
      metadata.kernel_spec.name metadata.language_info.codemirror_mode.version
      metadata.language_info.pygments_lexer metadata.language_info.version
      metadata.toc metadata.notify_time metadata.varInspector
      cell.metadata.heading_collapsed cell.metadata.hidden
      cell.metadata.code_folding cell.metadata.tags cell.metadata.init_cell'

Excluding folders
+++++++++++++++++

To exclude a certain folder from being processed by the ``nbstripout`` filter,
add the following line to your ``.git/info/attributes`` (or ``.gitattributes``
if you choose to use that): ::

    docs/** filter= diff=

This will disable ``nbstripout`` for any file in the ``docs`` directory.

To check which attributes a given file has with the current config, run ::

    git check-attr -a -- path/to/file

For a file to which the filter applies you will see the following: ::

    $ git check-attr -a -- foo.ipynb
    foo.ipynb: diff: ipynb
    foo.ipynb: filter: nbstripout

For a file in your excluded folder you will see the following: ::

    $ git check-attr -a -- docs/foo.ipynb
    foo.ipynb: diff:
    foo.ipynb: filter:

Manual filter installation
==========================

Set up a git filter and diff driver using nbstripout as follows: ::

    git config filter.nbstripout.clean '/path/to/nbstripout'
    git config filter.nbstripout.smudge cat
    git config filter.nbstripout.required true
    git config diff.ipynb.textconv '/path/to/nbstripout -t'

This will add a section to the ``.git/config`` file of the current repository.

If you want the filter to be installed globally for your user, add the
``--global`` flag to the ``git config`` invocations above to have the
configuration written to your ``~/.gitconfig`` and apply to all repositories.

Create a file ``.gitattributes`` (if you want it versioned with the repository)
or ``.git/info/attributes`` (to apply it only to the current repository) with
the following content: ::

    *.ipynb filter=nbstripout
    *.ipynb diff=ipynb

This instructs git to use the filter named _nbstripout_ and the diff driver
named _ipynb_ set up in the git config above for every ``.ipynb`` file in the
repository.

If you want the attributes be set for ``.ipynb`` files in any of your git
repositories, add those two lines to ``~/.config/git/attributes``. Note that
this file and the ``~/.config/git`` directory may not exist.

Mercurial usage
===============

Mercurial does not have the equivalent of smudge filters.  One can use
an encode/decode hook but this has some issues.  An alternative
solution is to provide a set of commands that first run ``nbstripout``,
then perform these operations. This is the approach of the `mmf-setup`_
package.

.. _mmf-setup: http://bitbucket.org/mforbes/mmf_setup
.. _Anaconda: https://www.continuum.io/anaconda-overview
.. _conda: http://conda.pydata.org
.. _conda-forge: http://conda-forge.github.io
.. _PyPI: https://pypi.io


