Import .ipynb files as modules in the system path.
Project description
importnb imports notebooks as modules & packages.
pip install importnb
conda install -c conda-forge importnb
importnb
works in Python and IPython
Use the Notebook
context manager.
For brevity
importnb.loader
will find notebooks available anywhere along the sys.path
.
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)
Partial loading
The importnb.loader.Partial
will import a notebook even if there is an exception. The exception is found on module.__exception
.
from importnb import Partial
with Partial():
import readme
Lazy imports
The importnb.loader.Lazy
will delay the evaluation of a module until one of its attributes are accessed the first time.
with Notebook(lazy=True):
import readme
Capture Outputs
importnb
can capture the stdout
, stderr
, and display
in the context manager.
with Notebook(stdout=True, stderr=True, display=True) as output:
import readme
Docstring
The first cell is the module docstring.
if __name__ == '__main__':
print(readme.__doc__.splitlines()[0])
__importnb__ imports notebooks as modules & packages.
Import notebooks from files
Notebook names may not be valid Python paths. In this case, use Notebook.from_filename
.
Notebook.from_filename('readme.ipynb')
Import under the __main__
context.
Notebook.from_filename('readme.ipynb', main=True)
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
from importnb import Parameterize
f = Parameterize(readme)
The parameterized module is a callable that evaluates with different literal statements.
assert callable(f)
f.__signature__
<Signature (*, foo=42)>
assert f().foo == 42
assert f(foo='importnb').foo == 'importnb'
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-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.
Setup
To package notebooks add recursive-include package_name *.ipynb
Watchdog
pip install importnb[watch]
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 oftricks.yaml
Developer
Format and test the Source Code
if __name__ == '__main__':
from pathlib import Path
from nbconvert.exporters.python import PythonExporter
from importnb.compile import export
for path in Path('src/notebooks/').rglob("""*.ipynb"""):
if 'checkpoint' not in str(path):
export(path, Path('src/importnb') / path.with_suffix('.py').relative_to('src/notebooks'))
__import__('unittest').main(module='src.importnb.tests.test_unittests', argv="discover --verbose".split(), exit=False)
test_import (src.importnb.tests.test_unittests.TestContext) ... ok
test_reload_with_context (src.importnb.tests.test_unittests.TestContext) ... ok
test_failure (src.importnb.tests.test_unittests.TestExtension) ... expected failure
test_import (src.importnb.tests.test_unittests.TestExtension) ... ok
test_exception (src.importnb.tests.test_unittests.TestPartial) ... ok
test_traceback (src.importnb.tests.test_unittests.TestPartial) ... ok
test_imports (src.importnb.tests.test_unittests.TestRemote) ... skipped 'requires IP'
----------------------------------------------------------------------
Ran 7 tests in 2.022s
OK (skipped=1, expected failures=1)
if __name__ == '__main__':
!jupyter nbconvert --to markdown readme.ipynb
[NbConvertApp] Converting notebook readme.ipynb to markdown
[NbConvertApp] Writing 7130 bytes to readme.md
if __name__ == '__main__':
from IPython.display import display, Image
!pyreverse importnb -opng -pimportnb
display(*map(Image, ('classes_importnb.png', 'packages_importnb.png')))
CHANGELOG
0.3.0
- Include
Partial
,Lazy
, andNotebookTest
loaders. - Transform markdown cells to literate block strings so they are included in the ast.
__doc__
's are extracted from the first markdown cell or normal source code from a code cell.
- Export the python source code with
black
. Notebook.from_filename
is a loader for paths and strings.- Add
importnb.nbtest
for notebook testing tools.. - Benchmark
importnb
against existing notebooks. - Include a
watchdog
trick to watch tests.. - Extend the project to >= 3.4
- Use nbviewer/github hierachy for the docs.
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
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.