# PIDA Handbook

PIDA is an IDE (integrated development environment). PIDA is different from other IDEs in that it will use the tools that are already available rather than attempting to reinvent each one. PIDA is written in Python with the PyGTK toolkit, and although it is designed to be used to program in any language, PIDA has fancy Python IDE features.

This document describes PIDA features and usage. It is aimed at providing help for new comers and advanced users. Developer documentation is available in other sources for those who want to hack PIDA.

| Since PIDA is still being actively worked on, this manual is still incomplete and will grow with time.

<tito> aa_: PIDA is an acronym ? <Zapek> PIDA Is Da Acronym <mnemoc> Python Integrated Developmenet Architecture iirc <aa_> Zapek: I like it
— #pida on freenode.net

## 1. Introduction

There are many IDE around, and some are very good. But lots of them are also closed in the sense that they are limited in terms of extensibility or communication with other tools. On the other hand, some of you may want to change your editor for anything else, even if you have to rely on external tools to complete its features.

PIDA was designed with these problems in mind. PIDA's motto is to reuse the tools that proved to be useful and solid, and to provide the glue for them. PIDA is written in Python with PyGTK, is easily extensible through plug-ins and can embed any editor provided someone writes an adapter for it.

PIDA has a number of unique features, such as

- Embedding Vim, Emacs or any editor.
  [Of course, the editor has to provide a way to communicate with for external programs. Moo, Scite, and probably GEdit could be candidates]

- Using any version control system.

## 2. Requirements

Because of the nature of PIDA there are a number of tools that may optionally be used, but are not absolutely required. The list of requirements is therefore split into absolute and relative requirements.

### 2.1. Absolute Requirements

Python

Python is the programming language PIDA is written in. PIDA requires any version of Python greater than or equal to 2.4. Python is available from the `Python Web Site`_ or more likely packaged for your distribution. Most desktop Linuxes come with Python preinstalled.

PyGTK

PyGTK are the Python bindings for the GTK toolkit. Note that you will also need to have GTK installed for them to work. These are available from the `PyGTK Web Site` and the `GTK Web Site` or more likely packaged by your Linux distribution.

Kiwi

Kiwi is a helper library for PyGTK. It was decided a while ago that there should not be a duplication in effort in creating common widgets and patterns withing PyGTK programs. For this reason common things exist in Kiwi, and PIDA developers contribute fixes back upstream to Kiwi. Kiwi is available in the contrib directory of the source code. It is recommended to use this version if at all possible. It contains no changes from the original, but it is ensured to have all the latest fixes.

VTE

VTE is a GTK terminal widget that is used by gnome-terminal. PIDA uses this for many things, and since it is in most distributions that Gnome is in, we have made it an absolute requirement.

### 2.2. Compilation Requirements

Python development headers

These are usually available in your distribution as python-dev. They are the headers required for building python extensions.

PyGTK development headers

These are required to build the external moo_stub extension, and are usually available in your distribution as pygtk-dev or pygtk-devel etc. packages.

## 3. Installation

PIDA is still not considered finalised by its authors. The most recent version lies in SVN repository, but milestones are available though to provide a snapshot of the development to the less adventurers.

### 3.1. Compilation from sources

The source code comes with a standard Python installation method.

Build

The build step is necessary even when running from source so as to ensure that the extensions are built.

    python setup.py build

Debian Users

Due to the location of headers on Debian, users must first:

    export PKG_CONFIG_PATH=/usr/lib/pkgconfig/python2

Install

Installation is the recommended method of running PIDA. Running from source should be reserved for people who know what they are doing.

    python setup.py install

| you may need to use sudo or equivalent to obtain superuser access if you are installing to a global location.

Run from source

First copy the moo_stub.so (that was built in the build stage) from the build/ directory somewhere into PYTHONPATH or the working directory. Then execute:

| Running from source is generally reserved for developers of PIDA, or those people who really know what they are doing. It is very useful to be able to make a change and test it immediately. It is not recommended to use this as a general running method.

    run-pida.sh

