[SciPy-dev] Setting up your editor for NumPy/SciPy

[Stefan van der Walt]

Hi all,

Since we are busy cleaning up the NumPy and SciPy sources, I'd like to
draw your attention to the guidelines regarding whitespace.

We use 4 spaces per indentation level, in Python and C code alike (see
PEP 7: http://www.python.org/dev/peps/pep-0007/ under the heading
Python 3000).  Lines should be a maximum of 79 characters long (to
facilitate reading in text terminals), and must not have trailing
whitespace.

PEP 8 (http://www.python.org/dev/peps/pep-0008/) states:
    
    """
    The preferred way of wrapping long lines is by using Python's
    implied line continuation inside parentheses, brackets and braces.
    If necessary, you can add an extra pair of parentheses around an
    expression, but sometimes using a backslash looks better.  Make
    sure to indent the continued line appropriately.
    """

I attach a file, containing some common errors, which you can use to
setup your editor.  I also attach the settings I use under Emacs to
highlight the problems.

Regards
Stéfan
-------------- next part --------------
A non-text attachment was scrubbed...
Name: bad_whitespace.py
Type: text/x-python
Size: 440 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20071003/03e518b6/attachment.py>
-------------- next part --------------
=========================================
Configuring Emacs for NumPy/SciPy editing
=========================================

.. contents ::

.. note ::

   Downloaded lisp (``.el``) files should be placed in a directory on
   the Emacs path.  I typically use ``~/elisp`` and add it to the
   search path using

   ::

     (add-to-list 'load-path "~/elisp")

Essential to producing well-formed code
=======================================

Never use tabs
--------------

::

  (setq-default indent-tabs-mode nil)


Clean up tabs and trailing whitespace
-------------------------------------

``M-x untabify``

and

``M-x whitespace-cleanup``


Highlight unnecessary whitespace
--------------------------------

Download
`show-wspace.el <http://www.emacswiki.org/cgi-bin/wiki/show-wspace.el>`__

::

  ; Show whitespace
  (require 'show-wspace)
  (add-hook 'python-mode-hook 'highlight-tabs)
  (add-hook 'font-lock-mode-hook 'highlight-trailing-whitespace)

Wrap lines longer than 79 characters
------------------------------------

::

  (setq fill-column 79)

The ``fill-paragraph`` command (``M-q`` or ``ESC-q``) also comes in
handy.

Other useful tools
==================

Highlight column 79
-------------------

Prevent lines from exceeding 79 characters in length.

Download
`column-marker.el <http://www.emacswiki.org/cgi-bin/wiki/column-marker.el>`__

::

  (require 'column-marker)
  (add-hook 'font-lock-mode-hook (lambda () (interactive) (column-marker-1 80)))


Show a ruler with the current column position
---------------------------------------------

::

  (require 'ruler-mode)
  (add-hook 'font-lock-mode-hook 'ruler-mode)

Enable restructured text (ReST) editing
---------------------------------------

::

  (require 'rst)
  (add-hook 'text-mode-hook 'rst-text-mode-bindings)

Fix outline-mode to work with Python
------------------------------------

::

  (add-hook 'python-mode-hook 'my-python-hook)
  (defun py-outline-level ()
    "This is so that `current-column` DTRT in otherwise-hidden text"
    ;; from ada-mode.el
    (let (buffer-invisibility-spec)
      (save-excursion
        (skip-chars-forward "\t ")
        (current-column))))

::

  ; this fragment originally came from the web somewhere, but the outline-regexp
  ; was horribly broken and is broken in all instances of this code floating
  ; around.  Finally fixed by Charl P. Botha
  ; <<a href="http://cpbotha.net/">http://cpbotha.net/</a>>
  (defun my-python-hook ()
    (setq outline-regexp "[^ \t\n]\\|[ \t]*\\(def[ \t]+\\|class[ \t]+\\)")
    ; enable our level computation
    (setq outline-level 'py-outline-level)
    ; do not use their \C-c@ prefix, too hard to type. Note this overides 
    ;some python mode bindings
    ;(setq outline-minor-mode-prefix "\C-c")
    ; turn on outline mode
    (outline-minor-mode t)
    ; initially hide all but the headers
    ; (hide-body)
    (show-paren-mode 1)
  )