From 690c066c350c839cd89e708763989fa91569d0bc Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?C=C3=A9dric=20Krier?= <ced@b2ck.com>
Date: Sat, 23 Feb 2013 18:26:01 +0100
Subject: [PATCH] Add documentation for Dict field and standardize options

review672003
---
 doc/ref/models/fields.rst    | 14 +++++++
 doc/ref/models/models.rst    | 71 ++++++++++++++++++++++++++++++++++++
 trytond/model/fields/dict.py |  8 ++--
 trytond/test/test.py         |  6 +--
 4 files changed, 92 insertions(+), 7 deletions(-)

diff --git a/doc/ref/models/fields.rst b/doc/ref/models/fields.rst
index 680263aa08..e3a4f735bf 100644
--- a/doc/ref/models/fields.rst
+++ b/doc/ref/models/fields.rst
@@ -670,3 +670,17 @@ Instance methods:
 .. method:: Property.search(model, name, clause)
 
     Same as :meth:`Function.search`.
+
+Dict
+----
+
+.. class:: Dict(schema_model[, \**options])
+
+A dictionary field with predefined keys.
+
+:class:`Dict` has one extra required argument:
+
+.. attribute:: Dict.schema_model
+
+    The name of the :class:`DictSchemaMixin` model that stores the definition
+    of keys.
diff --git a/doc/ref/models/models.rst b/doc/ref/models/models.rst
index 34cb6bbac2..9a64c0f15f 100644
--- a/doc/ref/models/models.rst
+++ b/doc/ref/models/models.rst
@@ -456,3 +456,74 @@ Class methods:
 .. classmethod:: ModelSingleton.get_singleton()
 
     Return the instance of the unique record if there is one.
+
+===============
+DictSchemaMixin
+===============
+
+.. class:: DictSchemaMixin
+
+A mixin_ for the schema of :class:`trytond.model.fields.Dict` field.
+
+Class attributes are:
+
+.. attribute:: DictSchemaMixin.name
+
+    The definition of the :class:`trytond.model.fields.Char` field for the name
+    of the key.
+
+.. attribute:: DictSchemaMixin.string
+
+    The definition of the :class:`trytond.model.fields.Char` field for the
+    string of the key.
+
+.. attribute:: DictSchemaMixin.type\_
+
+    The definition of the :class:`trytond.model.fields.Selection` field for the
+    type of the key. The available types are:
+
+    * boolean
+    * integer
+    * char
+    * float
+    * numeric
+    * date
+    * datetime
+    * selection
+
+.. attribute:: DictSchemaMixin.digits
+
+    The definition of the :class:`trytond.model.fields.Integer` field for the
+    digits number when the type is `float` or `numeric`.
+
+.. attribute:: DictSchemaMixin.selection
+
+    The definition of the :class:`trytond.model.fields.Text` field to store the
+    couple of key and label when the type is `selection`.
+    The format is a key/label separated by ":" per line.
+
+.. attribute:: DictSchemaMixin.selection_json
+
+    The definition of the :class:`trytond.model.fields.Function` field to
+    return the JSON_ version of the :attr:`selection`.
+
+Static methods:
+
+.. staticmethod:: DictSchemaMixin.default_digits()
+
+    Return the default value for :attr:`digits`.
+
+Class methods:
+
+.. classmethod:: DictSchemaMixin.get_keys(records)
+
+    Return the definition of the keys for the records.
+
+Instance methods:
+
+.. method:: DictSchemaMixin.get_selection_json(name)
+
+    Getter for the :attr:`selection_json`.
+
+.. _mixin: http://en.wikipedia.org/wiki/Mixin
+.. _JSON: http://en.wikipedia.org/wiki/Json
diff --git a/trytond/model/fields/dict.py b/trytond/model/fields/dict.py
index b573250464..42076d769a 100644
--- a/trytond/model/fields/dict.py
+++ b/trytond/model/fields/dict.py
@@ -13,10 +13,10 @@ class Dict(Field):
     'Define dict field.'
     _type = 'dict'
 
-    def __init__(self, string='', help='', required=False, readonly=False,
-            domain=None, states=None, select=False, on_change=None,
-            on_change_with=None, depends=None, order_field=None, context=None,
-            loading='lazy', schema_model=None):
+    def __init__(self, schema_model, string='', help='', required=False,
+            readonly=False, domain=None, states=None, select=False,
+            on_change=None, on_change_with=None, depends=None,
+            order_field=None, context=None, loading='lazy'):
         super(Dict, self).__init__(string, help, required, readonly, domain,
             states, select, on_change, on_change_with, depends, order_field,
             context, loading)
diff --git a/trytond/test/test.py b/trytond/test/test.py
index 7bba00369a..65a9723e26 100644
--- a/trytond/test/test.py
+++ b/trytond/test/test.py
@@ -623,13 +623,13 @@ class SelectionRequired(ModelSQL):
 class Dict(ModelSQL):
     'Dict'
     __name__ = 'test.dict'
-    dico = fields.Dict('Test Dict')
+    dico = fields.Dict(None, 'Test Dict')
 
 
 class DictDefault(ModelSQL):
     'Dict Default'
     __name__ = 'test.dict_default'
-    dico = fields.Dict('Test Dict')
+    dico = fields.Dict(None, 'Test Dict')
 
     @staticmethod
     def default_dico():
@@ -639,4 +639,4 @@ class DictDefault(ModelSQL):
 class DictRequired(ModelSQL):
     'Dict Required'
     __name__ = 'test.dict_required'
-    dico = fields.Dict('Test Dict', required=True)
+    dico = fields.Dict(None, 'Test Dict', required=True)