Elpygen

• What?

  ~elpygen.el~ implements a single function only: ~elpygen-implement~. The function retrieves the symbol name under the point, checks that the symbol looks like a call and that it's not defined anywhere in the current file and generates a stub definition based on the name of the symbol.

  As the insertion is done using ~yasnippet~ the inserted function/method template will be interactive, i.e. it's possible to cycle through the typical template modification points using ~<tab>~.

  ~elpygen~ requires Emacs version above 25, built-in ~python.el~ and ~yasnippet~.

• How to install?

  For manual installation checkout the repository and copy ~elpygen.el~ to your ~load-path~. Make sure ~yasnippet~ is installed, and your emacs version is at least 25.

  The package is also available through [[http://melpa.milkbox.net][Melpa]]. So if you have that set up - just do ~M-x package-install elpygen~, which should ensure all the dependencies are installed.

  Having the package installed add ~(require 'elpygen)~ to your ~.emacs~ and bind ~elpygen-implement~ to a key you like:

#+BEGIN_SRC emacs-lisp (define-key python-mode-map (kbd "C-c i") 'elpygen-implement). #+END_SRC

• How to use?

  Move the point to the ~a_function_call~ symbol given the following code:

#+BEGIN_SRC python

a_function_call(first_named, 2, second_named)

#+END_SRC

Press ~C-c i~ (or the binding you use). The following stub will be inserted, pressing ~<tab>~ will cycle through the function name, args and the body.

#+BEGIN_SRC python

a_function_call(first_named, 2, second_named)

def a_function_call(first_named, arg1, second_named): pass

#+END_SRC

Notice how the constant ~2~ was replaced with a default argument name ~arg1~.

The same ~elpygen-implement~ works for methods. Given the following code move the point to ~a_method_call~.

#+BEGIN_SRC python

class Class():

def __init__(self):
    self.a_method_call(arg)

#+END_SRC

Press ~C-c i~:

#+BEGIN_SRC python class Class():

def __init__(self):
    self.a_method_call(arg)

def a_method_call(self, arg):
    pass

#+END_SRC

That's it, basically. ~elpygen-implement~ chooses between function and method templates based on the symbol name. Methods should start with ~self.~, and can only be implemented within a class.

• Why?

  These days I write a lot of small Python utilities, and I prefer doing that using the top-down approach. This means I write the general code structure first, and figure out the details (function/method bodies) later. This package helps to streamline the process of generating those little helper functions and methods and saves a lot of key presses.

  My memory isn't that good any more so I explicitly try to avoid introducing multiple entry points or key bindings, so that the cognitive load isn't too big.

  Originally I wanted to offer this code for inclusion to the wonderful [[https://github.com/jorgenschaefer/elpy][Elpy]] package but figured out that ~elpygen~ doesn't need any code from it and is perfectly fine as a standalone package.

• Plans?

  • [X] if a definition already exists - just navigate to it instead of template insertion

  • [ ] bugs

  • [ ] inserting a Class template based on the symbol name should also be possible.

  • [ ] inserting constants based on the symbol name (if a number or a string - offer to replace?)

  • [ ] customisation points (insertion method, insertion point, etc)