docs/dev/env.rst

   1 Your Development Environment
   2 ============================
   3
   4
   5 Text Editors
   6 ::::::::::::
   7
   8 Just about anything which can edit plain text will work for writing Python code,
   9 however, using a more powerful editor may make your life a bit easier.
  10
  11
  12 VIM
  13 ---
  14
  15 Vim is a text editor which uses keyboard shortcuts for editing instead of menus
  16 or icons. There exist a couple of plugins and settings for the VIM editor to
  17 aid python development. If you only develop in Python, a good start is to set
  18 the default settings for indentation and linewrapping to values compliant with
  19 `PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_. In your home directory,
  20 open a file called `.vimrc` and add the following lines: ::
  21
  22     set textwidth=79
  23     set shiftwidth=4
  24     set tabstop=4
  25     set expandtab
  26     set softtabstop=4
  27     set shiftround
  28
  29 With these settings, newlines are inserted after 79 characters and indentation
  30 is set to 4 spaces per tab. If you also use VIM for other languages, there is a
  31 handy plugin at indent_, which handles indentation settings for python source
  32 files.
  33
  34 There is also a handy syntax plugin at syntax_ featuring some improvements over
  35 the syntax file included in VIM 6.1.
  36
  37 These plugins supply you with a basic environment for developing in Python.
  38 To get the most out of Vim, you should continually check your code for syntax
  39 errors and PEP8 compliance. Luckily PEP8_ and Pyflakes_ will do this for you.
  40 If your VIM is compiled with `+python` you can also utilize some very handy
  41 plugins to do these checks from within the editor.
  42
  43 For PEP8 checking, install the vim-pep8_ plugin, and for pyflakes you can
  44 install vim-pyflakes_. Now you can map the functions `Pep8()` or `Pyflakes()`
  45 to any hotkey or action you want in Vim. Both plugins will display errors at
  46 the bottom of the screen, and provide an easy way to jump to the corresponding
  47 line. It's very handy to call these functions whenever you save a file. In
  48 order to do this, add the following lines to your `vimrc`::
  49
  50     autocmd BufWritePost *.py call Pyflakes()
  51     autocmd BufWritePost *.py call Pep8()
  52
  53
  54 .. _indent: http://www.vim.org/scripts/script.php?script_id=974
  55 .. _syntax: http://www.vim.org/scripts/script.php?script_id=790
  56 .. _Pyflakes: http://pypi.python.org/pypi/pyflakes/
  57 .. _vim-pyflakes: https://github.com/nvie/vim-pyflakes
  58 .. _PEP8: http://pypi.python.org/pypi/pep8/
  59 .. _vim-pep8: https://github.com/nvie/vim-pep8
  60
  61 .. todo:: add supertab notes
  62
  63 TextMate
  64 --------
  65
  66 "`TextMate <http://macromates.com/>`_ brings Apple's approach to operating
  67 systems into the world of text editors. By bridging UNIX underpinnings and GUI,
  68 TextMate cherry-picks the best of both worlds to the benefit of expert
  69 scripters and novice users alike."
  70
  71 Sublime Text
  72 ------------
  73
  74 "`Sublime Text <http://www.sublimetext.com/>`_ is a sophisticated text editor
  75 for code, html and prose. You'll love the slick user interface and
  76 extraordinary features."
  77
  78 Sublime Text has excellent support for editing Python code and uses Python for
  79 its plugin API.
  80
  81 `Sublime Text 2 <http://www.sublimetext.com/blog/articles/sublime-text-2-beta>`_
  82 is currently in beta.
  83
  84 IDEs
  85 ::::
  86
  87 PyCharm / IntelliJ IDEA
  88 -----------------------
  89
  90 `PyCharm <http://www.jetbrains.com/pycharm/>`_ is developed by JetBrains, also
  91 known for IntelliJ IDEA. Both share the same code base and most of PyCharm's
  92 features can be brought to IntelliJ with the free `Python Plug-In <http://plugins.intellij.net/plugin/?id=631/>`_.
  93
  94
  95 Eclipse
  96 -------
  97
  98 The most popular Eclipse plugin for Python development is Aptana's
  99 `PyDev <http://pydev.org>`_.
 100
 101
 102 Komodo IDE
 103 -----------
 104 `Komodo IDE <http://www.activestate.com/komodo-ide>`_ is developed by
 105 ActiveState and is a commercial IDE for Windows, Mac
 106 and Linux.
 107
 108
 109 Spyder
 110 ------
 111
 112 `Spyder <http://code.google.com/p/spyderlib/>`_ an IDE specifically geared
 113 toward working with scientific python libraries (namely `Scipy <http://www.scipy.org/>`_).
 114 Includes integration with pyflakes_, `pylint <http://www.logilab.org/857>`_,
 115 and `rope <http://rope.sourceforge.net/>`_.
 116
 117 Spyder is open-source (free), offers code completion, syntax highlighting,
 118 class and function browser, and object inspection.
 119
 120
 121 WingIDE
 122 -------
 123
 124 `WingIDE <http://wingware.com/>`_ a python specific IDE.   Runs for Linux,
 125 Windows, and Mac (as an X11 application, which frustrates some Mac users).
 126
 127
 128 Interpreter Tools
 129 :::::::::::::::::
 130
 131
 132 virtualenv
 133 ----------
 134
 135 Virtualenv is a tool to keep the dependencies required by different projects
 136 in separate places, by creating virtual Python environments for them.
 137 It solves the "Project X depends on version 1.x but, Project Y needs 4.x"
 138 dilemma and keeps your global site-packages directory clean and manageable.
 139
 140 `virtualenv <http://www.virtualenv.org/en/latest/index.html>`_ creates
 141 a folder which contains all the necessary executables to contain the
 142 packages that a Python project would need. An example workflow is given.
 143
 144 Install virtualenv::
 145
 146     $ pip install virtualenv
 147
 148
 149 Create a virtual environment for a project::
 150
 151     $ cd my_project
 152     $ virtualenv venv
 153
 154 ``virtualenv venv`` will create a folder in the currect directory
 155 which will contain the Python executable files, and a copy of the ``pip``
 156 library which you can use to install other packages. The name of the
 157 virtual environment (in this case, it was ``venv``) can be anything;
 158 omitting the name will place the files in the current directory instead.
 159
 160 In order the start using the virtual environment, run::
 161
 162     $ source venv/bin/activate
 163
 164
 165 The name of the current virtual environment will now appear on the left
 166 of the prompt (e.g. ``(venv)Your-Computer:your_project UserName$``) to
 167 let you know that it's active. From now on, any package that you install
 168 using ``pip`` will be placed in the venv folder, isolated from the global
 169 Python installation. Install packages as usual::
 170
 171     $ pip install requests
 172
 173 To stop using an environment simply type ``deactivate``. To remove the
 174 environment, just remove the directory it was installed into. (In this
 175 case, it would be ``rm -rf venv``).
 176
 177 Other Notes
 178 ~~~~~~~~~~~
 179
 180 Running ``virtualenv`` with the option ``--no-site-packages`` will not
 181 include the packages that are installed globally. This can be useful
 182 for keeping the package list clean in case it needs to be accessed later.
 183
 184 In order to keep your environment consistent, it's a good idea to "freeze"
 185 the current state of the environment packages. To do this, run
 186
 187 ::
 188
 189     $ pip freeze > requirements.txt
 190
 191 This will create a ``requirements.txt`` file, which contains a simple
 192 list of all the packages in the current environment, and their respective
 193 versions. Later, when a different developer (or you, if you need to re-
 194 create the environment) can install the same packages, with the same
 195 versions by running
 196
 197 ::
 198
 199     $ pip install -r requirements.txt
 200
 201 This can help ensure consistency across installations, across deployments,
 202 and across developers.
 203
 204 Lastly, remember to exclude the virtual environment folder from source
 205 control by adding it to the ignore list.
 206
 207 virtualenvwrapper
 208 -----------------
 209
 210 `Virtualenvwrapper <http://pypi.python.org/pypi/virtualenvwrapper>`_ makes
 211 virtualenv a pleasure to use by wrapping the command line API with a nicer CLI.
 212
 213 ::
 214
 215     $ pip install virtualenvwrapper
 216
 217
 218 Put this into your `~/.bash_profile` (Linux/Mac) file:
 219
 220 ::
 221
 222     $ export VIRTUALENVWRAPPER_VIRTUALENV_ARGS='--no-site-packages'
 223
 224 This will prevent your virtualenvs from relying on your (global) site packages
 225 directory, so that they are completely separate..
 226
 227 Other Tools
 228 :::::::::::
 229
 230 IDLE
 231 ----
 232
 233 `IDLE <http://docs.python.org/library/idle.html>`_ is an integrated
 234 development environment that is part of Python standard library. It is
 235 completely written in Python and uses Tkinter GUI toolkit. Though IDLE
 236 is not suited for full-blown development using Python , it is quite
 237 helpful to try out small Python snippets and experiment with different
 238 features in Python.
 239
 240 It provides following features:
 241
 242 * Python Shell Window (interpreter)
 243 * Multi window text editor that colorizes Python code
 244 * Minimal debugging facility
 245
 246
 247 IPython
 248 -------
 249
 250 `IPython <http://ipython.org/>`_ provides a rich toolkit to help you make the
 251 most out of using Python interactively. Its main components are:
 252
 253 * Powerful Python shells (terminal- and Qt-based).
 254 * A web-based notebook with the same core features but support for rich media,
 255   text, code, mathematical expressions and inline plots.
 256 * Support for interactive data visualization and use of GUI toolkits.
 257 * Flexible, embeddable interpreters to load into your own projects.
 258 * Tools for high level and interactive parallel computing.
 259
 260 ::
 261
 262     $ pip install ipython
 263
 264
 265
 266 BPython
 267 -------
 268
 269 `bpython <http://bpython-interpreter.org/>`_ is an alternative interface to the
 270 Python interpreter for Unix-like operating systems. It has the following features:
 271
 272 * In-line syntax highlighting.
 273 * Readline-like autocomplete with suggestions displayed as you type.
 274 * Expected parameter list for any Python function.
 275 * "Rewind" function to pop the last line of code from memory and re-evaluate.
 276 * Send entered code off to a pastebin.
 277 * Save entered code to a file.
 278 * Auto-indentation.
 279 * Python 3 support.
 280
 281 ::
 282
 283     $ pip install bpython
 284