[ANN] NBConvert 5.4 -- A year's worth of changes

[Matthew Seal]

NBConvert 5.4

After a long period between releases, we are pleased to announced nbconvert 5.4.0!

It is available via pypi (pip install nbconvert -U) and conda-forge (conda install nbconvert -c conda-forge).

For full details about the release, see the changelog, but we've highlighted the significant changes below.

Significant Changes

Deprecations

Python 3.3 support was dropped. The version of python is no longer common and new versions have many fixes and interface improvements that warrant the change in support.

Changes in how we handle metadata

There were a few new metadata fields which are now respected in nbconvert.

``nb.metadata.authors`` metadata attribute will be respected in latex exports. Multiple authors will be added with ``,`` separation against their names.

``nb.metadata.title`` will be respected ahead of ``nb.metadata.name`` for title assignment. This better matches with the notebook format.

``nb.metadata.filename`` will override the default ``output_filename_template`` when extracting notebook resources in the ``ExtractOutputPreprocessor``. The attribute is helpful for when you want to consistently fix to a particular output filename, especially when you need to set image filenames for your exports.

The ``raises-exception`` cell tag (``nb.cells[].metadata.tags[raises-exception]``) allows for cell exceptions to not halt execution. The tag is respected in the same way by `nbval <https://github.com/computationalmodelling/nbval>`_ and other notebook interfaces. ``nb.metadata.allow_errors`` will apply this rule for all cells. This feature is toggleable with the ``force_raise_errors`` configuration option.

Errors from executing the notebook can be allowed with a ``raises-exception`` tag on a single cell, or the ``allow_errors`` configurable option for all cells. An allowed error will be recorded in notebook output, and execution will continue.

If an error occurs when it is not explicitly allowed, a ``CellExecutionError`` will be raised.

If ``force_raise_errors`` is True, ``CellExecutionError`` will be raised for any error that occurs while executing the notebook. This overrides both the ``allow_errors`` option and the ``raises-exception`` cell tags.

Configurable kernel managers when executing notebooks

The kernel manager can now be optionally passed into the ``ExecutePreprocessor.preprocess`` and the ``executenb`` functions as the keyword argument ``km``. This means that the kernel can be configured as desired before beginning preprocessing.

This is useful for executing in a context where the kernel has external dependencies that need to be set to non-default values. An example of this might be a Spark kernel where you wish to configure the Spark cluster location ahead of time without building a new kernel.

Overall the ExecutePreprocessor has been reworked to make it easier to use. Future releases will continue this trend to make this section of the code more inheritable and reusable by others. We encourage you read the source code for this version if you're interested in the detailed improvements.

Surfacing exporters in front-ends

Exporters are now exposed for front-ends to consume, including classic notebook. As an example, this means that latex exporter will be made available for latex 'text/latex' media type from the Download As interface.

Raw Templates

Template exporters can now be assigned raw templates as string attributes by setting the ``raw_template`` variable.

.. code-block::

  class AttrExporter(TemplateExporter):

      # If the class has a special template and you want it defined within the class

      raw_template = """{%- extends 'rst.tpl' -%}

  {%- block in_prompt -%}

  raw template

  {%- endblock in_prompt -%}

      """

  exporter_attr = AttrExporter()

  output_attr, _ = exporter_attr.from_notebook_node(nb)

  assert "raw template" in output_attr

New command line flags

The ``--no-input`` will hide input cells on export. This is great for notebooks which generate "reports" where you want the code that was executed to not appear by default in the extracts.

An alias for ``notebook`` was added to exporter commands. Now ``--to ipynb`` will behave as ``--to notebook`` does.

Contributors

The following 35 authors contributed 329 commits.

* Anton Akhmerov

* Benjamin Ragan-Kelley

* berleon

* Correoso Garcia

* Damian Avila

* Danilo J. S. Bellini

* Doug Devine

* geniusupgrader

* Hagai Hargil

* Igor Mikushkin

* Josh Barnes

* Leo Gallucci

* Lukasz Mitusinski

* M Pacer

* Marco Rossi

* Matthew Petroff

* Matthew Seal

* Matthias Bussonnier

* Matthias Geier

* Michael Droettboom

* Mike Driscoll

* Oliver Evans

* oscar6echo

* pacahon

* Paul Ivanov

* Roger Labbe

* Sally Wilsak

* Saul Shanabrook

* Steven Silvester

* Sylvain Corlay

* Thomas Kluyver

* Todd

* Tyler Makaro

* Vidar Tonaas Fauske

* Ya'aqov (James) Walker

Best,

the many many Jupyter contributors who helped improve the project!

[Matthias Bussonnier]

Awesome and Congratulation !

Please give a round of applause for Matthew Seal who recently got commit right to nbconvert, and just did his first release !

Thanks for the good work !

-- 

Matthias

--
You received this message because you are subscribed to the Google Groups "Project Jupyter" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jupyter+u...@googlegroups.com.
To post to this group, send email to jup...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jupyter/f0728fe4-aae9-468f-9b5c-bab8b99ab888%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Brian Granger]

Matthew, many thanks for all your work on nbconvert and congrats to everyone who helped out!

--
You received this message because you are subscribed to the Google Groups "Project Jupyter" group.
To unsubscribe from this group and stop receiving emails from it, send an email to jupyter+u...@googlegroups.com.
To post to this group, send email to jup...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/jupyter/f0728fe4-aae9-468f-9b5c-bab8b99ab888%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

Brian E. Granger
Associate Professor of Physics and Data Science
Cal Poly State University, San Luis Obispo
@ellisonbg on Twitter and GitHub
bgra...@calpoly.edu and elli...@gmail.com

[Damián Avila]

Congrats!!! Really nice to see a new release for nbconvert.

Thanks Matthew!

To view this discussion on the web visit https://groups.google.com/d/msgid/jupyter/CAH4pYpQkpgPS_TEtGiaAL_LVxDK-F%2BrQ3gVEjdH7HJn33WGCXg%40mail.gmail.com.

For more options, visit https://groups.google.com/d/optout.

--

Damián Avila

[Matthias Geier]

Thanks for the recent increase in activity and for the new release!

Sadly, it looks like the "raises-exception" feature kept the
inconsistency between its name and its behavior, right?
It would have been nice to consider my issue at
https://github.com/jupyter/nbconvert/issues/730.

Also, the new system for configurable kernels broke my "nbsphinx"
module, see https://github.com/spatialaudio/nbsphinx/issues/202.
The error is already reported in
https://github.com/jupyter/nbconvert/issues/878.
I have for now disabled version 5.4 and will try to make a release
later this day in order not to cause too much disruption due to the
new nbconvert release.

cheers,
Matthias