= PIDA Handbook


//////////////////////////////////////////////////////////////////////////////
Please note here typo or documentation format rules that should be consistent
throughout the whole document.

- PIDA should always be written PIDA for now. A find and replace will change
   this if necessary.

- The attitude of the writer (using first person, using 'you' or 'the user' to
   speak about the reader...) should be consistent throughout the whole
   document. It is not decided what this attitude shall be yet.

- Anchors should be explicit and composed using the hierarchy of the document
   ie: services_project_manager for Project Manager title in Services.
//////////////////////////////////////////////////////////////////////////////


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.

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


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

[[introduction]]
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.
footnote:[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.

[[requirements]]
== 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.

=== 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.

=== 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.


[[installation]]
== 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.

[[installation_compilation]]
=== 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
-------------------------------------------

[NOTE]
.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
------------------------------------------------------------------------------

[NOTE]
==============================================================================
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:

[NOTE]
==============================================================================
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
------------------------------------------------------------------------------

=== 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.

[[installation_packages]]
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.

.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
-------------------------------------------------

IMPORTANT: 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.

[[installation_windows]]
MS Windows
~~~~~~~~~~
FIXME.

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

[[installation_mac]]
Mac OS X
~~~~~~~~
FIXME.


[[getting_started]]
Getting started
---------------
FIXME.

[[getting_started_wizard]]
First run wizard
~~~~~~~~~~~~~~~~
NOTE: This feature is planned for a future version of PIDA, which is still undetermined yet.

[[getting_started_window]]
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.

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.

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.

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 xref:getting_started_window_views[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.

[[getting_started_window_views]]
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.

[[getting_started_configuration]]
PIDA configuration
~~~~~~~~~~~~~~~~~~
FIXME: gconf, .pida

[[services]]
Core services
-------------
FIXME.

=== Editor

==== Vim

FIXME.

==== Emacs

FIXME.

File Manager
~~~~~~~~~~~~
FIXME.

[[service_project_manager]]
Project Manager
~~~~~~~~~~~~~~~
FIXME.

[[service_terminal]]
Terminal
~~~~~~~~
FIXME.

[[service_version_control]]
Version Control
~~~~~~~~~~~~~~~
FIXME.

Preferences
~~~~~~~~~~~
FIXME.


[[plugins]]
Plug-ins
--------
FIXME.

Bookmark
~~~~~~~~
Manage bookmark (files, directories...)

Checklist
~~~~~~~~~
FIXME.

GTags
~~~~~
GNU Global Integration » Build global index, search through database

Library
~~~~~~~
FIXME.

Man
~~~
Search and browse man page

PasteBin
~~~~~~~~
Send code to a pastebin service
 
Python
~~~~~~
Show class/function from python file, and show compilation errors

RFC
~~~
Download RFC index, search and view RFC pages inside PIDA

TODO
~~~~
Manage a personal todo list per project

Trac
~~~~
View bugs from Trac project inside PIDA

== 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.

=== 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
---------------------------

=== 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:

.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
------------------------------------------------------------------------

=== Individual Components

==== 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.

==== 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.


=== 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
-----------------------------------------------

=== Service Commands

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

==== 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.

==== 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

==== 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 = '/',
)
-------------------------------------------

=== 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.

==== 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.

==== 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
------------------------------------------------

==== 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.

==== 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.

=== 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.


==== 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.

==== 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'
----------------------------------------------------

[NOTE]
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
-----------------------------------------------------

==== 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.

==== 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.

==== 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`.

==== 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.

=== 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.

=== Links

+ [[[PyGTK]]] http://pygtk.org[PyGTK Website]

== 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.

=== 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:

.Service.pida metadata
[grid="all"]
'-------------'---------------------------------------------------------------
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_

.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
------------------------------------------------------------------------------

=== 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.

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

=== 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!


== 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.

=== Indenting

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

=== 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.

=== 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.

=== 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

=== 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.

=== 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.

=== 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"
------------------------------------------

=== 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.

=== 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.

=== 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.

=== Bibliography

+ [[[PEP8]]] http://www.python.org/dev/peps/pep-0008/[Python Enhancement Proposal 8]
+ [[[PEP20]]] http://www.python.org/dev/peps/pep-0020/[Python Enhancement Proposal 20]
+ [[[Pydoctor]]] http://codespeak.net/~mwh/pydoctor/[Pydoctor Web Site]

// vim: set filetype=asciidoc :
