spacemacs/layers/+lang/python/README.org

#+TITLE: Python layer
#+HTML_HEAD_EXTRA: <link rel="stylesheet" type="text/css" href="../../../css/readtheorg.css" />

[[file:img/python.png]]

* Table of Contents                                         :TOC_4_org:noexport:
 - [[Description][Description]]
   - [[Features][Features]]
 - [[Install][Install]]
   - [[Layer][Layer]]
   - [[Test runner][Test runner]]
   - [[Anaconda dependencies][Anaconda dependencies]]
   - [[Automatic buffer formatting on save][Automatic buffer formatting on save]]
   - [[autoflake][autoflake]]
   - [[pylookup][pylookup]]
 - [[Management of Python versions and virtual environments][Management of Python versions and virtual environments]]
   - [[Manage virtual environments with pyvenv][Manage virtual environments with pyvenv]]
   - [[Manage multiple Python versions with pyenv][Manage multiple Python versions with pyenv]]
     - [[Automatic activation of local pyenv version][Automatic activation of local pyenv version]]
 - [[Key Bindings][Key Bindings]]
   - [[Inferior REPL process][Inferior REPL process]]
   - [[Running Python Script in shell][Running Python Script in shell]]
   - [[Testing][Testing]]
   - [[Refactoring][Refactoring]]
   - [[Other Python commands][Other Python commands]]
 - [[Configuration][Configuration]]
   - [[Fill column][Fill column]]

* Description
This layer adds support for the Python language.