### 3.2. Obtaining the development source code

The current development version is hosted on Google Code Subversion repository. You can use the following command to anonymously check the latest source code.

    svn checkout http://pida.googlecode.com/svn/trunk/ pida

PIDA can be executed from its source directory as outlined above.

### 3.3. Distribution packages

Though there is still a long way before PIDA can be considered mature, it is already packaged by several Linux and BSD(FIXME?) distributions. Use the guidelines of your distribution to install or remove PIDA from your system.

Table: Known distributions that provide PIDA
Distribution | Distribution version | PIDA version
--- | --- | ---
Debian | Etch (stable) | 0.3.1
Debian | Lenny (testing) | 0.4.4
Debian | Sid (unstable) | 0.4.4
Gentoo | FIXME. | FIXME.
Ubuntu | Breezy Badger | 0.2.2
Ubuntu | Dapper Drake | 0.2.2
Ubuntu | Edgy Eft | 0.3.1
Ubuntu | Feisty Fawn | 0.3.1
Ubuntu | Gutsy | 0.4.4

| There are chances that the version packaged is a bit outdated. Please consider trying to install the most recent version before reporting a bug. You can either compile pida from sources or try to use a package prepared for a more recent version of your distribution.

### 3.4. MS Windows

FIXME.

Some pointers on how to install PIDA dependencies can be found on http://code.google.com/p/pida/wiki/WindowsInstallation

### 3.5. Mac OS X

FIXME.

## 4. Getting started

FIXME.

### 4.1. First run wizard

| This feature is planned for a future version of PIDA, which is still undetermined yet.

### 4.2. The PIDA window

Like any other IDE, PIDA provides in one window all the tools you need to edit your files, compile your programs, invoke external tools, explore a project space or a file hierarchy, and so on. The PIDA window is organized with a menu, a toolbar, multiple views and a status bar. Many of these elements are optional and can be hidden or displayed at will.

#### 4.2.1. The menu bar

File

  This menu offers all file related operations, like creating, saving, or closing a document, but also all version control operations. PIDA also provides sessions management, and the File menu permits to save the current session or load a previous one.

Edit

  This menu serves two purposes. First, it provides facilities to search documents throughout a project, or directories. But PIDA preferences and shortcuts settings are also modifiable from here.

Project

  This menu provides version control at project level. From there, it is also possible to modify the properties of a project and to start the configured controllers.

Tools

  Additional utilities, like a terminal and a Python shell for PIDA introspection.

View

  The PIDA window can be customized from there, displaying or hiding special views or elements like the menu bar or the tool bar. This menu also provides shortcuts to access quickly the most important views of the window, like the file manager.

Help

  Provides only the credits window for now.

#### 4.2.2. The status bar

The status bar provides live information on

- The current project.

- The current directory browsed in the file manager.

- Information on t file currently edited, like its name, encoding and size.

#### 4.2.3. The editor

The editor is the core element of PIDA. All other views only provide utilities to fill the missing features of the editor, or integrate important accessories — like a debugger — or give a quick access to external tools — like a terminal. The editor is also the central view of PIDA. All other views can be moved around it (see See Views).

PIDA can support any editor. Editor shortcuts and features directly depend on what editor you prefer. It is possible that some features of the chosen editor and PIDA features overlap. In this case, both can be used, but the feature implemented by PIDA will certainly provide better integration with the other tools of the IDE.

#### 4.2.4. Views

All elements in the PIDA window, except the editor, the menu bar, the toolbar and status bar, can be moved (remember that the menu bar and the toolbar can be hidden though).

FIXME: must choose carefully the vocabulary for elements of the views and keep them consistent.

### 4.3. PIDA configuration

FIXME: gconf, .pida

## 5. Core services

FIXME.

### 5.1. Editor

#### 5.1.1. Vim

FIXME.

#### 5.1.2. Emacs

