|
|
|
=========================
|
|
|
|
Mitter Hacking Guidelines
|
|
|
|
=========================
|
|
|
|
|
|
|
|
First of all, Mitter is a Python project and it tries to follow PEP8_
|
|
|
|
as close as possible. Sometimes we fail, but we try to adhere to it
|
|
|
|
as much as possible. The Google Guidelines_ for Python are a good
|
|
|
|
summary about it, although we don't follow all their recommendations:
|
|
|
|
|
|
|
|
- We use PyFlakes instead of Pychecker. PyFlakes seems to be better in
|
|
|
|
finding unused imports. As usual, some files don't adhere to it,
|
|
|
|
mostly helper tools (Sphinx and the helper PEP8 checker, for
|
|
|
|
example.)
|
|
|
|
- Exceptions do not start with an Error class. Each module should have
|
|
|
|
its own Exception, e.g. NetworkError and all other exceptions
|
|
|
|
should use that as base, e.g. ::
|
|
|
|
|
|
|
|
class UnreachableNetworkError(NetworkError):
|
|
|
|
|
|
|
|
- Function parameters do not need to follow the break lines pointed,
|
|
|
|
but must follow the 80 columns rule.
|
|
|
|
|
|
|
|
Also, other rules we follow:
|
|
|
|
|
|
|
|
- All string formating must have the variables in parenthesis. In this
|
|
|
|
case, this is wrong::
|
|
|
|
|
|
|
|
text = '%d characters' % count
|
|
|
|
|
|
|
|
this is right::
|
|
|
|
|
|
|
|
text = '%d characters % (count)
|
|
|
|
|
|
|
|
- Unless it's a work in progress, do not leave code commented (or,
|
|
|
|
worse yet, inside a ``if 0:`` block.) If it's a WIP, be sure to
|
|
|
|
comment what it is (e.g. "Working on issue #X" or "Trying to make
|
|
|
|
the field count properly".)
|
|
|
|
|
|
|
|
|
|
|
|
Documentation
|
|
|
|
=============
|
|
|
|
All documentation (including this file!) follows the Sphinx_ format
|
|
|
|
(ReSTructured_ format). This includes docstrings and external files.
|
|
|
|
|
|
|
|
Creating Interfaces
|
|
|
|
===================
|
|
|
|
There is a couple of things you should take care when creating your
|
|
|
|
own interface.
|
|
|
|
|
|
|
|
Naming and Location
|
|
|
|
-------------------
|
|
|
|
Your file must have the prefix "ui\_". It must be installed in the
|
|
|
|
``mitterlib/ui`` directory.
|
|
|
|
|
|
|
|
class Interface
|
|
|
|
---------------
|
|
|
|
Inside your module, there should be at least one class called
|
|
|
|
``Interface``. It may inherit any other class (or ``object`` in case
|
|
|
|
you don't need anything).
|
|
|
|
|
|
|
|
__init__(self, connection, options)
|
|
|
|
-----------------------------------
|
|
|
|
The initialization will receive two parameters:
|
|
|
|
|
|
|
|
- connection: the network connection. Your interface will request any
|
|
|
|
network data with that object. You can check the ``Networks`` object
|
|
|
|
in the ``mitterlib/network/__init__.py`` for methods there (or read
|
|
|
|
the Sphinx documentation generated about it.)
|
|
|
|
|
|
|
|
- options: It's a ConfigOpt_ object, with all your interface options.
|
|
|
|
Use it for EVERTYHING that you'd hardcode.
|
|
|
|
|
|
|
|
__call__(self)
|
|
|
|
--------------
|
|
|
|
Once Mitter have everything set up, it will call your interface.
|
|
|
|
``__call__`` is to interfaces as ``run()`` is to threads.
|
|
|
|
|
|
|
|
options(self, options)
|
|
|
|
----------------------
|
|
|
|
``options`` is a ``@classmethod`` called by Mitter on the setting up
|
|
|
|
phase to populate the interface options. To add an option, use the
|
|
|
|
``add_option``; if your interface don't have any options, simply
|
|
|
|
return. Again, refer to the ConfigOpt_ documentation on how to use it.
|
|
|
|
|
|
|
|
NAMESPACE
|
|
|
|
---------
|
|
|
|
The namespace is a class variable used to identify the name of the
|
|
|
|
network. It should also be used in the config as the group name.
|
|
|
|
|
|
|
|
Creating Networks
|
|
|
|
=================
|
|
|
|
Naming and Location
|
|
|
|
-------------------
|
|
|
|
Network reside in the ``mitterlib/network`` directory. Contrary to
|
|
|
|
interfaces, it doesn't require any special prefixes.
|
|
|
|
|
|
|
|
Base Class
|
|
|
|
----------
|
|
|
|
All networks must inherit from the :class:`NetworkBase` object, in
|
|
|
|
the module ``networkbase``. There is a couple of method you should
|
|
|
|
implement in case you want it to return any data. If the network
|
|
|
|
doesn't support some functionality (e.g. reposts), simply don't
|
|
|
|
declare the function. :class:`NetworkBase` offers good defaults to
|
|
|
|
all functions (basically, returning nothing.)
|
|
|
|
|
|
|
|
class Connection
|
|
|
|
----------------
|
|
|
|
Inside your module, you should have at least once class called
|
|
|
|
``Connection``. As pointed before, it should inherit from the
|
|
|
|
:class:`NetworkBase` clas.
|
|
|
|
|
|
|
|
Base Return Object
|
|
|
|
------------------
|
|
|
|
Most functions will return a :class:`NetworkData` object. It offers
|
|
|
|
an unified data format for every interface, so they don't need to
|
|
|
|
worry about each network data. It is wise to create your own
|
|
|
|
:class:`NetworkData`, inheriting from it, with its own ``__init__``
|
|
|
|
and setting the properties.
|
|
|
|
|
|
|
|
Proxy support
|
|
|
|
-------------
|
|
|
|
Mitter supports proxies. Its value is in the configuration manager, in
|
|
|
|
the ``NetworkManager`` section, ``proxy`` value. The network manager
|
|
|
|
itself will install a urllib2 proxy handler, so you don't need to
|
|
|
|
worry about manually installing a handler yourself if you use urllib2.
|
|
|
|
|
|
|
|
NAMESPACE
|
|
|
|
---------
|
|
|
|
The namespace is a class variable used to name the interface. It's
|
|
|
|
also used in the ``--interface`` so the user can name the interfaces
|
|
|
|
they want.
|
|
|
|
|
|
|
|
PRIORITY
|
|
|
|
--------
|
|
|
|
Interface priority, as a class variable. It's used by the interface
|
|
|
|
manager to select an interface in case the user doesn't have one. The
|
|
|
|
higher this value, the higher the priority. Be sure to put interfaces
|
|
|
|
with more dependencies with higher priorities, as those should be, in
|
|
|
|
theory, more full featured.
|
|
|
|
|
|
|
|
Mixing It All
|
|
|
|
=============
|
|
|
|
|
|
|
|
Creating New Elements
|
|
|
|
---------------------
|
|
|
|
In case you want to display/add a new element on your interface, you
|
|
|
|
need to add the element in :class:`NetworkData` with a default that
|
|
|
|
represents it better (for boolean values, set it to False; strings to
|
|
|
|
''; numbers to 0 or 0.0). Once your element is there, you can add it
|
|
|
|
in the networks (do not ignore other networks that may use that
|
|
|
|
information!) and then, finally, use it on your interface.
|
|
|
|
|
|
|
|
Creating New Request
|
|
|
|
--------------------
|
|
|
|
If you want to add a new functionality in the interfaces, you need do
|
|
|
|
to a couple of steps:
|
|
|
|
|
|
|
|
- First of all, you need to add the method in the :class:`Networks`.
|
|
|
|
Remember that this is the class that the interfaces receive to do
|
|
|
|
all the other calls. If the function doesn't exist there, it won't
|
|
|
|
be call it at all.
|
|
|
|
|
|
|
|
- Once the function is available to be called, you need to make it
|
|
|
|
available to the networks. For this, add the function in
|
|
|
|
:class:`NetworkBase` module, so calling it on networks that don't
|
|
|
|
have that method defined yet will still work. In this point, it
|
|
|
|
should return some sort of empty value (empty list, None).
|
|
|
|
|
|
|
|
- Finally, add the function on your network. Follow the same name in
|
|
|
|
the :class:`NetworkBase` and you should be fine.
|
|
|
|
|
|
|
|
Developer Discussion
|
|
|
|
====================
|
|
|
|
Mitter have an open developer discussion maillist. Join us on
|
|
|
|
Mitter-Dev_ if you have any suggestions/patches/questions.
|
|
|
|
|
|
|
|
(We had a massive problem with spammers in the recent days, so the
|
|
|
|
list is currently moderated. Your first message needs to be approved
|
|
|
|
and, after that, everything should be fine.)
|
|
|
|
|
|
|
|
Souce Code Repository
|
|
|
|
=====================
|
|
|
|
Mitter uses Git for SCM and Gitorious to host it. You can check the
|
|
|
|
Mitter_ project there, clone it and hack away! ;)
|
|
|
|
|
|
|
|
|
|
|
|
.. _PEP8: http://www.python.org/dev/peps/pep-0008/
|
|
|
|
|
|
|
|
.. _Guidelines: http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
|
|
|
|
|
|
|
|
.. _Sphinx: http://sphinx.pocoo.org/
|
|
|
|
|
|
|
|
.. _ReSTRuctured: http://docutils.sourceforge.net/docs/user/rst/quickref.html
|
|
|
|
|
|
|
|
.. _ConfigOpt: http://deadbraincells.org/configopt/docs/configopt.html
|
|
|
|
|
|
|
|
.. _Mitter-Dev: http://groups.google.com/group/mitter-dev/
|
|
|
|
|
|
|
|
.. _Mitter: http://gitorious.org/projects/mitter
|