** Features
- Auto-completion using [[https://github.com/proofit404/anaconda-mode][anaconda-mode]]
- Code Navigation using  [[https://github.com/proofit404/anaconda-mode][anaconda-mode]]
- Documentation Lookup using  [[https://github.com/proofit404/anaconda-mode][anaconda-mode]]  and [[https://github.com/tsgates/pylookup][pylookup]]
- Test Runners using [[https://github.com/syl20bnr/nose.el][nose.el]] or [[https://github.com/ionrock/pytest-el][pytest]]
- Virtual Environment using  [[https://github.com/jorgenschaefer/pyvenv][pyvenv]] and [[https://github.com/yyuu/pyenv][pyenv]]
- semantic mode is enabled
- PEP8 compliant formatting via [[https://github.com/google/yapf][YAPF]]
- Suppression of unused import with [[https://github.com/myint/autoflake][autoflake]]
- Use the ~%~ key to jump between blocks with [[https://github.com/redguardtoo/evil-matchit][evil-matchit]]

* Install
** Layer
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =python= to the existing =dotspacemacs-configuration-layers= list in this
file.

** Test runner
Both =nose= and =pytest= are supported. By default =nose= is used.
To choose your test runner set the layer variable =python-test-runner= to
either =nose= or =pytest=.

The root of the project is detected with a =.git= directory or a =setup.cfg= file.

#+BEGIN_SRC emacs-lisp
(setq-default dotspacemacs-configuration-layers
  '((python :variables python-test-runner 'pytest)))
#+END_SRC

** Anaconda dependencies
=anaconda-mode= tries to install the dependencies itself but sometimes
it does not work and you may encounter the following message when
opening a python buffer:

#+begin_example
    Blocking call to accept-process-output with quit inhibited!!
#+end_example

To fix this, install the =anaconda-mode= [[https://github.com/proofit404/anaconda-mode/blob/master/requirements.txt][anaconda-deps]] by hand:

#+begin_src sh
    pip install  jedi==0.8.1 json-rpc==1.8.1 service_factory==0.1.2
#+end_src

Source: https://github.com/proofit404/anaconda-mode#issues

If you are facing errors such as "Unable to run anaconda-mode server", try
setting your ~PYTHONPATH~ as explained at
https://github.com/proofit404/anaconda-mode#pythonpath

** Automatic buffer formatting on save
To enable automatic buffer formatting on save with  [[https://github.com/google/yapf][YAPF]] set the variable
=python-enable-yapf-format-on-save= to =t=.

#+BEGIN_SRC emacs-lisp
  (setq-default dotspacemacs-configuration-layers '(
    (python :variables python-enable-yapf-format-on-save t)))
#+END_SRC

** autoflake
To be able to suppress unused imports easily, install [[https://github.com/myint/autoflake][autoflake]]:

#+BEGIN_SRC sh
  pip install autoflake
#+END_SRC

** pylookup
To use =pylookup= on ~SPC m h H~, make sure you update the database first, using
~SPC : pylookup-update~.

* Management of Python versions and virtual environments

** Manage virtual environments with pyvenv
A virtual environment provides isolation of your Python package versions. For a
general overview see [[http://docs.python-guide.org/en/latest/dev/virtualenvs/][this site]]. [[http://virtualenvwrapper.readthedocs.org/en/latest/index.html][Virtualenvwrapper]] which is also explained in the
previous link, is a program which manages your virtual environments in a central
location set by the ~WORKON_HOME~ environment variable.

Spacemacs integration of virtual environments and virtualenvwrapper is provided
by the [[https://github.com/jorgenschaefer/pyvenv][pyvenv]] package. It provides the following keybindings:

| Key Binding | Description                                     |
|-------------+-------------------------------------------------|
| ~SPC m V a~ | activate a virtual environment in any directory |
| ~SPC m V d~ | deactivate active virtual environment           |
| ~SPC m V w~ | work on virtual environment in ~WORKON_HOME~    |

** Manage multiple Python versions with pyenv
If you need multiple Python versions (e.g. Python 2 and Python 3) then take a
look at [[https://github.com/yyuu/pyenv][pyenv]]. It enables the installation and managment of multiple
Python versions.
[[https://www.brianthicks.com/2015/04/10/pyenv-your-python-environment-automated/][This blogpost]] gives a good overview on how to use the tool. Spacemacs
integration is provided by [[https://github.com/proofit404/pyenv-mode][pyenv mode]] which has the following keybindings.

| Key Binding | Description                          |
|-------------+--------------------------------------|
| ~SPC m v s~ | set a pyenv environment with [[https://github.com/yyuu/pyenv][pyenv]]   |
| ~SPC m v u~ | unset a pyenv environment with [[https://github.com/yyuu/pyenv][pyenv]] |

Pyenv can also manage virtual environments for each of the Python versions it
has installed. Those will be listed alongside your Python versions.

*** Automatic activation of local pyenv version
A project-specific pyenv version may be written to a file called
=.python-version= using the [[https://github.com/yyuu/pyenv/blob/master/COMMANDS.md#pyenv-local][pyenv local]] command. If this file is not found then
the global pyenv version is set.

Spacemacs can search in parent directories for this file, and automatically set
the pyenv version. The behavior can be set with the variable
=python-auto-set-local-pyenv-version= to:
- =on-visit= (default) set the version when you visit a python buffer,
- =on-project-switch= set the version when you switch projects,
- =nil= to disable.

* Key Bindings

** Inferior REPL process
Start a Python or iPython inferior REPL process with ~SPC m s i~.
If =ipython= is available in system executable search paths, =ipython=
will be used to launch python shell; otherwise, default =python=
interpreter will be used.  You may change your system executable
search path by activating a virtual environment.

Send code to inferior process commands:

| Key Binding | Description                                     |
|-------------+-------------------------------------------------|
| ~SPC m s b~ | send buffer and keep code buffer focused        |
| ~SPC m s B~ | send buffer and switch to REPL in insert mode   |
| ~SPC m s f~ | send function and keep code buffer focused      |
| ~SPC m s F~ | send function and switch to REPL in insert mode |
| ~SPC m s i~ | start inferior REPL process                     |
| ~SPC m s r~ | send region and keep code buffer focused        |
| ~SPC m s R~ | send region and switch to REPL in insert mode   |
| ~CTRL+j~    | next item in REPL history                       |
| ~CTRL+k~    | previous item in REPL history                   |

** Running Python Script in shell
To run a Python script like you would in the shell press ~SPC m c c~
to start the Python script in comint mode. This is useful when working with
multiple Python files since the REPL does not reload changes made in other
modules.

| Key Binding | Description                                                               |
|-------------+---------------------------------------------------------------------------|
| ~SPC m c c~ | Execute current file in a comint shell                                    |
| ~SPC m c C~ | Execute current file in a comint shell and switch to it in =insert state= |

*Note:* With the universal argument ~SPC u~ you can enter a new
compilation command.

** Testing
Test commands start with ~m t~:

| No Debug    | Description                                              |
|-------------+----------------------------------------------------------|
| ~SPC m t a~ | launch all tests of the project                          |
| ~SPC m t b~ | launch all tests of the current buffer (same as module)  |
| ~SPC m t m~ | launch all tests of the current module                   |
| ~SPC m t s~ | launch all tests of the current suite (only with =nose=) |
| ~SPC m t t~ | launch the current test (function)                       |

| Debug       | Description                                                            |
|-------------+------------------------------------------------------------------------|
| ~SPC m t A~ | launch all tests of the project in debug mode                          |
| ~SPC m t B~ | launch all tests of the current buffer (module) in debug mode          |
| ~SPC m t M~ | launch all tests of the current module in debug mode                   |
| ~SPC m t S~ | launch all tests of the current suite in debug mode (only with =nose=) |
| ~SPC m t T~ | launch the current test (function) in debug mode                       |

** Refactoring

| Key Binding | Description                          |
|-------------+--------------------------------------|
| ~SPC m r i~ | remove unused imports with [[https://github.com/myint/autoflake][autoflake]] |

** Other Python commands

| Key Binding | Description                                                                  |
|-------------+------------------------------------------------------------------------------|
| ~SPC m =~   | Reformat the buffer according to PEP8 using  [[https://github.com/google/yapf][YAPF]]                            |
| ~SPC m d b~ | toggle a breakpoint                                                          |
| ~SPC m g g~ | go to definition using =anaconda-mode-find-definitions= (~C-o~ to jump back) |
| ~SPC m g a~ | go to assignment using =anaconda-mode-find-assignments= (~C-o~ to jump back) |
| ~SPC m g u~ | navigate between usages with =anaconda-mode-find-references=                 |
| ~SPC m h d~ | look for documentation using =helm-pydoc=                                    |
| ~SPC m h h~ | quick documentation using anaconda                                           |
| ~SPC m h H~ | open documentation in =firefox= using [[https://github.com/tsgates/pylookup][pylookup]]                               |
| ~SPC m v s~ | set a pyenv environment with [[https://github.com/yyuu/pyenv][pyenv]]                                           |
| ~SPC m v u~ | unset a pyenv environment with [[https://github.com/yyuu/pyenv][pyenv]]                                         |
| ~SPC m V w~ | work on virtual environment in ~WORKON_HOME~                                 |
| ~SPC m V a~ | activate a virtual environment in any directory                              |
| ~SPC m V d~ | deactivate active virtual environment                                        |

* Configuration
** Fill column
If you want to customize the fill column value, use something like this inside
the ~user-init~ function in your ~.spacemacs~:

#+BEGIN_SRC elisp
(setq python-fill-column 99)
#+END_SRC