FIXME.

### 5.2. File Manager

FIXME.

### 5.3. Project Manager

FIXME.

### 5.4. Terminal

FIXME.

### 5.5. Version Control

FIXME.

### 5.6. Preferences

FIXME.

## 6. Plug-ins

FIXME.

### 6.1. Bookmark

Manage bookmark (files, directories…)

### 6.2. Checklist

FIXME.

### 6.3. GTags

GNU Global Integration » Build global index, search through database

### 6.4. Library

FIXME.

### 6.5. Man

Search and browse man page

### 6.6. PasteBin

Send code to a pastebin service

### 6.7. Python

Show class/function from python file, and show compilation errors

### 6.8. RFC

Download RFC index, search and view RFC pages inside PIDA

### 6.9. TODO

Manage a personal todo list per project

### 6.10. Trac

View bugs from Trac project inside PIDA

## 7. PIDA Service Authoring Guide

PIDA has a very general concept of services (you might call them plugins in another application). In general, a service is able to define any PIDA function, that is anything PIDA can do, a service can do it too.

PIDA is essentially a bunch of services bound together by a Boss. The services are discovered from service directories and loaded by a Service Manager for the Boss.

### 7.1. Service Overview

A service is comprised of a directory on the file system. This directory is a Python package with data.

The structure of this directory is like so for a service named "myservice":

        myservice/
            __init__.py
            myservice.py
            service.pida
            test_myservice.py
            data/
            glade/
            pixmaps/
            uidef/
                myservice.xml

### 7.2. Creating a starter service

As will be seen, there is a large amount of boiler plate involved in creating a service, and so we have provided the creator.py script in the tools/ directory of the source distribution. You should run this with the single argument service and you will be asked a few questions to complete the process:

Example: Using tools/creator.py

    ali@book:~/working/pida$ python tools/creator.py service
    Please enter the path for the service [/home/ali/working/pida/pida/services]: /tmp
    Please enter the Service name: MyService
    Creating service my service in /tmp

### 7.3. Individual Components

#### 7.3.1. myservice.py

This is the file containing the Python code for the service. It is a Python module and should contain an attribute ``Service``, which is the Class which will be instantiated as the service.

The service class has a number of class attributes which describe its behaviour. These behaviours are:

- Configuration

- Commands

- Events

- Features

- Actions

Configuration

This is the global configuration options for the service.

Commands

Commands are the external interface for the service. They can be called by any other service, and this decoupling is cleaner than expecting, and calling an actual method on a service.

Events

Events are an asynchronous call back for the service. Any other service can subscribe to an event explicitly, and by subscribing is notified when an event occurs.

Features

Features are behaviours that a service expects other services to provide for it. If this makes no sense, imagine a situation in which a file-manager service expects any service to subscribe to its right-click menu on a file. In this way, the actions provided on that right-click menu are decentralized from the menu itself, and can be provided anywhere. This is very similar to a classical (e.g. Trac) extension point.

Actions

Actions are gtk.Actions and are used in the user interface. An action maps directly to a single toolbar and menu action, and contains the necessary information to create this user interface item from it, including label, stock image etc.

#### 7.3.2. Other files and directories

init.py

This file is required so that Python recognises the directory as a legitimate Python package.

service.pida

This empty file is just present to identify the package as a PIDA service.

data/

This directory should contain any data files for the service that are not included in the other resource directories.

glade/

This directory contains the glade files for the service's views. Although views can be created using Python-only, it is recommended for more detailed plugin views that they use glade.

pixmaps/

This directory should contain any custom pixmaps for the service. These can be used in any way.

uidef/

This directory should contain the UI Definition XML files for the service. These are gtk.UIManager XML files, and define the menu bar and toolbar items for the service. The file myservice.xml is automatically loaded by PIDA, but others can exist in this directory and could be used to populate popup menus or to be further merged with the standard UI defnition.

### 7.4. Service Options

