New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document pre/post save hooks #327

Merged
merged 1 commit into from Aug 25, 2015
Jump to file or symbol
Failed to load files and symbols.
+77 −0
Diff settings

Always

Just for now

@@ -10,3 +10,4 @@ override the notebook's defaults with your own custom behavior.
:maxdepth: 2
contents
savehooks
@@ -0,0 +1,76 @@
File save hooks
===============
You can configure functions that are run whenever a file is saved. There are
two hooks available:
* ``ContentsManager.pre_save_hook`` runs on the API path and model with content.
This can be used for things like stripping output that people don't like
adding to VCS noise.
* ``FileContentsManager.post_save_hook`` runs on the filesystem path and model
without content. This could be used to commit changes after every save, for
instance.
They are both called with keyword arguments::
pre_save_hook(model=model, path=path, contents_manager=cm)
post_save_hook(model=model, os_path=os_path, contents_manager=cm)
Examples
--------
These can both be added to :file:`jupyter_notebook_config.py`.
A pre-save hook for stripping output::
def scrub_output_pre_save(model, **kwargs):
"""scrub output before saving notebooks"""
# only run on notebooks
if model['type'] != 'notebook':
return
# only run on nbformat v4
if model['content']['nbformat'] != 4:
return
for cell in model['content']['cells']:
if cell['cell_type'] != 'code':
continue
cell['outputs'] = []
cell['execution_count'] = None
c.FileContentsManager.pre_save_hook = scrub_output_pre_save
A post-save hook to make a script equivalent whenever the notebook is saved
(replacing the ``--script`` option in older versions of the notebook)::
import io
import os
_script_exporter = None
def script_post_save(model, os_path, contents_manager, **kwargs):
"""convert notebooks to Python script after save with nbconvert
replaces `ipython notebook --script`
"""
from nbconvert.exporters.script import ScriptExporter
if model['type'] != 'notebook':
return
global _script_exporter
if _script_exporter is None:
_script_exporter = ScriptExporter(parent=contents_manager)
log = contents_manager.log
base, ext = os.path.splitext(os_path)
py_fname = base + '.py'
script, resources = _script_exporter.from_filename(os_path)
script_fname = base + resources.get('output_extension', '.txt')
log.info("Saving script /%s", to_api_path(script_fname, contents_manager.root_dir))
with io.open(script_fname, 'w', encoding='utf-8') as f:
f.write(script)
c.FileContentsManager.post_save_hook = script_post_save
This could be a simple call to ``jupyter nbconvert --to script``, but spawning
the subprocess every time is quite slow.
ProTip! Use n and p to navigate between commits in a pull request.