https://github.com/vkazanov/elpygen
Generate Python function/method stub for a call-like symbol under point
https://github.com/vkazanov/elpygen
emacs emacs-lisp python
Last synced: 3 months ago
JSON representation
Generate Python function/method stub for a call-like symbol under point
- Host: GitHub
- URL: https://github.com/vkazanov/elpygen
- Owner: vkazanov
- License: gpl-3.0
- Created: 2017-12-07T08:24:11.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2017-12-25T17:36:33.000Z (over 7 years ago)
- Last Synced: 2025-03-15T01:47:49.270Z (3 months ago)
- Topics: emacs, emacs-lisp, python
- Language: Emacs Lisp
- Homepage:
- Size: 39.1 KB
- Stars: 14
- Watchers: 2
- Forks: 3
- Open Issues: 3
-
Metadata Files:
- Readme: README.org
- License: LICENSE
Awesome Lists containing this project
README
* 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
~~.
~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 ~~ 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)