Options are currently stored in the GConf database. They are registered at activation time of the service. Each service has its own directory in the GConf database at /apps/pida/service_name. On registering the options, if they do not exist, they are set to the default value.

Service options are defined in the service's OptionsConfig. This class should be the options_config attribute of the service class, and should subclass pida.options.OptionsConfig.

The OptionsConfig has a method named create_options, which is called on service activation. This method should contain the calls to create_option to create the options. The signature for create_option is:

    create_option(name, label, type, default, documentation)

For example:

    class MyServiceOptions(OptionsConfig):

        def create_options(self):
            self.create_option(
                'myoption',
                'myoption label',
                OTypeString,
                'default_value',
                'A string describing the option',
            )

    class MyService(Service):

        options_config = MyServiceOptions

### 7.5. Service Commands

Commands are the external interface for a service. This interface is specifically provided to other services for use of service activities.

#### 7.5.1. Defining Commands

Commands are defined as methods on the `commands_config` attribute of the Service class. This attribute should reference a subclass of `pida.core.commands.CommandsConfig` class. Any method defined on that class will be available as a command on the service.

#### 7.5.2. Calling service commands

Commands are called on a service using the `cmd` method of a service. Calling commands on other services must be performed through the Boss' `cmd` method which takes as an additional parameter then name of the target service.

For example, execute a shell from a service:

    self.boss.cmd(
        'commander',        (1)
        'execute_shell',    (2)
    )

1. The target service name

2. The target service command

#### 7.5.3. Using arguments on service commands

All arguments to service commands must be passed as keyword arguments. Because of this, they can be passed in any order after the servicename, and commandname parameters.

For example, execute a shell from a service starting in an explicit directory:

    self.boss.cmd(
        'commander',
        'execute_shell',
        cwd = '/',
    )

### 7.6. Service Events

The events are asynchronous call back for the service. So any other service can subscribe its call back to an event, and it will get called back once the event occurs.

#### 7.6.1. Events definition

To create a new event, like earlier, you just need to create a new class that you can call MyServiceEvents, and you bind it to your MyService class doing events_config = MyServiceEvents.

    class MyServiceEvents(EventsConfig):
        def create_events(self):
            [...]
        def subscribe_foreign_events(self):
            [...]

    class MyService(Service):
        events_config = MyServiceEvents

So in that example code, you can notice the two methods you need to implement to manage your own events. You have to define in create_events all the events your service is about to use, and in subscribe_foreign_events all the events from other services your service needs.

#### 7.6.2. Create your own new events

So, once you have your EventsConfig ready, you need to implement the create_events method so you can have your own new events. Three steps are needed to create an event :

    (1) You call self.create_event() on the event name
    (2) You subscribe a new callback to the event you just made
    (3) You implement the new event's callback so it acts when it is emitted.

        def create_events(self):
            self.create_event('myevent')                     # (1)
            self.subscribe_event('myevent', self.on_myevent) # (2)
            self.create_event('my_foreign_event')

        def on_myevent(self,param=None):                     # (3)
            print 'myevent receipt'
            if param != None:
                print 'with param:', param

#### 7.6.3. Subscribe to other services' events

We have seen how we can bind callbacks to events you created in your own service. But you often need to interact with other services as well. To do so, you need to implement the subscribe_foreign_events() method the following way :

        def subscribe_foreign_events(self):
            self.subscribe_foreign_event('editor', 'started',
                                         self.on_editor_startup)

for each event you want to bind a call back, you need to call the subscribe_foreign_event() method. In the example above, when the editor service launches the started event, self.on_editor_startup() gets called.

    self.subscribe_foreign_event('SERVICE_NAME', 'EVENT_NAME', CALLBACK_FUNCTION)

where SERVICE_NAME is the destination service, EVENT_NAME the event to bind to, CALLBACK_FUNCTION the function to be called when the event is emitted.

Now suppose you want to give other services' programmers an event of your own service. To do so, you need to call create_event() in create_events() with the name of your event (ie see my_foreign_event above).

