From d176faae757bf0dd48f9e2429c92b3380edffdfd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?C=C3=A9dric=20Krier?= <ced@b2ck.com>
Date: Thu, 11 Nov 2010 17:57:54 +0100
Subject: [PATCH] Add example in README

---
 README   | 91 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 setup.py |  5 ++++
 2 files changed, 96 insertions(+)

diff --git a/README b/README
index c337a861ce..b4a4955407 100644
--- a/README
+++ b/README
@@ -8,6 +8,97 @@ Installing
 
 See INSTALL
 
+Example of usage
+----------------
+
+    >>> from proteus import config, Model, Wizard
+
+Creating a database
+~~~~~~~~~~~~~~~~~~~
+
+Configuration to connect to a sqlite memory database using trytond as module.
+
+    >>> config = config.set_trytond(':memory:', database_type='sqlite')
+
+When connecting to a database that doesn't exist, Proteus will create it.
+
+Installing a module
+~~~~~~~~~~~~~~~~~~~
+
+Find the module, call the install button and run the install wizard.
+
+    >>> Module = Model.get('ir.module.module')
+    >>> (party,) = Module.find([('name', '=', 'party')])
+    >>> Module.button_install([party.id], config.context)
+    >>> Wizard('ir.module.module.install_upgrade').execute('start')
+
+Creating a party
+~~~~~~~~~~~~~~~~
+
+First instanciate a new Party:
+
+    >>> Party = Model.get('party.party')
+    >>> party = Party()
+    >>> party.id < 0
+    True
+
+Fill the fields:
+
+    >>> party.name = 'ham'
+
+Save the instance into the server:
+
+    >>> party.save()
+    >>> party.name
+    u'ham'
+    >>> party.id > 0
+    True
+
+Setting the language of the party
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The language on party is a `Many2One` relation field. So it requires to get a
+`Model` instance as value.
+
+    >>> Lang = Model.get('ir.lang')
+    >>> (en,) = Lang.find([('code', '=', 'en_US')])
+    >>> party.lang = en
+    >>> party.save()
+    >>> party.lang.code
+    u'en_US'
+
+Creating an address for the party
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Addresses are store on party with a `One2Many` field. So the new address just
+needs to be appended to the list `addresses`.
+
+    >>> Address = Model.get('party.address')
+    >>> address = Address()
+    >>> party.addresses.append(address)
+    >>> party.save()
+    >>> party.addresses #doctest: +ELLIPSIS
+    [proteus.Model.get('party.address')(...)]
+
+Adding category to the party
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Categories are linked to party with a `Many2Many` field.
+
+So first create a category
+
+    >>> Category = Model.get('party.category')
+    >>> category = Category()
+    >>> category.name = 'spam'
+    >>> category.save()
+
+Append it to categories of the party
+
+    >>> party.categories.append(category)
+    >>> party.save()
+    >>> party.categories #doctest: +ELLIPSIS
+    [proteus.Model.get('party.category')(...)]
+
 Support
 -------
 
diff --git a/setup.py b/setup.py
index 6392718407..2d9c8debc6 100644
--- a/setup.py
+++ b/setup.py
@@ -3,6 +3,7 @@
 #this repository contains the full copyright notices and license terms.
 from setuptools import setup, find_packages
 import sys
+import os
 import proteus
 
 major_version, minor_version, _ = proteus.__version__.split('.', 2)
@@ -13,9 +14,13 @@ SIMPLEJSON = []
 if sys.version_info < (2, 6):
     SIMPLEJSON = ['simplejson']
 
+def read(fname):
+    return open(os.path.join(os.path.dirname(__file__), fname)).read()
+
 setup(name='proteus',
     version=proteus.__version__,
     description='Library to access Tryton server as a client',
+    long_description=read('README'),
     author='B2CK',
     author_email='info@b2ck.com',
     url='http://www.tryton.org/',