%pypath: An IPython magic for manipulating your Python path
Edit: Now with support for Python 3!
You're a pragmatic Python developer, so you extract the logically related bits of your code into functions and group those functions together into modules.
Now, how do you actually import those modules? If you're in the directory containing those modules, you're good to go:
In [1]: %ls # Desired files are in the same directory.
data_wranglers.py
plot_helpers.py
In [2]: from plot_helpers import plot_slope_marker
[Success]
If, instead, those files are located elsewhere, you might get something like this:
In [3]: %ls path/to/my-utils # Desired files are somewhere else.
data_wranglers.py
plot_helpers.py
In [4]: from plot_helpers import plot_slope_marker
---------------------------------------------------------------------------
ImportError Traceback (most recent call last)
<ipython-input-141-1d0fef5fa475> in <module>()
----> 1 from plot_helpers import plot_slope_marker
ImportError: No module named plot_helpers
Quickfix: sys.path
The quick fix here is to append to sys.path:
In [3]: import sys
In [4]: sys.append('path/to/my-utils')
In [5]: from plot_helpers import plot_slope_marker
[Success]
But, the next time you fire up python, you get the same ImportError we saw above.
Persistent changes to your path
To make persistent changes to your Python path, you'll have to tweak your PYTHONPATH or figure out how to add '*.pth' files to your site-packages directory.
These solutions are annoying for most users and downright intimidating to newer developers. With %pypath, you can easily manipulate your Python path from IPython.
How to use pypath_magic
The pypath_magic module adds an IPython magic (err... Jupyter magic?) command for easily manipulating your Python path.
Load the extension
To use the %pypath magic command, just load the extension from an IPython session:
In [1]: %load_ext pypath_magic
List the custom paths
After loading, you will have access to the %pypath magic. You can type:
In [2]: %pypath
to list all the custom paths added by pypath-magic. When you get started, you won't have anything there.
Add to your Python path
To add some custom paths, just change to a directory and call %pypath -a:
In [3]: %cd path/to/my-utils
In [4]: %ls
data_wranglers.py
plot_helpers.py
In [5]: %pypath -a
Added u'/absolute/path/to/my-utils' to path.
In [6]: %pypath
0. /absolute/path/to/my-utils
Now you can reuse those helper functions from anywhere:
In [7]: from plot_helpers import plot_slope_marker
Changes to your Python path will persist across IPython sessions, and those paths will be available outside of IPython.
Deleting one of your custom paths
If you later want to delete a directory from your path, just use %pypath -d:
In [8]: %cd path/to/my-utils
In [9]: %pypath -d
Deleted u'/absolute/path/to/my-utils' from path.
List everything in your Python path
You can also list your entire Python path with %pypath -l:
In [10]: %pypath -l
/Users/tonysyu/code/yutils
/Users/tonysyu/code/skimage
/Users/tonysyu/code/mpl/lib
/Users/tonysyu/code/ipython
/Users/tonysyu/code/deli
/Users/tonysyu/code/mpltools
/Applications/Canopy.app/appdata/canopy-1.4.1.1975.macosx-x86_64/Canopy.app/Contents/lib/python27.zip
/Applications/Canopy.app/appdata/canopy-1.4.1.1975.macosx-x86_64/Canopy.app/Contents/lib/python2.7
...
/absolute/path/to/my-utils
Adding and deleting using arguments
Finally, you can manipulate paths---without changing to those directories---by passing arguments to the add and delete commands.
First we add paths using relative or absolute directory paths:
In [11]: %pypath -a path/to/useful-modules
Added u'/absolute/path/to/useful-modules' to path.
In [12]: %pypath -a /absolute/path/to/stuff
Added u'/absolute/path/to/stuff' to path.
In [13]: %pypath -a path/to/things
Added u'/absolute/path/to/things' to path.
In [14]: %pypath
0. /absolute/path/to/useful-modules
1. /absolute/path/to/stuff
2. /absolute/path/to/things
Notice those numbers in the list above. We can use those indices to delete paths, or we can delete using string paths:
In [15]: %pypath -d 1
Deleted u'/absolute/path/to/stuff' from path.
In [16]: %pypath
0. /absolute/path/to/useful-modules
1. /absolute/path/to/things
In [17]: %pypath -d path/to/useful-modules
Deleted u'/absolute/path/to/useful-modules' from path.
In [18]: %pypath
0. /absolute/path/to/things
How it works
The basic idea is really simple: The pypath command just maintains a custom *.pth file in your site-packages directory. Altering that file alters the paths in the Python path. Since this is a custom *.pth file, you don't have to worry about screwing up packages installed by other means.
Install
To install using pip, just type the following in a terminal:
$ pip install pypath_magic
Or if you're feeling lucky:
$ pip install git+https://github.com/tonysyu/pypath-magic
Or if you want to go direct to the source:
$ git clone https://github.com/tonysyu/pypath-magic.git $ cd pypath-magic $ python setup.py install
Dependencies
- Python 2.7/3.4 (older versions probably work, but this is not tested)
- IPython >= 1.0
License
New BSD (a.k.a. Modified BSD). See LICENSE file in this directory for details.
Comments
comments powered by Disqus