Then in the foreign service, in the subscribe_foreign_events() method you just need to subscribe to the event:

        def subscribe_foreign_events(self):
            self.subscribe_foreign_event('myservice', 'my_foreign_event',
                                         self.on_myservice_foreign_event)

and finally define your callback.

#### 7.6.4. Events emition

Now you have defined and bound all your events in your service and all you need is to emit them when you need them to be executed. Well, it's fairly simple, just call the emit() method :

        [...]
        self.emit('myevent')
        self.emit('myevent', param='hello world')
        self.emit('my_foreign_event')
        [...]
        self.get_service('myservice').emit('myevent')
        self.get_service('myservice').emit('myevent', param='hello from some other place')
        self.get_service('myservice').emit('my_foreign_event')
        [...]

As you can see in the examples above, emit can be used in different contexts and with or without parameters. As a rule, every event defined can be called using the emit() method either from your own service (ie in MyService) or from someone else's service (then you use get_service().emit()).

If your callback function needs parameters, you need to give the options to the emit method. You can also use, as in the above example, non-mandatory parameters.

### 7.7. Service Views

Service views are almost anything that appears visually in PIDA (apart from the main toolbar and menubar). All of these views belong to a service.

#### 7.7.1. Creating Views

Views may be designed in Glade3, or in pure [PyGTK]. Each method of view creation has its advantages and disadvantages, and these are discussed below.

#### 7.7.2. Glade3 Views

Views created with Glade3 have the following advantages:

- Better maintainability

- Automatic signal callback connection

The glade-file itself should be places in the directory glade/ in the service directory, and should be named appropriately so as not to conflict with any other service glade file. The extension `.glade` is preferred. So, for example a well named glade file is `project-properties-editor.glade`.

This glade file is used by subclassing `pida.ui.views.PidaGladeView` and setting the gladefile attribute on the class, for example for the glade file above:

    from pida.ui.views import PidaGladeView

    class ProjectPropertiesView(PidaGladeView):

        gladefile = 'project-properties-editor'

| The glade file attribute omits the extension part of the file name.

