Notebook Cleaning
=================

``clean`` can delete elements from Jupyter notebooks:

* selected notebook-level non-required metadata fields
* selected cell-level metadata fields
* selected cell tags
* empty cells
* all outputs of code cells

When code cell outputs are cleaned,
also the execution counts are cleaned (reset to not-executed).


Result File Name
----------------

The result of cleaning notebook ``nb.ipynb`` is written to ``nb-clean.ipynb``,
unless the option ``--inplace`` is applied.

The result name addition can be adjusted in the configuration file
by setting ``clean_result_name``;
see :doc:`configuration`.


Options
-------

The default behavior is to clean nothing.
The following options are supported by ``clean``:

.. code-block:: none

  -g FIELDS, --global FIELDS
                        comma-separated list of fields to remove from metadata
                        of notebook (default: '')
  -m FIELDS, --metadata FIELDS
                        comma-separated list of fields to remove from metadata
                        of all cells (default: '')
  -t TAGS, --tags TAGS  comma-separated list of tags to remove from all cells;
                        use '-m tags' to remove all tags (default: '')
  -e, --empty-cells, -E, --no-empty-cells
                        delete cells with empty source, i.e. with whitespace
                        only (default: False)
  -o, --outputs, -O, --no-outputs
                        clean all outputs from all code cells (default: False)


JSON Output
-----------

See :ref:`output-json` for general information about JSON output.

``clean`` produces the following members in the JSON output:

  +--------------------+--------------------------------------------------------+
  | Name               | Value                                                  |
  +====================+========================================================+
  | ``"global F"``     | count of global metadata fields ``F`` cleaned (0 or 1) |
  +--------------------+--------------------------------------------------------+
  | ``"cell F"``       | count of cell metadata fields ``F`` cleaned            |
  +--------------------+--------------------------------------------------------+
  | ``"tag T"``        | count of cell tags ``T`` cleaned                       |
  +--------------------+--------------------------------------------------------+
  | ``"empty_cells"``  | count of empty cells cleaned                           |
  +--------------------+--------------------------------------------------------+
  | ``"outputs"``      | count of cell outputs cleaned                          |
  +--------------------+--------------------------------------------------------+

Note that members are absent when count is zero.


Examples
--------

Remove all ``collapsed`` and ``scrolled`` metadata fields from cells:

.. code-block:: bash

  $ nbtb clean -m collapsed,scrolled test.ipynb -v
  Options for nbclean:
    Deleting cell metadata fields: ['collapsed', 'scrolled']
    Clearing outputs from all code cells

  ::::::::::::::
  test.ipynb
  ::::::::::::::
  Counts:
             6 cell collapsed
             2 cell scrolled
             9 outputs cleaned
    Files written: {'test-clean.ipynb'}

  Notebooks processed: 1