PYSON doc

doc/ref/pyson.rst

 .. _ref-pyson:
 .. module:: trytond.pyson
 
 =====
 PYSON
 =====
 
-PYSON is the Python statement and object notation.·
+
+PYSON is the PYthon Statement and Object Notation.
+
+There is also a more :ref:`practical introduction into
+PYSON statements <topics-pyson>`.
 
 .. class:: PYSON
 
-    Base class of any PYSON statement. It is never used directly.
+Base class of any PYSON statement. It is never used directly.
 
 Instance methods:
 
 .. method:: PYSON.pyson()
-    
-    Method that returns the dictionary representation of the statement. 
+
+Method that returns the internal dictionary representation of the
+statement.
 
 .. method:: PYSON.types()
 
-    Method that returns all possible types which the statement can become
-    when evaluated.
+Method that returns a set of all possible types which the statement
+can become when evaluated.
 
 .. classmethod:: PYSON.eval(dct, context)
 
-    Method which returns the evaluation of the statement given in·
-    :attr:`eval.dct`  within the :attr:`eval.context`.·
-
-Attributes:
-
-.. attribute:: eval.dct
-
-    Contains a dictionary with statements to evaluate.
-
-.. attribute:: eval.context
-
-    Contains a dictionary with the evaluation context.
-
-
-============
-PYSONEncoder
-============
-
-.. class:: pyson.PYSONEncoder
-
-    Encoder for PYSON statements into string representations.
+Method which returns the evaluation of the statement given in
+``dct`` within the ``context``. ``dct`` contains a
+dictionary which is the internal representation of a PYSON
+statement. ``context`` contains a dictionary with contextual
+values.
+
+
+Encoder and Decoder
+===================
+
+.. class:: PYSONEncoder()
+
+Encoder for PYSON statements into string representations.
 
 Instance method:
 
-.. method:: pyson.PYSONEncoder.encode(object)
+    .. method:: PYSONEncoder.encode(object)
 
     Returns a string representation of a given PYSON statement.
-
-Attribute:
-
-.. attribute:: encode.object
-
-    Contains a PYSON statement.
-
-
-==========
+    ``object`` contains a PYSON statement.
+
+.. class:: PYSONDecoder()
+
+Decoder for string into PYSON statement representation.
+
+Instance method:
+
+    .. method:: PYSONDecoder.decode(object)
+
+    Returns a PYSON statement representation of a given string.
+    ``object`` contains a string.
+
 Statements
 ==========
 
-The following statements are implemented in :class:`PYSON`.
-There is also an overview introduction into·
-:ref:`PYSON statements <topics-pyson>`.
-
-
-Eval
-====
-
-An :class:`Eval()` object represents the PYSON ``Eval()``·
-statement for evaluation.
+The following statements can be used in :class:`PYSON`.
 
 .. class:: Eval(value[, default])
 
-    Returns :attr:`Eval.value` if defined in the evaluation context,·
-    or the optional :attr:`Eval.default`.
-
-Class attributes:
-
-.. attribute:: Eval.value
-
-    It contains a PYSON statement.
-
-.. attribute:: Eval.default
-
-    It contains a default value or ``''``.
-
-
-Not
-===
-
-A :class:`Not` object represents the PYSON ``Not()``·
-operator for boolean operation.
+An :class:`Eval()` object represents the PYSON ``Eval()``
+statement for evaluations. When evaluated, it returns the
+value of the statement named by ``value``, if defined in the
+evaluation context, otherwise the ``default`` value (empty
+string by default). ``value`` can use the dot notation to
+access objects values in the context. Returns an instance of
+itself.
 
 .. class:: Not(value)
 
-    Returns the logical negation of :attr:`Not.value`.
-
-Class attribute:
-
-.. attribute:: Not.value
-
-    Contains a PYSON statement of type boolean.
-
-
-Bool
-====
-
-A :class:`Bool` object represents the PYSON ``Bool()``·
-statement for boolean evaluation.
+A :class:`Not` object represents the PYSON ``Not()``
+statement for logical negations. When evaluated, returns
+the boolean negation of the value of the statement named by
+``value``, if defined in the evaluation context. Returns an
+instance of itself.
 
 .. class:: Bool(value)
 
