Description
===========
Pydiction allows you to Tab-complete Python code in Vim such as keywords, built-ins, standard library, and third-party modules.
It doesn't require installing any dependencies. It simply consists of three main files:
python_pydiction.vim -- Vim plugin that autocompletes Python code.
complete-dict -- Dictionary file of Python keywords, modules, etc.
pydiction.py -- Python script to add more words to complete-dict.
The bundled dictionary comes with most things you will likely need in your day-to-day Python programming, and the included
Python script allows you to easily append new modules to the dictionary. So you don't have to wait around for me to add them.
And you can teach Pydiction to complete your project's own API very quickly. Some third-party libraries already supported are:
`Django` `Flask` `Requests` `Twisted` `Numpy` `Psycopg2` `PyGreSQL` `SQLite3` `MySQLdb` `OpenGL` `Pygame` `wxPython` `PyGTK`
`PyQT4` `OpenID` `Scrapy` `Celery` and more.
Since Pydiction just uses a flat dictionary file, it's extremely flexible because you can do things like re-order how you want
things to appear in your popup completion menus. By default it will be in alphabetical order, but if you want `else` to come
before `elif`, you can.
Pydiction is often misunderstood when compared to other forms of python code completion. Pydiction doesn't have to do
any source code analysis. It only uses the dictionary of terms. This is its strength and weakness when used alone. It's a
strength because of how stable it allows the plugin to be. And Pydiction really shines when completing 3rd party libraries
and frameworks and basic keywords, but not for things that dictionary completion isn't suited for. For that, you'll want
omni-completion too. See the `Tips` section for how to get the best of all worlds.
Installation
============
If you have Pathogen installed:
cd ~/.vim/bundle
git clone https://github.com/rkulla/pydiction.git
or use a plugin manager like Vimogen (https://github.com/rkulla/vimogen) to install and manage Pydiction and all of your plugins.
Otherwise:
In the after/ftplugin/ directory, there's a file called python_pydiction.vim.
- UNIX/LINUX/OSX: Put python_pydiction.vim in ~/.vim/after/ftplugin/
Create this directory if doesn't yet exist. Vim looks there automatically
- WINDOWS: Put python_pydiction.vim in C:\vim\vimfiles\ftplugin\
Assuming you installed Vim to C:\vim\
You may install complete-dict and pydiction.py anywhere (see the Configuration section),
but only python_pydiction.vim in the ftplugin directory because for .vim files only.
Configuration
=============
In your vimrc file, first add the following line to enable filetype plugins:
filetype plugin on
then make sure you set g:pydiction_location to the full path of where you installed complete-dict. Ex:
let g:pydiction_location = '/path/to/complete-dict'
for example, if you used Pathogen to install Pydiction, you would set this to:
let g:pydiction_location = '/home/user/.vim/bundle/pydiction/complete-dict'
and the dictionary will be available to all of your virtualenv's as well.
You can change the height of the completion menu by setting g:pydiction_menu_height in your vimrc:
let g:pydiction_menu_height = 3
The default menu height is 8, meaning 8 items at a time will be shown. Some people prefer more or less and you can make it as large as you want since it will automatically know where to position the menu to be visible.
If you want to configure other things, such as how to get Pydiction to work with other plugins like `SnipMate` or the color of the menu, see the `Tips` section of this documentation.
Usage (Plugin)
==============
In Vim's INSERT mode, type part of a Python keyword, module name, attribute or method, then hit TAB:
raw<Tab>
will bring up a menu of possibilities, such as:
raw_input(
raw_unicode_escape_decode(
raw_unicode_escape_encode(
Pressing `Tab` again scrolls down the menu so you can select something else. Then type a popup-menu key:
<Space> -- Accept current match and insert a space.
CTRL-Y -- Accept current match and and don't insert a space.
<Enter> -- Accept current match and insert a newline.
<ESC> or CTRL-E -- Close the menu and do not accept any match.
You can also now use Shift-Tab to Tab backwards through the popup menu.
Typing:
os.p<Tab>
pops up:
os.pardir
os.path
os.pathconf(
os.pathconf_names
os.pathsep
os.pipe(
...
Typing:
co<Tab>
pops up:
continue
coerce(
compile(
...
Typing:
dj[Tab]
pops up:
django
django.db
django.utils
django.conf
django.template
...
Typing:
def __i<Tab>
pops up:
def __init__(
def __iter__(
You can complete modules that were imported via `from module import submodule`. For example:
from xml.parsers import expat
expat.P<Tab>
expands to:
expat.ParserCreate(
Python's newer `import module as X` syntax isn't supported by default, since it would be impossible for Pydiction to know what you'll alias a module to. However, you can either add the alias to complete-dict or just use pythoncomplete.vim's Omnicompletition by typing `<C-X><C-O>`. You can also use the omni-completion to complete other things that aren't in the complete-dict dictionary, such as variables:
i = 3
i.b<Ctrl-x><Ctrl-o> # expands to: i.bit_length(
The same goes for relative import syntax. I have included a few common Django relative import words such as `.models` `.views` and `.forms` and you can add more.
See my Tips section below for more.
If you feel you're getting different results in your completion menu, it's probably because you don't have Vim set to ignore case. You can remedy this with ":set noic". It also helps to type at least 2 letters before hitting Tab, to help Vim narrow down what you mean to complete.
Usage (Dictionary generator)
============================
You can skip this section if you don't plan to add more modules to complete-dict yourself. Consult complete-dict to see if it already has the modules you intend to use.
This is the Python script used to create the "complete-dict" Vim dictionary file. I have curated and bundled a default complete-dict for your use. I created it using a Linux system, so there won't be many real win32 specific modules in it. You're free to run pydiction.py to add or upgrade as many modules as you need. The dictionary file will still work if you're using windows, but it won't complete win32 related modules unless you tell it to.
USAGE: At a command prompt, run:
$ python pydiction.py <module> [<module> ...] [-v]
(You need to have at least python 2.x installed.)
Say you wanted to add a module called "mymodule" to complete-dict. Do the following:
$ python pydiction.py mymodule
You can input more than one module name on the command-line by separating them with spaces:
$ python pydiction.py mymodule1 mymodule2 mymodule3
The -v option will just write the results to stdout (standard output) instead of the complete-dict file:
$ ./pydiction.py -v datetime math
If the backup file "complete-dict.last" doesn't exist in the current directory, pydiction.py will create it for you. You should always keep a backup of your last working dictionary in case anything goes wrong, as it can get tedious having to recreate the file from scratch.
If complete-dict.last already exists, the script will ask if you want to overwrite your old backup with the new backup.
If you try to add a module that already exists in complete-dict, Pydiction will tell you it already exists, so don't worry about adding duplicates. In fact you can't add duplicates because every time pydiction.py runs it looks for and removes any duplicates in the file.
When pydiction.py adds new modules to
