####################################
PowerConsole Extension Specification
####################################

.. extension-object:

Extension Interface Specification
=================================

PowerConsole execution engine is extensible through user defined Python objects that are passed to PowerConsole
constructor. These objects must conform to this Extension Interface Specification.

Specification v1
----------------

.. attribute:: name

   *Mandatory* attribute containing **unique** name of the extension package.

.. attribute:: version

   *Mandatory* attribute containing package version.

.. attribute:: summary

   *Mandatory* attribute containing short package description.

.. attribute:: url

   *Mandatory* attribute containing URL to package home website.

.. attribute:: download_url

   *Mandatory* attribute containing URL to package download area.

.. attribute:: description

   *Mandatory* attribute containing package description.

.. attribute:: author

   *Mandatory* attribute containing package author name.

.. attribute:: author_email

   *Mandatory* attribute containing author's contact e-mail address.

.. attribute:: license

   *Mandatory* attribute containing license used for package distrbution.

.. method:: controller_extensions()

   *Optional* method. When defined must return list of :ref:`controller extension objects <controller-extender>`.

.. method:: commands()

   *Optional* method. When defined must return list of :ref:`command objects <cmd-class>`.

.. method:: show_extensions()

   *Optional* method. When defined must return list of :ref:`show extension objects <show-extension>`.

.. method:: help_providers()

   *Optional* method. When defined must return list of :ref:`help provider objects <help-provider>`.

.. method:: object_renderers()

   *Optional* method. When defined must return list of :ref:`object renderer objects <text-renderer>`.


If you are going to use setuptools_ for your extension package distribution (which is recommended), you may
use the provided base class :class:`~pwc.base.ExtensionPackage` for your extension object. This base class
implements all mandatory attributes and can fill their values from setuptools package metadata.

.. _extension-package:

Extension Package Specification
===============================

Extensions could be packaged and distributed in any format, but official PowerConsole applications will support
only extensions that would conform to this Extension Package Specification. So if you're planning to develop
extensions for public use, or PowerConsole-based applications that would support thrid-party extensions, you
should follow this specification in your product.

Specification v1
----------------

Package must be a setuptools_ package that registers at least one 'powerconsole.package' entry point.

Example :file:`setup.py` for package::

    from setuptools import setup, find_packages
    
    setup(
        ...
        entry_points = {
            'powerconsole.package': [   
                'firebird = pwc.fbcmd:packageFirebird'
        },
        ...
        )

Each registered callable (it could be a function or class) should accept keyword arguments and must return single
object conforming to Extension Interface Specification. 


.. _setuptools: http://peak.telecommunity.com/DevCenter/setuptools