-    Returns the boolean representation of :attr:`Bool.value`
-
-Class attribute:
-
-.. attribute:: Bool.value
-
-    Contains a PYSON statement which can be evaluated to boolean.
-
-
-And
-===
-
-An :class:`And` object represents the PYSON ``And()``·
-operator for boolean operation.
+A :class:`Bool` object represents the PYSON ``Bool()``
+statement for boolean evaluations. Returns the boolean
+representation of the value of the statement named by
+``value``.
 
 .. class:: And(\*statements)
 
-    Returns the result of the logical conjuction of two or more·
-    :attr:`And.statements` .
-
-Class attribute:
-
-.. attribute:: And.statements
-
-    Contains a tuple with two or more PYSON statements of type boolean.
-
-
-Or
-==
-
-An :class:`Or` object represents the PYSON ``Or()``·
-operator for boolean operation.
+An :class:`And` object represents the PYSON ``And()``
+statement for logical *and* operations. Returns the result of
+the logical conjunction of two or more values named by the
+statements in the ``statements`` tuple.
 
 .. class:: Or(\*statements)
 
-    Returns the result of the logical disjunction of two or more·
-    PYSON :attr:`Or.statements`.
-
-
-Class attribute:
-
-.. attribute:: Or.statements
-
-    Contains a tuple with two or more PYSON statements of type boolean.
-
-
-Equal
-=====
-
-An :class:`Equal` object represents the PYSON ``Equal()``·
-operator for comparison.
-
-.. class:: Equal(statemant1, statement2)
-
-    Returns true when :attr:`statement1` and :attr:`statement2` are·
-    equal, otherwise returns false.
-
-Class attribute:
-
-.. attribute:: Equal.statement1
-
-    Contains a PYSON statement of the same type as :attr:`statement2`.
-
-.. attribute:: Equal.statement2
-
-    Contains a PYSON statement of the same type as :attr:`statement1`.
-
-
-Greater
-=======
-
-A :class:`Greater` object represents the PYSON ``Greater()``·
-operator for comparison.
+An :class:`Or` object represents the PYSON ``Or()``
+statement for logical *or* operations. Returns the result of
+the logical disjunction of two or more values named by the
+statements in the ``statements`` tuple.
+
+.. class:: Equal(statement1, statement2)
+
+An :class:`Equal` object represents the PYSON ``Equal()``
+statement for equation comparisons. Returns true when a value of
+a statement named by ``statement1`` and the value of a statement
+named by ``statement2`` are equal, otherwise returns false.
 
 .. class:: Greater(statement1, statement2[, equal])
 
-    Returns true when :attr:`Greater.statement1` is strictly greater than·
-    :attr:`Greater.statement2`,  otherwise returns false.·
-···
-    When :attr:`Greater.equal` is true:·
-        Returns true when :attr:`Greater.statement1`is greater than·
-        or equal :attr:`Greater.statement2`, otherwise returns false.·
-
-Class attribute:
-
-.. attribute:: Greater.statement1
-
-    The left hand side statement of type long, integer or float.
-
-.. attribute:: Greater.statement2
-
-    The right hand side statement of type long, integer or float.
-
-.. attribute:: Greater.equal
-
-    Contains a boolean. When set true *greater than or equal* operation
-    is used for comparison, otherwise *strictly greater than* (default).
-
-
-Less
-====
-
-A :class:`Less` object represents the PYSON ``Less()``·
-operator for comparison.
+A :class:`Greater` object represents the PYSON ``Greater()``
+statement for *greater-than* comparisons. Returns true when the value
+of the statement named by ``statement1`` is strictly greater than the
+value of the statement named by ``statement2``,  otherwise
+returns false. Is the value of the variable named by ``equal`` is·
+true, then returns also true when both values of statements named by
+``statement1`` and ``statement2`` are equal. In this case
+:class:`Greater` works as a *greater-than or equal* operator.
 
 .. class:: Less(statement1, statement2[, equal])
 
