(Note: See the bottom of this post for updates)
I was honored to to give my “Emacs for Python Programming” talk at the inaugural PyCarolinas conference. The conference was a huge success in every way, thanks to the efforts of Calvin Spealman, et. al. I promised that I would post my Emacs setup, so here it is.
Step 0: Prerequisites
This may work with other setups, but here’s what I tested:
Step 1: Clear out any previous customization
As evidenced by the numerous blog posts documenting how to set this up, it’s not straightforward. I recommend starting from scratch to make sure everything is set up properly. Once you have it working, then you can customize it. Make sure to start these commands in your home directory.
Step 2: Set up initial Emacs configuration
Create an empty
.emacs.d directory and a subdirectory named with your
username. My username is
vinod, so we’ll create a directory
.emacs.d/vinod/. The emacs-starter-kit tells emacs
to automatically load any elisp files from that special directory, so
you’ll always have a place to drop custom elisp files.
Create a file named
.emacs.d/init.el with the following contents:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
Step 3: Create a python virtualenv
We’ll keep all the python-side customization in a virtualenv named
default. It’s important that the name you choose is the same as the
name in the
(virtualenv-workon) command in line 45 of Step 2.
After it does its thing, your shell prompt should change, indicating that your new virtualenv is activated
Step 4: Install Pymacs
Pymacs is a really cool
piece of software that sets up a 2 way communication between Emacs and
Python, allowing you to control Emacs with python commands rather than
elisp commands. It requires a python piece (
Pymacs.py) and an Emacs
pymacs.el). Unfortunately, they’re not installable via
package.el, but installation is easy enough.
1 2 3 4 5 6 7 8 9 10 11 12 13
Step 5: Install other python packages
These helper packages are easier to install:
The pyflakes and pep8 packages check your code as you type using Emacs’ flymake mode. Now, deactivate your virtualenv.
Step 6: Install pycheckers
Flymake is the part of Emacs that checks your code for errors on the
fly. It calls a shell script called
pycheckers, so you need to have
a script by that name in your shell’s
PATH. Here’s mine
1 2 3 4 5
Step 7: Install python-mode.el
As I mentioned in my talk, there are multiple Python modes available, but I recommend using the one named python-mode.el, which is developed at http://launchpad.net/python-mode. It does periodically get uploaded to Marmalade, but the auto-completion using pycomplete doesn’t work well on the version that is there now (6.0.10), so I recommend that you manually download and install the latest stable version (6.0.12). I’ll update this post once a stable working version gets uploaded to Marmalade or Melpa.
Step 8: Test it all out
Launch emacs and open a python file named
test.py. Type the following:
import os os.path.jo
Wait at this point. You should see auto-completion of
followed shortly by a yellow popup showing documentation of that method.
Hitting return should accept the completion. Then type
( and you
should see the method signature in the minibuffer.
Move the cursor over any letter in
join. Hit ‘F1’. A window should
popup with the docstring for
os.path.join. Hit ‘F2’. A new window
should be opened with the code for
os.path.join. Hit ‘F3’. You’ll be
prompted to enter the name of any python command, and Emacs will show
you the docstring.
Type the string ‘blah’ and hit return. The string should be
highlighted in pink and if you mouseover it, the minibuffer will say
undefined name 'blah'. That’s flymake working for you.
C-c C-c and the buffer should be sent to a Python interpreter and
you’ll be dropped in the REPL after the code has been loaded. Any
errors in the code will be reported.
If all of this works, then CONGRATULATIONS!!! If not, let me know and I’ll see if I can help debug.
Step 9: Customize
All of this is customizable in hundreds of ways. Try
customize-group RET python-mode RET to see how.
Step 10: How to create a new python project
Whenever you want to create a new Python project, you have do the following:
Create a new virtualenv
Install pymacs into that virtualenv
Install the other pip modules
Switch to that virtualenv in emacs
M-x virtualenv-workon RET newproject/ RET
Changing virtualenvs doesn’t restart Pymacs
For the most part, this won’t affect much, but if you move from a
Python2 project to a Python3 project, you may have problems. The
workaround is to call
M-x pymacs-terminate-services, then
virtualenv-workon to change your virtualenv, and then finally
M-x load-pycomplete to restart pymacs and pycomplete.
Latest stable version of python-mode.el isn’t on Melpa
I’d much prefer to just load python-mode using the built-in Emacs package manager.
Pymacs installation is harder than it needs to be
I wish Pymacs could be installed by a 2 step process
- pip install Pymacs
- M-x package-install RET pymacs RET
Which pycheckers to use?
My script uses pep8 and pyflakes. There are a lot of other options out there and I do not know which is best. See this post for more details.
Not using ropemacs any more
In my talk, I used ropemacs. In this setup, I have decided against it. I was mostly using it for code-completion and documentation lookup, but I like pycomplete.el better for those purposes. It’s included in python-mode and it shows method signatures as you type. Ropemacs does have other features such as project management (easily jumping to files in the same project), and refactoring (changing variable names throughout project). I haven’t used those, so I decided not to install ropemacs.
Project management not included
I haven’t yet decided which package to use for this. I’ll probably try projectile, but there are many other options, some lightweight (ropemacs, eproject, pony-mode) and some heavyweight (ecb, CEDET).
I gleaned knowledge from all of the following, in no particular order.
- Using Pymacs and virtualenv together (slacy.com)
- Using Ropemacs for autocompletion (yilmazhuseyin.com)
- How to use Rope to automatically change virtualenv for you
- Ropemacs and virtualenv (almostobsolete.net)
- The post that turned me on to pycomplete.el (rwdev.eu)
- Perfect Python Environment (2009)
- Lot’s of great ‘advanced-beginner’ emacs tips
- Using python.el rather than python-mode.el
- Using IPython, pylookup and more (pedrokroger.net) - I need to look into this post some more.
- EmacsWiki Python Page
- Python.el, ropemacs, and a little django tip at the end
- Virtualenv.el (something similar is included in python-mode.el
- Python Development Environment - Looks promising, just wish there was some documentation on how to use it.
- Emacs for Cocoa Development - OK, not at all related to python, but some great insight from an Emacs (and all-around) wizard. Don’t miss the ranting at the end of the page.
- Python.el basics
- Using PDB in Emacs
- Ryan McGuire’s .emacs.d
- AutoComplete for Python (enigmacurry.com)
- The original Python IDE post (enigmacurry.com)
Thanks to @danpoirier and
@gregnewman for testing. I initially
recommended using the master branch of python-mode.el, but now I
recommend using the latest stable release (as of now) which is version
6.0.12 to avoid problems loading Pymacs. There’s a bug on 6.0.12 with
virtualenv-workon that requires you to put a trailing slash after
the name of your virtualenv, so I’ve updated the
init.el file above
to account for those changes.