6. Extend couchapp

Couchapp can easily be extended using external python modules or scripts. There are 3 kind of extensions:

  • extensions: allows you to add custom commands to couchapp
  • hooks: allows you to add actions on pre-/post (push, clone, pushdocs, pushapps) events.
  • vendors handlers: allows you to add support for different sources of vendor

Extensions

Extensions are eggs or python modules registered in the config file in extensions member, e.g.:

"extensions": [
   "egg:mymodule#name"
]

Eggs uri are entry points uri starting with egg: prefix. To just load python module use an uri with the form: python:mymodule.myextension.

To load eggs add an entry point in couchapp.extension sections. More info about entry points here.

An extension is a python module loaded when couchapp start. You can add custom commands to couchapp via this way. To add custom commands simply add a dict named cmdtable. This dict is under the format:

cmdtable = {
    'cmdname': (function, params, 'help string'),
}

params is a list of options that can be used for this function (the -someoption/–someoption= args):

params = [
    ('short', 'long', default, 'help string'),
]

short is the short option used on command line (ex: -v) long is the long option (ex: –verbose)

default could be True/False/None/String/Integer

Hooks

Couchapp offers a powerful mechanism to let you perform automated actions in response of different couchapp events (push, clone, generate, vendor).

Hooks are eggs or python modules registered in the config file in hooks member, e.g.:

"hooks": {
    "pre-push": [
        "egg:couchapp#compress"
    ]
}

Like extennsions egg uri start with egg: prefix and python module with python:. Entry point are added to couchapp.hook distribution. Here is the declaration of coupress hook in couchapp setup.py:

setup(
    name = 'Couchapp',
    ...

    entry_points="""
    ...

    [couchapp.hook]
    compress=couchapp.hooks.compress:hook

    ...
    """,

    ...
)

hooks are python functions like this:

def hook(path, hooktype, **kwarg):
    ...

path is the directory of the CouchApp on the filesystem, hooktype is the name of the event pre-/post-(push|clone|generate|vendor) and kwargs a list of arguments depending on the event:

  • push: dbs: list of Database object
  • clone: source: the source of the couchapp to clone
  • vendor: source, the uri of vendor, action, could be install or update.
  • generate: None

Have a look in compress hook source for a complete example.

Vendors handlers

for vendor_uri in self.conf.get('vendors'):
    obj = util.parse_uri(vendor_uri, "couchapp.vendor")
    vendors_list.append(obj)

Vendors handlers are used to manage installation or update of vendors. Like extensions or hooks vendors handlers are eggs or python modules registered in config file:

{
    "vendors": [
        "egg:couchapp#git",
        "egg:couchapp#hg",
        "egg:couchapp#couchdb"
    ]
}

(above is the default). Entry point are added to couchapp.vendor distribution, e.g.:

setup(
    name = 'Couchapp',
    ...

    entry_points="""
    [couchapp.vendor]
    git=couchapp.vendors.backends.git:GitVendor
    hg=couchapp.vendors.backends.hg:HgVendor
    couchdb=couchapp.vendors.backends.couchdb:CouchdbVendor

    ...
    """,

    ...
)

A vendor is an object inheriting couchapp.vendor.base.BackendVendor class:

class MyVendor(BackendVendor):
    """ vendor backend interface """
    url = ''
    license =  ''
    author = ''
    author_email = ''
    description = ''
    long_description = ''

    scheme = None

    def fetch(url, path, *args, **opts):
        ...
url:is the url of the vendor source
license:the license of the vendor
author:name of author
author_email:email of author
description:short description of this vendor
long_descrtiption:
 long description
scheme:list of url prefix on which this handler will be use. (e.g.: [‘git’, ‘git+ssh’] for git://|git/ssh:// urls)

The fetch function take the url given in console, the path of couchapp.

Here is an example for the default git vendor:

class GitVendor(BackendVendor):
    url = 'http://github.com/couchapp/couchapp'
    author = 'Benoit Chesneau'
    author_email = 'benoitc@e-engura.org'
    description = 'Git vendor handler'
    long_description = """couchapp vendor install|update from git::

    git://somerepo.git (use git+ssh:// for ssh repos)
    """

    scheme = ['git', 'git+ssh']

    def fetch(self, url, path, *args, **opts):
        ....

Full source is on the git repo.