-    Returns true when :attr:`Less.statement1` is strictly less than·
-    :attr:`Less.statement2`,  otherwise returns false.·
-···
-    When :attr:`Less.equal` is true:
-        Returns true when :attr:`Less.statement1`is less than or equal·
-        :attr:`Less.statement2`, otherwise returns false.·
-
-.. attribute:: Less.statement1
-
-    Contains a PYSON statement of type long, integer or float.
-
-.. attribute:: Less.statement2
-
-    Contains a PYSON statement of type long, integer or float.
-
-.. attribute:: Less.equal
-
-    Contains a PYSON statement of type boolean. When set true,·
-    *less than or equal* operation is used for comparison,·
-    otherwise *strictly less than* (default).
-
-
-If
-==
-
-An :class:`If` object represents the PYSON ``If()`` statement for·
-conditional flow control.
+A :class:`Less` object represents the PYSON ``Less()``
+statement for *less-than* comparisons. Returns true when the value
+of the statement named by ``statement1`` is strictly less than the
+value of the statement named by ``statement2``,  otherwise
+returns false. Is the value of the variable named ``equal`` is true,
+then returns also true when both values of the statements named by
+``statement1`` and ``statement2`` are equal. In this case
+:class:`Less`  works as a *less-than or equal* operator.
 
 .. class:: If(condition, then_statement, else_statement)
 
-    Returns :attr:`If.then_statement` when :attr:`If.condition` is
-    true, otherwise returns :attr:`If.else_statement`.
-
-Class attribute:
-
-.. attribute:: If.condition
-
-    Contains a PYSON statement of type boolean.
-
-.. attribute:: If.then_statement
-
-    Contains a PYSON statement with the same type as·
-    :attr:`If.else_statement` .
-
-
-.. attribute:: If.else_statement
-
-    Contains a PYSON statement with the same type as·
-    :attr:`If.then_statement` .
-
-
-Get
-===
-
-A :class:`Get` object represents the PYSON ``Get()`` statement for·
-dictionary look-ups.
+An :class:`If` object represents the PYSON ``If()``
+statement for conditional flow control operations. Returns the
+value of the statement named by ``then_statement`` when the value
+of the statement named by ``condition`` evaluates true.
+Otherwise returns the value of the statement named by
+``else_statement``.
 
 .. class:: Get(obj, key[, default])
 
-    Look up :attr:`Get.obj` for :attr:`Get.key` and returns·
-    the value if defined, otherwise returns :attr:`Get.default`.
-
-Class attribute:
-
-.. attribute:: Get.obj
-
-    Contains a PYSON statement of type dictionary.
-
-.. attribute:: Get.key
-
-    Contains a PYSON statement of type string.
-
-.. attribute:: Get.default
-
-    Contains PYSON statement.
-
-
-In
-==
-
-An :class:`In` object represents the PYSON ``In()``·
-operator for comparison.
+A :class:`Get` object represents the PYSON ``Get()``
+statement for dictionary look-up operations and evaluation.
+Look up and returns the value of a key named by ``key`` in an
+object named by ``obj`` if defined.
+Otherwise returns the value of the variable named by ``default``.
 
 .. class:: In(key, obj)
 
-    Returns true when :attr:`In.obj` contains :attr:`In.key`,·
-    otherwise returns false.
-
-Class attributes:
-
-.. attribute:: In.key
-
-    Contains a PYSON statement of type string when :attr:`In.obj`·
-    is of type dict. Otherwise contains a PYSON statement of type
-    integer or long.
-
-.. attribute:: In.obj
-
-    Contains a PYSON statement of type dict or list.
-
-
-Date
-====
-
-A :class:`Date` object represents the PYSON ``Date()`` statement for
-date related calculations.
+An :class:`In` object represents the PYSON ``In()``
+statement for look-up dictionary or integer objects. Returns true when
+a list (or dictionary) object named by ``obj`` contains the value of
+the variable (or key) named by ``key``. Otherwise returns false.
 
 .. class:: Date([year[, month[, day[, delta_years[, delta_month[, delta_days]]]]]])
 
