[[html(<h1 style="margin-bottom: 0;">Concordance</h1><div style="margin: 0 0 1em 0;padding: 0;">noun</div>)]]
  1. a harmonious state of things in general and of their properties (as of colors and sounds);
  2. congruity of parts with one another and with the whole;
  3. '''a robust XMPP service framework for Python 3'''

== Introduction ==

[http://xmpp.org/ XMPP] (eXtensible Messaging and Presence Protocol) is an excellent foundation for countless custom services.  Concordance is a framework for building and deploying those custom XMPP services rapidly, especially with the goal of building web applications.


== Paradigm ==

When web applications are written in XMPP content is published to and managed by Concordance in XML form.  For example, an application which allows a user to record books in her library could use a [http://xmpp.org/extensions/xep-0004.html data form] to receive the title, author, and isbn of the book.  The application could then generate the following XML record internally:

{{{
<library xmlns="http://concordance-xmpp.org/apps/mybookcase">
  <book>
    <title>Dive Into Python 3</title>
    <author>Mark Pilgrim</author>
    <isbn>9781430224150</isbn>
  </book>
</library>
}}}

This internal record is "published" to the [http://xmpp.org/extensions/xep-0060.html PubSub] node for the application and everyone who's subscribed to it will immediately receive the new book record.  The magic is in who that encompasses:
  * The submitter's own web browser
  * The web agent which generates a new snapshot of the page(s) which include this content
  * Any other web user currently on a page which includes this content
  * Any external agents (other websites, direct XMPP clients, etc) subscribed to the content

So once they submit the data, it appears instantly with no custom javascript or ajax/comet debugging on the application writer's part.

Templates are also managed by [http://xmpp.org/extensions/xep-0060.html PubSub] in [http://en.wikipedia.org/wiki/XSLT XSLT] form so, as in the above example, an updated template can be seen in every browser viewing an affected page immediately.

Virtually any web application can be implemented on this model using the classes and decorators Concordance provides.


== Design ==

As a framework, the most important aspect of Concordance is the API.  It must be generic, reusable, extendable, clean, and Pythonic.  This is especially important for a framework which will usually run the same codebase in separate distinct processes launched by separate daemons.

Generally Concordance runs in at least two processes; the XMPP service (run by Concordance on a dedicated S2S port) and the WSGI interface to that service run inside the web server.  These are part of the same app and often the same class which create a socket to communicate with each other.

Apps are the base unit which can be loaded to provide a service.  An example of an app is a wiki which is stored in XMPP PubSub.  Apps may depend on other apps and may be packaged in suites such as the Freeform CMS.  Concordance should come with the basic, generic services which many apps will use and which most users will need, such as a common XMPP+HTTP authentication app and an admin panel to enable, manage, and configure other apps.  These are all intended to be extended by other apps.

Concordance does not provide persistent data storage nor depends on any database package, but the API is designed to work with most ORMs such as that provided by SQLAlchemy seamlessly.  It is up to the user (or app author) to determine how to store data; whether it be by SQL database, XML database, JSON, dumping Python pickles of the objects to disk, or some even more obscure method.


== Status ==

Concordance sits at the top of a large stack of packages which are in active development, notably;
 * [http://www.nodetree.org/ NodeTree] Pythonic XML Data Binding Package
 * [http://www.wsgi.org/ WSGI] Web Service Gateway Interface for Python 3
 * [http://hg.concordance-xmpp.org/mod_xmpp mod_xmpp] Apache module for [http://tools.ietf.org/html/draft-moffitt-xmpp-over-websocket XMPP over WebSockets] (Download [http://download.concordance-xmpp.org/mod_xmpp-0.1.tbz2 version 0.1])
 
Development on Concordance is tightly linked with a [http://www.pysoy.org/ Python 3D game engine], one of the major use-cases in design being able to host XMPP-based cloud gaming services. PySoy uses the [http://www.lightmelody.org/ LightMelody XMPP Client Library].