This meta-project provides an easy way to install all of the python tools I typically use. It also serves as a fairly minimal example of setting up a package the pip can install, and specifying dependencies.
In particular, I structure it for the following use-cases:
- Directly from PyPIpip install --process-dependency-links --user mmf_setup[nbextensions]
pip install --process-dependency-links --user hg+https://bitbucket.org/mforbes/mmf_setup[nbextensions]
From Local Source (Run this from the source directory after you unpack it.)pip install --process-dependency-links --user .[nbextnensions]
Note: these can be run without the --user flag if you want to install them system-wide rather than into site.USER_BASE.
To get the notebook tools for Jupyter (IPython) notebooks, execute the following as a code cell in your notebook and then trust the notebook with File/Trust Notebook:
import mmf_setup; mmf_setup.nbinit()
This will download and enable the calico extensions, as well as set the theme which is implemented in the output cell so it is stored for use online such as when rendered through NBViewer. One can specify different themes. (Presently only theme='default' and theme='mmf' are supported.)
To use the mercurial notebook cleaning tools, simply source the mmf_setup script:
. mmf_setup -v
To do this automatically when you login, add this line to your ~/.bashc or ~/.bash_profile scripts. These can also be enabled manually by adding the following to your ~/.hgrc file:
[extensions] strip= mmf_setup.nbclean=$MMF_UTILS/nbclean.py
where $MMF_UTILS expands to the install location for the package (which can be seen by running mmf_setup -v).
This will provide commands for committing clean notebooks such as hg cstatus, hg cdiff and hg ccommit.
import mmf_setup.notebook_configuration mmf_setup.notebook_configuration.install_extensions()
If you source the output of the mmf_setup script:
then your HGRCPATH will be amended to include this projects hgrc file which does the following:
Adds some useful extensions.
Adds the following commands:
hg lga (or hg lg): provides a nice concise graphical display of the repo.
hg cstatus (or hg cst):
hg cdiff: same for hg diff
hg cediff: same for hg ediff
hg crecord: same for hg record. Note, this does not function like commit - it will not record the notebooks with the full output.
hg ccommit (or hg ccom): same for hg com but also commits the full version of the notebooks with output as a new node off the present node with the message ..: Automatic commit of output. This command has two behaviours depending on the configuration option nbclean.output_branch. If this is not set:
[nbclean] output_branch =
then hg ccommit will commit a cleaned copy of your notebooks with the output stripped, and then will commit the full notebook with output (provided that the notebooks have output) as a new head:
| o 4: test ...: Automatic commit with .ipynb output |/ @ 3: test ccommit 3 | | o 2: test ...: Automatic commit with .ipynb output |/ o 1: test ccommit 1 | o 0: test commit 0
The parent will always be set to the clean node so that the output commits can be safely stripped from your repository if you choose not to keep them.
The other mode of operation can be enabled by specifying a name for the output branch:
[nbclean] output_branch = auto_output
This will merge the changes into a branch with the specified name:
| o 4: test ...: Automatic commit with .ipynb output (...) auto_output |/| @ | 3: test ccommit 3 | | | o 2: test ...: Automatic commit with .ipynb output (...) auto_output |/ o 1: test ccommit 1 | o 0: test commit 0
This facilitates stripping the output hg strip 2 for example will remove all output. It also allows you to track the changes in the output.
There are a couple of subtle points here that should be mentioned.
Various notes about python, IPython, etc. are stored in the docs folder.