-    Returns a datetime.date object which represents the given attributes.
-    Missing attributes of :attr:`Date.year` or :attr:`Date.month` or·
-    :attr:`day` are defaulted from datetime.date.today().
-
-    When delta_* attributes are given, they are added to the·
-    appropriate attributes.
-···
-Class attributes:
-
-.. attribute:: Date.year
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: Date.month
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: Date.day
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: Date.delta_years
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: Date.delta_month
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: Date.delta_days
-
-    Contains a PYSON statement of type int or long.
-
-
-DateTime
-========
-
-A :class:`Date` object represents the PYSON ``Date()`` statement for
-date and time related calculations.
+A :class:`Date` object represents the PYSON ``Date()``
+statement for date related conversions and basic calculations.
+Returns a date object which represents
+the values of arguments named by the *variables* explained below.
+Missing values of arguments named by ``year`` or ``month`` or
+``day`` take their defaults from the actual date. When values of
+arguments named by ``delta_*`` are given, they are added to the
+values of the appropriate arguments in a date and time preserving
+manner.
+
+Arguments:
+
+``year``
+    Contains a PYSON statement of type int or long.
+
+``month``
+    Contains a PYSON statement of type int or long.
+
+``day``
+    Contains a PYSON statement of type int or long.
+
+``delta_years``
+    Contains a PYSON statement of type int or long.
+
+``delta_month``
+    Contains a PYSON statement of type int or long.
+
+``delta_days``
+    Contains a PYSON statement of type int or long.
 
 .. class:: DateTime([year[, month[, day[, hour[, minute[, second[, microsecond[, delta_years[, delta_months[, delta_days[, delta_hours[, delta_minutes[, delta_seconds[, delta_microseconds]]]]]]]]]]]]]])
 
-    Returns a datetime.datetime object which represents the given·
-    attributes. Missing attributes of :attr:`DateTime.year`,
-    :attr:`DateTime.month`, :attr:`DateTime.day`,·
-    :attr:`DateTime.hour`, :attr:`Date.minute`, :attr:`Date.second`,
-    :attr:`DateTime.microseconds` are defaulted to·
-    datetime.date.today() and datetime.datetime.now().time().
-
-    When delta_* attributes are given, they are added to the·
-    appropriate attributes.
-
-Class attributes:
-
-.. attribute:: DateTime.year
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: DateTime.month
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: DateTime.day
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: DateTime.hour
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: DateTime.minute
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: DateTime.second
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: DateTime.microsecond
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: DateTime.delta_years
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: DateTime.delta_month
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: DateTime.delta_days
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: DateTime.delta_hours
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: DateTime.delta_minutes
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: DateTime.delta_seconds
-
-    Contains a PYSON statement of type int or long.
-
-.. attribute:: DateTime.delta_microseconds
-
-    Contains a PYSON statement of type int or long.
-
-
+A :class:`DateTime` object represents the PYSON ``Date()``
+statement for date and time related conversions and calculations.
+Returns a date time object which represents the values of
+variables named by the *arguments* explained below.
+Missing values of arguments named by  ``year``, ``month``, ``day``,
+``hour``, ``minute``, ``second``, ``microseconds`` take their
+defaults from the actual date and time.
+When values of arguments named by ``delta_*`` are given, these are
+added  to the appropriate attributes in a date and time preserving
+manner.
+
+Arguments:
+
+``year``
+    Contains a PYSON statement of type int or long.
+
+``month``
+    Contains a PYSON statement of type int or long.
+
+``day``
+    Contains a PYSON statement of type int or long.
+
+``hour``
+    Contains a PYSON statement of type int or long.
+
+``minute``
+    Contains a PYSON statement of type int or long.
+
+``second``
+    Contains a PYSON statement of type int or long.
+
+``microsecond``
+    Contains a PYSON statement of type int or long.
+
+``delta_years``
+    Contains a PYSON statement of type int or long.
+
+``delta_month``
+    Contains a PYSON statement of type int or long.
+
+``delta_days``
+    Contains a PYSON statement of type int or long.
+
+``delta_hours``
+    Contains a PYSON statement of type int or long.
+
+``delta_minutes``
+    Contains a PYSON statement of type int or long.
+
+``delta_seconds``
+    Contains a PYSON statement of type int or long.
+
+``delta_microseconds``
+    Contains a PYSON statement of type int or long.
+
+