The glade-file should contain a single top-level container (usually a `gtk.Window`), and this must have the same name as the glade file (without extension.

The widget inside this container will be taken out of the Window and incorporated into Pida's view.

All widgets in the glade view, are attached to the view instances namespace, so that they can be accessed from the instance, for example if there is a text entry called `name_entry`, the attribute `self.name_entry` or `my_view.name_entry` would reference that entry.

Signals of items in the glade view are automatically connected if you provide the correct method on the glade view. These methods are named as `on_<widget_name>__<signal_name>`. For example, if there is a button on the view called `close_button`, and you wish to connect to it's `clicked` signal, you would provide the following method in order to automatically connect the signal for the widget:

    def on_close_button__clicked(self, button):
        print '%s was clicked!' % button

#### 7.7.3. Pure PyGTK Views

These views should subclass `pida.ui.views.PidaView` and should create the necessary widgets by overriding the create_ui method. The widgets can be added to the view by using the `view.add_main_widget(widget, expand=True, fill=True)`. The widgets will be added to the top-level VBox in the view.

There is no signal autoconnection, and widgets behave exactly as if they had been created with PyGTK in any other circumstance.

#### 7.7.4. Instantiating views

The service can instantiate its views at any time. They should pass the instance of the service as the first parameter to the View constructor. The service will then be stored as the `svc` attribute on the view.

#### 7.7.5. Adding Views to PIDA

Views are displayed at runtime by calling the window service's command add_view. The required paned must be passed as well as the view itself.

The paned attribute to the command should be one of:

- `Buffer`

- `Plugin`

- `Terminal`

The buffer paned is the left sidebar, the plugin paned is the right sidebar, and the terminal paned is the bottom bar. In general the guidelines for which paned to add views to are:

- Permanent views should be added to the Buffer paned

- Views relating to the current document should be added to the Buffer or Plugin paned

- Configuration or property views should be added to the Plugin paned

- Multiple view (eg terminal emulators, diffs, and web browsers), or those with a lot of data should be added to the Terminal paned.

An example of adding a view of type `MyServiceView` to the Terminal paned is as follows:

    # Override the start method as a hook to when the service starts
    def start(self):
        view = MyServiceView(self)
        self.boss.cmd('window', 'add_view', paned='Terminal', view=view)

Numerous other examples are available in almost every service in `pida.services`.

#### 7.7.6. View icons and labels

View icons (the image displayed on the paned button) are referred to by their stock ID, and set as a class attribute on the view `icon_name`. Similarly, the text associating the icon is set as a class attribute on the view called 'label_text`.

Additionally, an `icon_name` and/or a `label_text` attribute can be passed to the view constructor, and these will be displayed as the view's label and icon when it is added to the PIDA main view.

### 7.8. Using custom pixmaps in services

Any pixmap placed in the pixmaps directory in the service (`myservice/pixmaps`) will automatically be added as a stock image and can be used by the service using its name (without extension) for View icons or for gtk.Buttons or gtk.Images or any other widget which take a stock_id as an argument.

### 7.9. Links

1. [PyGTK] PyGTK Website

## 8. PIDA Plugin Authoring Guide

PIDA plugins are very much identical to Services. Anything you can do in a Service, you can also do in a Plugin. There are however a few minor differences, based on the facts that:

1. Plugins can be loaded and unlaoded at runtime

2. Plugins can be published on the PIDA community and installed

PIDA uses Plugins for all non-core funcitonality, and we have been quite strict about this, so that we can maintain a different release schedule for the core, and individual plugins. Because of this, Plugins which you might expect to find in a standard IDE or a standard Python IDE must be installed. Fortunately this is a matter of a single click.

### 8.1. The service.pida file

The service.pida file in Plugins is in the ini format with themetadata under the [plugin] tag. It contains metadata that is used by the installer and by the community website. This metadata includes:

Table: Service.pida metadata
Attribute | Description
--- | ---
plugin * | Technical name of plugin (only [a-z0-9_] name)
name * | Long name of plugin
version * | Version of plugin
author * | Name of author <email>
require_pida * | Version of PIDA
category * | Category of plugins
depends | List of dependencies
lastupdate | Date of last update
website | Website of plugin

* These fields are mandatory

Example: An example service.pida file

    [plugin]
    plugin = snippets
    name = Snippets
    author = Ali Afshar <aafshar@gmail.com>
    version = 0.1
    require_pida = 0.5
    depends = ""
    category = code
    description = Snippets: automatically enter repetitive text

### 8.2. Publishing Plugins

Plugin publishing can be done from the safety of the PIDA user interface. First you will need to create the service directory (our advice is to use the tools/creator.py script as outlined in the service authoring guide above). Once your plugin is created, in PIDA, select Plugin Manager from tools, and select the Publish tab. Enter the directory containing the service, and your username and password for the pida community website. You will be given a chance to edit the service metadata in the user interface. When you are happy, select the Make package and upload button to complete the process.

| The plugin will be placed on standby, and approved by one of the developers. Once it is approved, anyone can download it.

### 8.3. Limitations to plugins

The single limitation to a plugin is that it should not (although it can) provide events that can be subscribed to. This is because a plugin can be loaded and unloaded at runtime, and so plugins that depend on other plugins' events will cease to function.

We say "should not" rather than "must not" because you can actually do what you like. We have a strong philosophy about not getting in your way, but be warned that you have been warned!

## 9. PIDA Coding Style Guidelines

First read [PEP8] (the PEP on how to write readable Python code). The PEP gives a number of good insights. The PEP gives a few options on things, and I shall try to clarify what I prefer here. Where this document differs from PEP8_, you should use what is presented here, unless you are a zealot in which case you should listen to the Python people (who are cleverer than me anyway). Also read PEP20_ while you are at it.

### 9.1. Indenting

4 Spaces, no tabs ever ever. This is not negotiable. Emacs users please check your settings, somehow tabs creep into emacs-written code.

### 9.2. Line Width

79 characters, perhaps 78 to be safe. This is negotiable, and there are times when 83 character lines are acceptable. You can be the judge. I am not sure many people use 80-character terminals these days, so we can be a bit less hard-line than the PEP.

You can split lines however you wish. I personally use 3 different forms of splitting depending on the purpose.

Long lists, dicts, or many paramteres to a function:

    service_base_classes =  [
        OptionsMixin,
        commands_mixin,
        events_mixin,
        bindings_mixin,
    ]

Single extra bit:

    def really_long_method_or_function_name(first_parameter, second_paramater,
        third_parameter)

Or:

    def really_long_method_or_function_name(first_parameter, second_paramater,
                                            third_parameter)

It all depends on the use at the time, and we should remember to keep it readable.

### 9.3. Blank Lines

As [PEP8] for 2 lines between top-level classes and functions, with one line between methods.

Extra blank line "to indicate logical blocks" should be avoided at all costs in my opinion. Real logical blocks should be used to indicate logical blocks! If you have to do this, a comment is better than a blank line.

### 9.4. Imports

Only import the function or class you want to use, for example:

    from pida.ui.views import PidaView, BaseView

There are a few common exceptions like:

    import gtk

Multiple top-level imports are fine too if you like, but best grouped by where they are comming from:

    import os, sys
    import gtk, gobject, pango

Remember to import in this order:

1. standard library imports

2. related third party imports

3. PIDA application/library specific imports

### 9.5. Whitespace

Yes:

    def foo(blah, baz):

No:

    def foo ( blah , baz ):

    def foo(blah,baz):

(that space after a comma is basic punctuation)

[PEP8] has oodles on this.

### 9.6. Docstrings

I like having the triple quotes as doubles, and for them to be on empty lines, like so:

    def foo():
        """
        This is the single-line docstring
        """

Docstrings are plain nice, so please try to use them for all functions. I am guilty of being lazy, so I can't blame anyone. Also we use API generation which uses these doc strings, so it all helps.

We use Pydoctor_ with ReStructured text directives for API generation, so I guess you should look them up too.

### 9.7. Strings

Single quoted, unless you need single quotes in them, in which case use double quotes:

    my_string = 'I am a banana'
    my_other_string = "I am a banana's uncle"

### 9.8. Naming

- Modules as lowercase single words with no underscores, except test modules which should start with `test_`.

- Functions as lower_case_with_underscores.

- Classes is CamelCase. (Note: I hate camel case, but it is useful, even in Python to know the difference between a class and a function. Why? You can subclass a class.)

- Module-level constants all in UPPERCASE_WITH_UNDERSCORES.

### 9.9. Conditional blocks

This is fine:

    if blah:
        baz = 1
    else:
        baz = 2

And better than:

        baz = 2
        if blah:
            baz = 1

But I am not going to argue, needs can force you into a certain style. Remember, readability is key.

### 9.10. Magic

I hate magic, perhaps because I am dumb. I am really wary of using some of Python's shoot-me-in-the-foot techniques because I have to maintain the code, so. I have made these mistakes myself, and have (hopefully learned from the mistakes. So:

Meta classes

  Never! I have yet to see a use-case for metaclasses which did not relate to perverting some other library or external class. I am happy to be enlightened.

Decorators

  Make perfect sense in some cases, but have the danger of being over used, so please think carefully whether you are using them to decorate behaviour, or just using them for the sake of it.

Inner classes

  I have yet to see a use-case that requires these.

### 9.11. Bibliography

1. [PEP8] Python Enhancement Proposal 8

2. [PEP20] Python Enhancement Proposal 20

3. [Pydoctor] Pydoctor Web Site