importnb 0.2.5

Import .ipynb files as modules in the system path.

importnb imports notebooks as modules & packages.

pip install importnb

importnb works in Python and IPython

Use the Notebook context manager.

For brevity

    with __import__('importnb').Notebook(): 
        import readme

or explicity

    from importnb import Notebook
    with Notebook(): 
        import readme

    foo = 42
    import readme
    assert readme.foo is 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():
        reload(readme)

Integrations

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-install

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-install.

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 readme

See the deploy step in the travis build.

py.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.

Setuptools

importnb provides a setuptool command that will place notebooks in a source distribution. In setuptools, update the command classs with

from importnb.utils.setup import build_ipynb
setup(
    ...,
    cmdclass=dict(build_py=build_ipynb)
    ...,)

Watchdog

importnb exports a watchdog trick to watch files and apply command like operations on their module path.

Tricks File

For example, create a file called tricks.yaml containing

tricks:
- importnb.utils.watch.ModuleTrick:
      patterns: ['*.ipynb']
      shell_command: ipython -m ${watch_dest_path}

Run the watcher in a terminal

watchmedo tricks tricks.yaml

tricks.yaml is a concrete implementation of tricks.yaml

Developer

• Tests
• Source Notebooks
• Transpiled Python Source

Format and test the Source Code

    if __name__ == '__main__':
        from pathlib import Path
        import black
        from importnb.compiler_python import ScriptExporter
        for path in Path('src/notebooks/').rglob("""*.ipynb"""):
            if 'checkpoint' not in str(path):
                print(path)
                (Path('src/importnb') / path.with_suffix('.py').relative_to('src/notebooks')).write_text(
                black.format_str(ScriptExporter().from_filename(path)[0], 100))

        __import__('unittest').main(module='tests', argv="discover --verbose".split(), exit=False) 

src/notebooks/compiler_ipython.ipynb
src/notebooks/compiler_python.ipynb
src/notebooks/decoder.ipynb
src/notebooks/exporter.ipynb
src/notebooks/loader.ipynb
src/notebooks/utils/__init__.ipynb
src/notebooks/utils/ipython.ipynb
src/notebooks/utils/pytest_plugin.ipynb
src/notebooks/utils/setup.ipynb
src/notebooks/utils/watch.ipynb


test_import (tests.test_unittests.TestContext) ... ok
test_reload_with_context (tests.test_unittests.TestContext) ... ok
test_reload_without_context (tests.test_unittests.TestContext) ... skipped 'importnb is probably installed'
test_failure (tests.test_unittests.TestExtension) ... unexpected success
test_import (tests.test_unittests.TestExtension) ... ok
test_exception (tests.test_unittests.TestPartial) ... ok
test_traceback (tests.test_unittests.TestPartial) ... ok
test_imports (tests.test_unittests.TestRemote) ... skipped 'requires IP'

----------------------------------------------------------------------
Ran 8 tests in 1.013s

FAILED (skipped=2, unexpected successes=1)

Format the Github markdown files

    if __name__ == '__main__':
        from nbconvert.exporters.markdown import MarkdownExporter
        for path in map(Path, ('readme.ipynb', 'changelog.ipynb')):
            path.with_suffix('.md').write_text(MarkdownExporter().from_filename(path)[0])

Format the Github Pages documentation

We use /docs as the local_dir.

    if __name__ == '__main__':
        from nbconvert.exporters.markdown import MarkdownExporter
        files = 'readme.ipynb', 'changelog.ipynb', 'tests/test_importnb.ipynb'
        for doc in map(Path, files):
            to = ('docs' / doc.with_suffix('.md'))
            to.parent.mkdir(exist_ok=True)
            to.write_text(MarkdownExporter().from_filename(doc)[0])

CHANGELOG

0.2.4

• Use tox for testing
• Use a source directory folder structure for pytest and tox testing.
• Create a pytest plugin that discovers notebooks as tests. With importnb notebooks can be used as fixtures in pytest.
• Install importnb as an IPython extension.
• Support running notebooks as modules from the ipython command line
• Create a setuptools command to allow notebooks as packages.

0.2.1

• importnb supports notebook inputs from pure python environments. Two compatible compiler were created from IPython and Python

• importnb.Partial works appropriately by improving exceptions.

• All of the IPython magic syntaxes were removed to support Pure Python.

• The generated Python files are formatted with black.

• Tests were added to:

  • Validate the line number in tracebacks
  • Test someone elses notebooks

0.1.4

• Pypi supports markdown long_description with the proper mimetype in long_description_content_type.

0.1.3

• Include the RST files in the MANIFEST.in.

0.1.2 (Unreleased)

• Use RST files to improve the literacy of the pypi description.

0.1.1

• Released on PyPi

0.0.2

• Initial Testing Release