306 lines
8.6 KiB
ReStructuredText
306 lines
8.6 KiB
ReStructuredText
|
|
.. |travis| image:: https://img.shields.io/travis/proofit404/anaconda-mode.svg?style=flat-square
|
|
:target: https://travis-ci.org/proofit404/anaconda-mode
|
|
:alt: Build Status
|
|
|
|
.. |coveralls| image:: https://img.shields.io/coveralls/proofit404/anaconda-mode.svg?style=flat-square
|
|
:target: https://coveralls.io/r/proofit404/anaconda-mode
|
|
:alt: Coverage Status
|
|
|
|
.. |requires| image:: https://img.shields.io/requires/github/proofit404/anaconda-mode.svg?style=flat-square
|
|
:target: https://requires.io/github/proofit404/anaconda-mode/requirements
|
|
:alt: Requirements Status
|
|
|
|
.. |melpa| image:: http://melpa.org/packages/anaconda-mode-badge.svg
|
|
:target: http://melpa.org/#/anaconda-mode
|
|
:alt: Melpa
|
|
|
|
.. |melpa-stable| image:: http://stable.melpa.org/packages/anaconda-mode-badge.svg
|
|
:target: http://stable.melpa.org/#/anaconda-mode
|
|
:alt: Melpa Stable
|
|
|
|
.. image:: static/logo.png
|
|
:align: right
|
|
:alt: Logo
|
|
|
|
===============
|
|
Anaconda mode
|
|
===============
|
|
|
|
|travis| |coveralls| |requires| |melpa| |melpa-stable|
|
|
|
|
Code navigation, documentation lookup and completion for Python.
|
|
|
|
.. figure:: static/completion.png
|
|
|
|
.. figure:: static/reference.png
|
|
|
|
|
|
Features
|
|
--------
|
|
Anaconda mode provides the following features
|
|
|
|
* context-sensitive code completion
|
|
* jump to definitions
|
|
* find references
|
|
* view documentation
|
|
* virtual environment
|
|
* eldoc mode
|
|
* all this stuff inside vagrant and remote hosts
|
|
|
|
Supported Python Versions
|
|
-------------------------
|
|
2.6, 2.7, 3.3, 3.4
|
|
|
|
Installation
|
|
------------
|
|
|
|
To use this package you need to install ``setuptools``.
|
|
|
|
package.el
|
|
``````````
|
|
|
|
All you need to do is install the package from Melpa_::
|
|
|
|
M-x package-install RET anaconda-mode RET
|
|
|
|
Manual
|
|
``````
|
|
|
|
Clone this repository somewhere and add this directory to your
|
|
``load-path``.
|
|
|
|
Prelude
|
|
```````
|
|
|
|
``anaconda-mode`` is included in the `Emacs Prelude`_ distribution. You
|
|
can use it as well. Look at the ``prelude-python`` module to see more
|
|
details.
|
|
|
|
Spacemacs
|
|
`````````
|
|
|
|
``anaconda-mode`` is included in the Spacemacs_ distribution. You can use
|
|
it as well. Look at the ``python`` language layer to see more details.
|
|
|
|
Configuration
|
|
-------------
|
|
|
|
You can automatically enable ``anaconda-mode`` in all python buffers
|
|
with following code in your configuration:
|
|
|
|
.. code:: lisp
|
|
|
|
(add-hook 'python-mode-hook 'anaconda-mode)
|
|
|
|
ElDoc
|
|
`````
|
|
|
|
``anaconda-eldoc-mode`` provide document function to ``eldoc-mode``. All
|
|
you need is to enable ``anaconda-eldoc-mode`` in addition to the previous setup.
|
|
|
|
.. code:: lisp
|
|
|
|
(add-hook 'python-mode-hook 'anaconda-eldoc-mode)
|
|
|
|
Usage
|
|
-----
|
|
|
|
To start a completion press ``C-M-i``. This is the standard emacs binding
|
|
for ``complete-at-point`` function. You can use company-mode_ with
|
|
company-anaconda_ backend to get more intelligent ui. Or
|
|
auto-complete-mode_ with ac-anaconda_ as a last try.
|
|
|
|
Interactive commands
|
|
````````````````````
|
|
|
|
Here is a list of interactive commands available with anaconda-mode
|
|
|
|
========== ==============================
|
|
Keybinding Description
|
|
========== ==============================
|
|
C-M-i anaconda-mode-complete
|
|
M-. anaconda-mode-find-definitions
|
|
M-, anaconda-mode-find-assignments
|
|
M-r anaconda-mode-find-references
|
|
M-* anaconda-mode-go-back
|
|
M-? anaconda-mode-show-doc
|
|
========== ==============================
|
|
|
|
If multiple candidates are found for definitions, assignments or usages,
|
|
you'll see an advanced anaconda navigator buffer.
|
|
|
|
PYTHONPATH
|
|
``````````
|
|
|
|
You can add your project to the Emacs ``PYTHONPATH``. If you store project
|
|
dependencies somewhere on your machine, you can add them as well.
|
|
|
|
.. code:: lisp
|
|
|
|
(add-to-list 'python-shell-extra-pythonpaths "/path/to/the/project")
|
|
(add-to-list 'python-shell-extra-pythonpaths "/path/to/the/dependency")
|
|
|
|
Virtual environment
|
|
```````````````````
|
|
|
|
Use a virtual environment to isolate your project dependencies from
|
|
others on the system. You can additionally install your project in an editable
|
|
mode in the virtual environment. This will improve search functionality.
|
|
Then activate this virtual environment inside Emacs.
|
|
|
|
::
|
|
|
|
M-x pythonic-activate RET /path/to/virtualenv RET
|
|
|
|
Also you can use `pyenv-mode`_ or similar package to hold virtual
|
|
environment in actual state.
|
|
|
|
Each action above applies to ``anaconda-mode`` immediately. The next
|
|
``anaconda-mode`` command you call will use this environment for
|
|
search completion candidates.
|
|
|
|
Tramp
|
|
`````
|
|
|
|
It's possible to use anaconda-mode on a remote server when you connect
|
|
to it using tramp. Anaconda-mode can search for completion candidates
|
|
and all other stuff on remote server while you're running Emacs locally.
|
|
First of all open interesting remote file.
|
|
|
|
::
|
|
|
|
C-x C-f /ssh:remote_host:project/__init__.py RET
|
|
|
|
After tramp successfully connects and you see actual buffer
|
|
content, activate the remote virtual environment.
|
|
|
|
::
|
|
|
|
M-x pythoninc-activate RET /ssh:remote_host:/home/user/venv RET
|
|
|
|
Now any anaconda-mode command will use ``/home/user/venv/bin/python``
|
|
interpreter running on ``remote_host`` over ssh. If you don't use the
|
|
virtual environment remotely then you have an option to specify the remote
|
|
interpreter directly.
|
|
|
|
.. code:: lisp
|
|
|
|
(setq python-shell-interpreter "/ssh:remote_host:/usr/bin/python")
|
|
|
|
It is important to remember that ``remote_host`` must be a real host
|
|
name or an IP address. SSH aliases not allowed to be used with
|
|
anaconda-mode. Also port 9000 on the remote host should be open to
|
|
incoming connections from your local machine. A final note about project scope:
|
|
all kinds of searching from inside the
|
|
virtual environment are available from any buffer. However searching inside your
|
|
project is available only if you open it on the same machine as the
|
|
interpreter.
|
|
|
|
Vagrant
|
|
```````
|
|
|
|
You can get all the intelligent features of anaconda-mode with virtual
|
|
environments deployed on your vagrant box. Fire up the vagrant machine as usual.
|
|
The easiest way to handle authentication is to copy your public ssh key to the
|
|
vagrant box.
|
|
|
|
::
|
|
|
|
ssh-copy-id vagrant@localhost -p 2222
|
|
|
|
Now open your project inside the vagrant box.
|
|
|
|
::
|
|
|
|
C-x C-f /ssh:vagrant@localhost#2222:/vagrant/polls/views.py
|
|
|
|
Check the ``*anaconda-mode*`` buffer for the port number, and forward that port
|
|
from vagrant.
|
|
|
|
::
|
|
|
|
ssh -nNT vagrant@localhost -p 2222 -L <port number>:localhost:<port number>
|
|
|
|
Then activate your project environment installed inside vagrant.
|
|
|
|
::
|
|
|
|
M-x pythonic-activate RET /ssh:vagrant@localhost#2222:/vagrant/polls/venv RET
|
|
|
|
Now you are ready to go. If you have random connection errors during interaction
|
|
with running server, try replacing the host name with the IP address, for example,
|
|
``localhost`` with ``127.0.0.1``.
|
|
|
|
Implementation details
|
|
----------------------
|
|
|
|
Anaconda mode comes with ``anaconda_mode.py`` server. This server
|
|
allows you to use the jedi_ python library over jsonrpc api. The server chooses
|
|
first available port starting from 9000. Anaconda mode will run this
|
|
server automatically on first call of any anaconda-mode command.
|
|
|
|
This means that completion results and reference searches depend on your
|
|
project installation.
|
|
|
|
Bug Reports
|
|
-----------
|
|
|
|
Please attach ``*anaconda-mode*`` buffer content to every created
|
|
issue.
|
|
|
|
Issues
|
|
------
|
|
|
|
AttributeError and KeyError randomly happens
|
|
````````````````````````````````````````````
|
|
|
|
These kinds of problems were reported with jedi 0.9 version. (This
|
|
error may occur in Spacemacs or any other usage). You can try to
|
|
downgrade jedi version down to 0.8.
|
|
|
|
::
|
|
|
|
M-: (dired (anaconda-mode-server-directory)) RET
|
|
M-! rm -rf jedi* RET
|
|
M-! pip install "jedi<0.9" -t . RET
|
|
|
|
After you saw the jedi version changed to 0.8 in the dired window, you
|
|
have to refresh Emacs to make it work right away. You can either
|
|
restart Emacs or kill the ``*anaconda-mode*`` buffer.
|
|
|
|
Contributions
|
|
-------------
|
|
|
|
Are very welcome. But any significant change has to be accompanied
|
|
with tests, both for Emacs Lisp and Python code. To run the test
|
|
suite, call:
|
|
|
|
.. code:: shell
|
|
|
|
tox
|
|
|
|
Thanks
|
|
------
|
|
|
|
* Dmitry Gutov **@dgutov**
|
|
* Bo Lin **@sadboy**
|
|
* Vasilij Schneidermann **@wasamasa**
|
|
* Fredrik Bergroth **@fbergroth**
|
|
* Fabio Corneti **@fabiocorneti**
|
|
* Tom Davis **@tdavis**
|
|
* Sviridov Alexander **@sviridov**
|
|
* Mario Rodas **@marsam**
|
|
|
|
.. _Melpa: http://melpa.milkbox.net/
|
|
.. _pyenv-mode: https://github.com/proofit404/pyenv-mode
|
|
.. _jedi: http://jedi.jedidjah.ch/en/latest/
|
|
.. _emacs prelude: https://github.com/bbatsov/prelude
|
|
.. _spacemacs: https://github.com/syl20bnr/spacemacs
|
|
.. _company-mode: http://company-mode.github.io/
|
|
.. _company-anaconda: https://github.com/proofit404/company-anaconda
|
|
.. _auto-complete-mode: https://github.com/auto-complete/auto-complete
|
|
.. _ac-anaconda: https://github.com/proofit404/ac-anaconda
|
|
|
|
|