Package: nbsmoke
nbsmokeBuild StatusCoverageLatest dev releaseLatest releasePythonBasic notebook smoke tests: Do they run ok? Do they contain lint?ThisPytestplugin was generated
withCookiecutteralong with@hackebrot'sCookiecutter-pytest-plugintemplate.InstallationYou can install nbsmoke viapipfromPyPI:$ pip install nbsmokeOr get the latest pre-release:$ pip install --pre nbsmokenbsmoke is also available viacondafromanaconda.org:$ conda install -c conda-forge nbsmokeUsageCheck all notebooks run without errors:$ pytest --nbsmoke-runCheck all notebooks run without errors, and store html to look at
afterwards:$ pytest --nbsmoke-run --store-html=/scratchLint check notebooks:$ pytest --nbsmoke-lintLint failures as warnings only:$ pytest --nbsmoke-lint --nbsmoke-lint-onlywarnInstead of all files in a directory, you can specify a list e.g.:$ pytest --nbsmoke-run notebooks/Untitled*.ipynbIf you want to restrict pytest to running only your notebook tests, use
-k, e.g.:$ pytest --nbsmoke-run -k ".ipynb"Additional options are available by standard pytest 'ini' configuration
in setup.cfg, pytest.ini, or tox.ini:[pytest]
# when running, seconds allowed per cell (see nbconvert timeout)
nbsmoke_cell_timeout = 600

# notebooks to skip running; one case insensitive re to match per line
nbsmoke_skip_run = ^.*skipme\.ipynb$
                   ^.*skipmetoo.*$

# case insensitive re to match for file to be considered notebook;
# defaults to ``^.*\.ipynb``
it_is_nb_file = ^.*\.something$

# flakes you don't want to hear about (regex)
nbsmoke_flakes_to_ignore = .*hvplot.* imported but unused.*

# line magics to treat as being flakes (i.e. magics you don't want in your notebooks)
nbsmoke_flakes_line_magics_blacklist = pylab

# cell magics to treat as being flakes (i.e. magics you don't want in your notebooks)
nbsmoke_flakes_cell_magics_blacklist = bash
                                       ruby

# add your own magic handlers (python file containing line_magic_handlers and cell_magic_handlers as dictionaries magic_name: callable)
nbsmoke_magic_handlers = path/to/file.pynbsmoke supports# noqacomments to mark that something should be
ignored during lint checking.Thenbsmoke_skip_runlist in a project's config can be ignored by
passing--ignore-nbsmoke-skip-run(useful if sometimes you want to run
all notebooks for a project where many are typically skipped).What's the point?Although more sophisticated testing of notebooks is possible (e.g. see
nbval), just checking that notebooks run from start to finish without
error in a fresh kernel (or on a neutral CI service) can be useful
during development. Practical experience of working on several projects
with notebooks confirms this, but that's all the evidence I have.Checking notebooks for lint might seem trivial/pointless, but it
frequently uncovers unused names (typically unused imports). It's also
quite common to find python 2 vs 3 problems, and sometimes undefined
names - in a way that's faster than running the notebook (over multiple
versions of python).Unused imports/names themselves might seem trivial, but they can hinder
understanding of a notebook by readers, or add dependencies that are not
required.Hopefully you don't have mysterious (unused) imports in your notebook,
but if you do, you can add# noqa: explanationto stop flake errors.
E.g. if you're importing something for its side effects, it's very
helpful to inform the reader of that.Pyflakes is used as the underlying linter because "Pyflakes makes a
simple promise: it will never complain about style, and it will try
very, very hard to never emit false positives."ContributingFirst, install usingpip install -e .. Then run the tests usingtoxorpytest -v tests/.New release to PyPI:git tag -a vX.Y.Z -m "Something about release" && git push --tags.
Then a PR will auto-open on conda-forge, which should be merged.Get some help to debug apparently incorrect flakes by adding--nbsmoke-lint-debug, e.g.pytest -v --nbsmoke-lint --nbsmoke-lint-debug examples.LicenseDistributed under the terms of theBSD-3license, "nbsmoke"
is free and open source software.IssuesIf you encounter any problems, pleasefile an
issue(ideally including a
copy of any problematic notebook).