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
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. Individual Components
7.2.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.2.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.3. 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.4. Service Commands
Commands are the external interface for a service. This interface is
specifically provided to other services for use of service activities.
7.4.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.4.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)
)
-
The target service name
-
The target service command
7.4.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.5. 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.5.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.5.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.5.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.5.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.6. 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.6.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.6.2. Glade3 Views
Views created with Glade3 have the following advantages:
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.6.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.6.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.6.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:
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.6.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.7. 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.8. Links
-
[PyGTK] PyGTK Website
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.
8.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.
8.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.
8.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.
8.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:
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:
-
standard library imports
-
related third party imports
-
PIDA application/library specific imports
8.5. Whitespace
Yes:
No:
def foo ( blah , baz ):
def foo(blah,baz):
(that space after a comma is basic punctuation)
[PEP8] has oodles on this.
8.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.
8.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"
8.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.
8.9. Conditional blocks
This is fine:
if blah:
baz = 1
else:
baz = 2
And better than:
But I am not going to argue, needs can force you into a certain style.
Remember, readability is key.
8.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.
8.11. Bibliography
-
[PEP8] Python Enhancement Proposal 8
-
[PEP20] Python Enhancement Proposal 20
-
[Pydoctor] Pydoctor Web Site
