importnb imports notebooks as modules. Notebooks are reusable as tests, source code, importable modules, and command line utilities.
Installation
pip install importnb
conda install -c conda-forge importnb
importnb for testing
After importnb is installed, pytest will discover and import notebooks as tests.
pytest index.ipynb
importnb imports notebooks as python modules, it does not compare outputs like nbval.
importnb now captures doctests in every Markdown cell & block string expression. The docstrings are tested with the --doctest-modules flag.
pytest index.ipynb --doctest-modules
It is recommended to use importnb with --nbval and the --monotonic flag that checks if has notebook has be restarted and re-run.
pytest index.ipynb --nbval --monotonic
importnb for the commmand line
importnb can run notebooks as command line scripts. Any literal variable in the notebook, may be applied as a parameter from the command line.
ipython -m importnb -- index.ipynb --foo "A new value"
importnb for Python and IPython
It is suggested to execute importnb-install to make sure that notebooks for each IPython session.
Restart and run all or it didn't happen.
importnb excels in an interactive environment and if a notebook will Restart and Run All then it may reused as python code. The Notebook context manager will allow notebooks with valid names to import with Python.
from importnb import NotebookFor brevity
with __import__('importnb').Notebook():
import readme
importnb.loaderwill find notebooks available anywhere along thesys.path.
or explicity
from importnb import Notebook
with Notebook():
import readme foo = 42
with Notebook():
import readme
if __name__ == '__main__':
assert readme.foo == 42
assert readme.__file__.endswith('.ipynb')Modules may be reloaded
The context manager is required to reload a module.
from importlib import reload
with Notebook(): __name__ == '__main__' and reload(readme)Lazy imports
The lazy option will delay the evaluation of a module until one of its attributes are accessed the first time.
with Notebook(lazy=True):
import readmeFuzzy File Names
if __name__ == '__main__':
with Notebook():
import __a_me
assert __a_me.__file__ == readme.__file__Python does not provide a way to import file names starting with numbers of contains special characters. importnb installs a fuzzy import logic to import files containing these edge cases.
import __2018__6_01_A_Blog_Post
will find the first file matching *2018*6?01?A?Blog?Post. Importing Untitled314519.ipynb could be supported with the query below.
import __314519
Docstring
The first markdown cell will become the module docstring.
if __name__ == '__main__':
print(readme.__doc__.splitlines()[0])__importnb__ imports notebooks as modules. Notebooks are reusable as tests, source code, importable modules, and command line utilities.
Meaning non-code blocks can be executeb by doctest.
if __name__ == '__main__':
__import__('doctest').testmod(readme)Import notebooks from files
Notebook names may not be valid Python paths. In this case, use Notebook.load.
>>> Notebook.load('changelog.ipynb')
<module 'changelog' from 'changelog.ipynb'>Import under the __main__ context.
>>> Notebook('__main__').load('changelog.ipynb')
<module 'changelog' from 'changelog.ipynb'>Parameterize Notebooks
Literal ast statements are converted to notebooks parameters.
In readme, foo is a parameter because it may be evaluated with ast.literal_val
if __name__ == '__main__':
from importnb.parameterize import Parameterize
f = Parameterize.load(readme.__file__)The parameterized module is a callable that evaluates with different literal statements.
if __name__ == '__main__':
assert callable(f)
f.__signature__
assert f().foo == 42
assert f(foo='importnb').foo == 'importnb'Run Notebooks from the command line
Run any notebook from the command line with importnb. Any parameterized expressions are available as parameters on the command line.
ipython -m importnb -- index.ipynb --foo "The new value"Integrations
IPython
IPython Extension
Avoid the use of the context manager using loading importnb as IPython extension.
%load_ext importnb%unload_ext importnb will unload the extension.
Default Extension
importnb may allow notebooks to import by default with
importnb-installIf you'd like to play with source code on binder then you must execute the command above. Toggle the markdown cell to a code cell and run it.
This extension will install a script into the default IPython profile startup that is called each time an IPython session is created.
Uninstall the extension with importnb-uninstall.
Run a notebook as a module
When the default extension is loaded any notebook can be run from the command line. After the importnb extension is created notebooks can be execute from the command line.
ipython -m readmeIn the command line context, __file__ == sys.argv[0] and __name__ == '__main__' .
See the deploy step in the travis build.
Parameterizable IPython commands
Installing the IPython extension allows notebooks to be computed from the command. The notebooks are parameterizable from the command line.
ipython -m readme -- --helppy.test
importnb installs a pytest plugin when it is setup. Any notebook obeying the py.test discovery conventions can be used in to pytest. This is great because notebooks are generally your first test.
ipython -m pytest -- srcWill find all the test notebooks and configurations as pytest would any Python file.
Setup
To package notebooks add recursive-include package_name *.ipynb
Developer
Format and test the Source Code
if __name__ == '__main__':
if globals().get('__file__', None) == __import__('sys').argv[0]:
print(foo, __import__('sys').argv)
else:
!ipython -m pytest -- --cov=importnb --flake8 --isort --black tests
!jupyter nbconvert --to markdown --stdout index.ipynb > readme.md�[22;0t�]0;IPython: deathbeds/importnb��[1m========================================== test session starts ==========================================�[0m
platform linux -- Python 3.8.1, pytest-5.3.2, py-1.8.1, pluggy-0.13.1 -- /home/weg/projects/deathbeds/importnb/envs/importnb-dev/bin/python
cachedir: .pytest_cache
rootdir: /home/weg/projects/deathbeds/importnb, inifile: tox.ini
plugins: isort-0.3.1, black-0.3.7, flake8-1.0.4, cov-2.8.1, importnb-0.6.0
collected 22 items �[0m
tests/foobar.py::FLAKE8 �[33mSKIPPED�[0m�[33m [ 4%]�[0m
tests/foobar.py::BLACK �[33mSKIPPED�[0m�[33m [ 9%]�[0m
tests/foobar.py::ISORT �[33mSKIPPED�[0m�[33m [ 13%]�[0m
tests/test_importnb.ipynb::test_basic �[32mPASSED�[0m�[32m [ 18%]�[0m
tests/test_importnb.ipynb::test_package �[32mPASSED�[0m�[32m [ 22%]�[0m
tests/test_importnb.ipynb::test_reload �[32mPASSED�[0m�[32m [ 27%]�[0m
tests/test_importnb.ipynb::test_docstrings �[32mPASSED�[0m�[32m [ 31%]�[0m
tests/test_importnb.ipynb::test_docstring_opts �[32mPASSED�[0m�[32m [ 36%]�[0m
tests/test_importnb.ipynb::test_from_file �[32mPASSED�[0m�[32m [ 40%]�[0m
tests/test_importnb.ipynb::test_lazy �[32mPASSED�[0m�[32m [ 45%]�[0m
tests/test_importnb.ipynb::test_module_source �[32mPASSED�[0m�[32m [ 50%]�[0m
tests/test_importnb.ipynb::test_main �[32mPASSED�[0m�[32m [ 54%]�[0m
tests/test_importnb.ipynb::test_object_source �[32mPASSED�[0m�[32m [ 59%]�[0m
tests/test_importnb.ipynb::test_python_file �[32mPASSED�[0m�[32m [ 63%]�[0m
tests/test_importnb.ipynb::test_cli �[32mPASSED�[0m�[32m [ 68%]�[0m
tests/test_importnb.ipynb::test_parameterize �[32mPASSED�[0m�[32m [ 72%]�[0m
tests/test_importnb.ipynb::test_minified_json �[32mPASSED�[0m�[32m [ 77%]�[0m
tests/test_importnb.ipynb::test_fuzzy_finder �[32mPASSED�[0m�[32m [ 81%]�[0m
tests/test_importnb.ipynb::test_remote �[32mPASSED�[0m�[32m [ 86%]�[0m
tests/foobaz/__init__.py::FLAKE8 �[33mSKIPPED�[0m�[32m [ 90%]�[0m
tests/foobaz/__init__.py::BLACK �[33mSKIPPED�[0m�[32m [ 95%]�[0m
tests/foobaz/__init__.py::ISORT �[33mSKIPPED�[0m�[32m [100%]�[0mCoverage.py warning: Module importnb was previously imported, but not measured (module-not-measured)
----------- coverage: platform linux, python 3.8.1-final-0 -----------
Name Stmts Miss Cover
-----------------------------------------------------------
src/importnb/__init__.py 5 0 100%
src/importnb/__main__.py 6 2 67%
src/importnb/_version.py 1 0 100%
src/importnb/completer.py 54 54 0%
src/importnb/decoder.py 56 7 88%
src/importnb/docstrings.py 43 7 84%
src/importnb/finder.py 62 8 87%
src/importnb/ipython_extension.py 70 39 44%
src/importnb/loader.py 159 31 81%
src/importnb/parameterize.py 95 12 87%
src/importnb/remote.py 49 8 84%
src/importnb/utils/__init__.py 1 1 0%
src/importnb/utils/export.py 33 33 0%
src/importnb/utils/ipython.py 47 47 0%
src/importnb/utils/nbdoctest.py 32 32 0%
src/importnb/utils/pytest_importnb.py 32 19 41%
src/importnb/utils/setup.py 52 52 0%
-----------------------------------------------------------
TOTAL 797 352 56%
�[32m===================================== �[32m�[1m16 passed�[0m, �[33m6 skipped�[0m�[32m in 1.58s�[0m�[32m =====================================�[0m
[NbConvertApp] Converting notebook index.ipynb to markdown
if __name__ == '__main__':
try:
from IPython.display import display, Image
from IPython.utils.capture import capture_output
from IPython import get_ipython
with capture_output():
get_ipython().system("cd docs && pyreverse importnb -opng -pimportnb")
display(Image(url='docs/classes_importnb.png', ))
except: ...