Introduction
============

This is the user guide for dip.  dip is an application development and
integration framework for `Python <http://www.python.org>`_ and toolkits based
on `PyQt <http://www.riverbankcomputing.com/software/pyqt/>`_.  It supports
Python v2.6, v2.7 and v3.

dip encourages the development of applications based on reusable components.
This applies both to the development of new components so that they can be
reused in the future in a different context, and to the reuse of existing
components that were developed independently of dip.

Developers can choose to use the different parts of dip as required.  Unlike
many frameworks dip does not require its wholesale adoption to develop an
application.  dip makes it easy to take an existing application and refactor it
gradually to make use of dip's features.  Developers can also choose to replace
different parts of dip with their own implementations.  The :ref:`architecture`
section describes this in more detail.

The dip API is fairly stable but will not be finalized until v1.0.  dip should
not be considered for production applications until v1.0 is released.  The
:ref:`roadmap` section provides details of the planned development.


Features
--------

The current version of dip has the following features:

- a declarative type system where class attributes define the types of
  instance attributes that are created automatically when the class is
  instantiated

- the ability to define :term:`interfaces<interface>` and to write
  :term:`adapters<adapter>` that allow an object to appear to implement an
  interface without needing to change the object itself

- the ability to specify a user interface declaratively.  When combined with
  the type system it is possible to create a user interface that allows the
  user to edit a data model with a single line of code

- a default user interface shell that implements the menu hierarchies, context
  menus, toolbars etc. common to many applications

- support for user settings including, if enabled, the automatic saving and
  restoration of the geometry and configuration of a user interface

- dip's user interfaces are testable because a user's actions can be simulated
  programatically

- a framework for defining types of storage and data formats for reading and
  writing application objects

- support for alternative toolkits.  This does not mean that any toolkit can be
  supported - a toolkit must be based on Qt.  It does mean that an application
  can automatically use, for example, KDE widgets rather than the corresponding
  Qt widgets if they are available

- a :term:`plugin` system that encourages the decoupling, and easy reuse, of
  components through the use of :term:`services<service>` and
  :term:`extension points<extension point>`

- the ``dip-builder`` utility that is be used to create a stub application
  that can be run immediately, and can create a packaged version of the
  application for easy deployment.  (At the moment only :mod:`distutils` is
  supported.)

- the ``dip-automate`` utility that is used to automate the user's interaction
  with any PyQt application without requiring changes to the application
  itself.


License
-------

Like PyQt, dip is available under two licenses: the GPL (both v2 and v3), and
the Riverbank Commercial License.  Dual licensing is based on the principle of
quid pro quo - something for something.

If you, your company or your organisation derive commercial benefit from
Riverbank's products and do not wish to distribute your complete source code
you are required to purchase the appropriate number of commercial licenses.

Alternatively, if you are willing to follow the terms of the GPL, Riverbank
software is available to you under Open Source licenses which allows you to
develop, modify and distribute your software freely.  If you wish to use an
open source version of Riverbank's products, you must contribute all your
source code to the open source community, according to the terms of the
applicable open source license.

By offering both open source and commercial licenses, Riverbank ensures the
availability of resources for ongoing development and improvement of its
products.  By purchasing commercial licenses, you are no longer obligated to
publish your source code.


Installation
------------

dip is provided as a source packages created by Python's distutils module.
After unpacking the ``.tar.gz`` or ``.zip`` file run following command::

    python setup.py install

If you want to run the tests then change to the ``test`` directory and run the
following command::

    python runtests.py

If you want to re-create the documentation then change to the ``doc``
directory and run the following command::

    make html

dip is also available as a `Mercurial repository
<http://www.riverbankcomputing.com/hg/dip/>`_.
