Skip to main content

nosebook

Build Status PyPI BSD

a nose plugin for finding and running IPython 2/3 notebooks as nose tests.

What it can’t do in terms of setup and tearDown, nosebook makes up for in simplicity: there is no %%nose magic, no metadata required: the notebook on disk is the “gold master”.

This makes it ideal for decreasing the burden of keeping documentation up to date with tests by making a single set of notebooks into both rich, multi-format documentation and a simple part of your test suite.

How does it work?

Each notebook found according to `nosebook-match <#nosebook-match>`__ is started with a fresh kernel, based on the kernel specified in the notebook. If the kernel is not installed, no tests will be run and the error will be logged.

Each code cell that matches `nosebook-match-cell <#nosebook-match-cell>`__ will be executed against the kernel in the order in which it appears in the notebook: other cells e.g. markdown, raw, are ignored.

The number and content of outputs has to match exactly, with the following parts of each output stripped:

  • execution/prompt numbers, i.e. [1]:

  • tracebacks

Non-deterministic output, such as with _repr_ methods that include the memory location of the instance, will obviously not match every time. You can use `nosebook-scrub <#nosebook-scrub>`__ to rewrite or remove offending content.

Configuring nosetests to use nosebook

These options can be specified in your nose config file, or as long-form command line arguments, i.e. --with-nosebook.

with-nosebook

nosetests will look for notebooks that seem like tests, as configured with `nosebook-match <#nosebook-match>`__.

Default: False

# Basic usage
!nosetests --with-nosebook

nosebook-match

A regular expression that tells nosebook what should be a testable notebook.

Default: ``.*[Tt]est..ipynb$``*

# Run against all notebooks... probably not a good idea, but maybe a great idea
!nosetests --with-nosebook --nosebook-match .*.ipynb

nosebook-match-cell

A regular expression that will be replaced throughout the expected outputs and generated outputs.

Default: None

# will run cells where tests are defined... but you should probably run them, too
!nosetests --with-nosebook --nosebook-match .*Simple.* --nosebook-match-cell '(def|class).*[Tt]est'

nosebook-scrub

A regular expression that will be replaced throughout the expected outputs and generated outputs.

Default: None

# you can't fail if you don't try
!nosetests --with-nosebook --nosebook-scrub .+

For multiple scrub values, you can pass a JSON-formatted list of regular expressions or object of pattern-replacement pairs that will be replaced. When passed in via the command line, you’ll have to escape special characters: using a .noserc config file makes this easier.

# there are only 10 kinds of tests...
!nosetests --with-nosebook --nosebook-scrub='["0", "1"]'
# 0 is equally good
!nosetests --with-nosebook --nosebook-scrub='{"\\d+": "0"}'

Contributing

Issues and pull requests welcome!

License

nosebook is released as free software under the BSD 3-Clause license.

Metadata

Release files for nosebook 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nosebook 0.4.0
File Size Uploaded
nosebook-0.4.0.tar.gz 9.4 kB Details

Built distribution (wheel)

Table of built distributions (wheels) for nosebook 0.4.0
File Interpreter ABI Platform
nosebook-0.4.0-py2.py3-none-any.whl Python 2, Python 3 none any Details

Total release size: 18.3 kB

Release files / nosebook-0.4.0.tar.gz

Download URL nosebook-0.4.0.tar.gz
Size 9.4 kB
Tags Source
SHA-256 checksum
How to use checksums
f1ceefe3eaae5c3c69ef4702a1318171b0a1d08ec8716f10306a0df6bc4876bd
BLAKE2b-256 checksum
How to use checksums
055ccf0416989ecbb237319049268f2ea62499099d7d4ee7488ab854f1d25ca2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Release files / nosebook-0.4.0-py2.py3-none-any.whl

Download URL nosebook-0.4.0-py2.py3-none-any.whl
Size 9.0 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
0dae949e62670425bbc477643afa6a80334521d90e8471b6eeced1c92dc35625
BLAKE2b-256 checksum
How to use checksums
d578e45864e6a61ff83ecfa5b772a8b8836683a0a326da6cfc887b2c62434619
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No

Release history Release notifications | RSS feed

This release

0.4.0 This release

2 release files

0.3.0

2 release files

0.2.0

2 release files

0.1.0

2 release files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page