From e953107c0415285bf4862e6ba9dbb13895162a67 2011-12-18 02:27:03 From: Fernando Perez Date: 2011-12-18 02:27:03 Subject: [PATCH] Merge pull request #1168 from fperez/nbscript Add --script/--no-script flags as shorthands for the NotebookManager.save_script option. --- diff --git a/IPython/frontend/html/notebook/notebookapp.py b/IPython/frontend/html/notebook/notebookapp.py index 8fc6e3f..49132ec 100644 --- a/IPython/frontend/html/notebook/notebookapp.py +++ b/IPython/frontend/html/notebook/notebookapp.py @@ -52,7 +52,7 @@ from .handlers import (LoginHandler, LogoutHandler, ) from .notebookmanager import NotebookManager -from IPython.config.application import catch_config_error +from IPython.config.application import catch_config_error, boolean_flag from IPython.core.application import BaseIPythonApplication from IPython.core.profiledir import ProfileDir from IPython.lib.kernel import swallow_argv @@ -157,10 +157,15 @@ flags['read-only'] = ( """ ) +# Add notebook manager flags +flags.update(boolean_flag('script', 'NotebookManager.save_script', + 'Auto-save a .py script everytime the .ipynb notebook is saved', + 'Do not auto-save .py scripts for every notebook')) + # the flags that are specific to the frontend # these must be scrubbed before being passed to the kernel, # or it will raise an error on unrecognized flags -notebook_flags = ['no-browser', 'no-mathjax', 'read-only'] +notebook_flags = ['no-browser', 'no-mathjax', 'read-only', 'script', 'no-script'] aliases = dict(ipkernel_aliases) diff --git a/IPython/frontend/html/notebook/notebookmanager.py b/IPython/frontend/html/notebook/notebookmanager.py index f95b7c4..02295c4 100644 --- a/IPython/frontend/html/notebook/notebookmanager.py +++ b/IPython/frontend/html/notebook/notebookmanager.py @@ -27,12 +27,10 @@ from IPython.config.configurable import LoggingConfigurable from IPython.nbformat import current from IPython.utils.traitlets import Unicode, List, Dict, Bool - #----------------------------------------------------------------------------- -# Code +# Classes #----------------------------------------------------------------------------- - class NotebookManager(LoggingConfigurable): notebook_dir = Unicode(os.getcwd(), config=True, help=""" @@ -40,10 +38,12 @@ class NotebookManager(LoggingConfigurable): """) save_script = Bool(False, config=True, - help="""Also save notebooks as a Python script. + help="""Automatically create a Python script when saving the notebook. - For easier use of import/%loadpy across notebooks, a .py - script will be created next to any .ipynb on each save. + For easier use of import, %run and %loadpy across notebooks, a + .py script will be created next to any + .ipynb on each save. This can also be set with the + short `--script` flag. """ ) diff --git a/docs/source/interactive/htmlnotebook.txt b/docs/source/interactive/htmlnotebook.txt index b1b6849..a829419 100644 --- a/docs/source/interactive/htmlnotebook.txt +++ b/docs/source/interactive/htmlnotebook.txt @@ -187,15 +187,7 @@ entire contents of the file will be loaded into a single code cell. But if prior to import, you manually add the ``# 2`` marker at the start and then add separators for text/code cells, you can get a cleaner import with the file broken into individual cells. - -If you want use notebooks as scripts a lot, then you can set:: - - c.NotebookManager.save_script=True - -which will instruct the notebook server to save the ``.py`` export of each -notebook adjacent to the ``.ipynb`` at every save. Then these can be ``%run`` -or imported from regular IPython sessions or other notebooks. - + .. warning:: While in simple cases you can roundtrip a notebook to Python, edit the @@ -209,6 +201,48 @@ or imported from regular IPython sessions or other notebooks. notebook started. But the Python version is *not* an alternate notebook format. + +Importing or executing a notebook as a normal Python file +--------------------------------------------------------- + +The native format of the notebook, a file with a ``.ipynb`` extension, is a +JSON container of all the input and output of the notebook, and therefore not +valid Python by itself. This means that by default, you can not import a +notebook or execute it as a normal python script. But if you want use +notebooks as regular Python files, you can start the notebook server with:: + + ipython notebook --script + +or you can set this option permanently in your configuration file with:: + + c.NotebookManager.save_script=True + +This will instruct the notebook server to save the ``.py`` export of each +notebook adjacent to the ``.ipynb`` at every save. These files can be +``%run``, imported from regular IPython sessions or other notebooks, or +executed at the command-line as normal Python files. Since we export the raw +code you have typed, for these files to be importable from other code you will +have to avoid using syntax such as ``%magics`` and other IPython-specific +extensions to the language. + +In regular practice, the standard way to differentiate importable code from the +'executable' part of a script is to put at the bottom:: + + if __name__ == '__main__': + # rest of the code... + +Since all cells in the notebook are run as top-level code, you'll need to +similarly protect *all* cells that you do not want executed when other scripts +try to import your notebook. A convenient shortand for this is to define early +on:: + + script = __name__ == '__main__': + +and then on any cell that you need to protect, use:: + + if script: + # rest of the cell... + Keyboard use ------------