From fc94201b0cf6f17e30bd1cf9a7ad0060ad139db5 Mon Sep 17 00:00:00 2001
From: Christophe de Vienne <cdevienne@gmail.com>
Date: Mon, 28 Nov 2011 23:21:52 +0100
Subject: [PATCH] Document a bit
---
doc/_static/wsme.css | 27 +++++
doc/api.rst | 3 +
doc/changes.rst | 14 +--
doc/conf.py | 2 +
doc/protocols.rst | 279 +++++++++++++++++++++++--------------------
doc/types.rst | 3 +-
6 files changed, 191 insertions(+), 137 deletions(-)
create mode 100644 doc/_static/wsme.css
diff --git a/doc/_static/wsme.css b/doc/_static/wsme.css
new file mode 100644
index 0000000..09675f6
--- /dev/null
+++ b/doc/_static/wsme.css
@@ -0,0 +1,27 @@
+@import "agogo.css";
+
+table.docutils {
+ margin: 0;
+ padding: 0;
+ border: 1;
+}
+
+table.docutils th {
+ margin: 0;
+ padding: 0;
+ border: 0;
+}
+
+table.docutils thead tr {
+}
+
+table.docutils td {
+ margin: 0;
+ padding: 0;
+ border: 0;
+}
+
+table.docutils tr.row-odd {
+ background: #EEEEEC;
+}
+
diff --git a/doc/api.rst b/doc/api.rst
index ac3e496..7559fa7 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -18,6 +18,9 @@ Public API
.. autoclass:: wsproperty
.. autoclass:: wsattr
+.. data:: Unset
+
+ Default value of the complex type attributes.
Internals
---------
diff --git a/doc/changes.rst b/doc/changes.rst
index 7e76a3c..583f1cd 100644
--- a/doc/changes.rst
+++ b/doc/changes.rst
@@ -14,18 +14,16 @@ next
* The restjson protocol do not nest the results in an object anymore.
-* Fixes
+* Fix array attributes validation.
- * Fix array attributes validation.
+* Fix date|time parsing errors.
- * Fix date|time parsing errors.
+* Fix Unset values validation.
- * Fix Unset values validation.
+* Fix registering of complex types inheriting form already
+ registered complex types.
- * Fix registering of complex types inheriting form already
- registered complex types.
-
- * Fix user types, str and None values encoding/decoding.
+* Fix user types, str and None values encoding/decoding.
0.2.0 (2011-10-29)
------------------
diff --git a/doc/conf.py b/doc/conf.py
index dff2348..be53305 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -94,6 +94,8 @@ pygments_style = 'sphinx'
# a list of builtin themes.
html_theme = 'agogo'
+html_style = 'wsme.css'
+
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
diff --git a/doc/protocols.rst b/doc/protocols.rst
index ac7ffab..809a18b 100644
--- a/doc/protocols.rst
+++ b/doc/protocols.rst
@@ -1,78 +1,9 @@
Protocols
=========
-The example
------------
-
In this document the same webservice example will be used to
-illustrate the different protocols:
-
-.. code-block:: python
-
- class Person(object):
- id = int
- lastname = unicode
- firstname = unicode
- age = int
-
- hobbies = [unicode]
-
- def __init__(self, id=None, lastname=None, firstname=None, age=None,
- hobbies=None):
- if id:
- self.id = id
- if lastname:
- self.lastname = lastname
- if firstname:
- self.firstname = firstname
- if age:
- self.age = age
- if hobbies:
- self.hobbies = hobbies
-
- persons = {
- 1: Person(1, "Geller", "Ross", 30, ["Dinosaurs", "Rachel"]),
- 2: Person(2, "Geller", "Monica", 28, ["Food", "Cleaning"])
- }
-
- class PersonController(object):
- @expose(Person)
- @validate(int)
- def get(self, id):
- return persons[id]
-
- @expose([Person])
- def list(self):
- return persons.values()
-
- @expose(Person)
- @validate(Person)
- def update(self, p):
- if p.id is Unset:
- raise ClientSideError("id is missing")
- persons[p.id] = p
- return p
-
- @expose(Person)
- @validate(Person)
- def create(self, p):
- if p.id is not Unset:
- raise ClientSideError("I don't want an id")
- p.id = max(persons.keys()) + 1
- persons[p.id] = p
- return p
-
- @expose()
- @validate(int)
- def destroy(self, id):
- if id not in persons:
- raise ClientSideError("Unknown ID")
-
-
- class WS(WSRoot):
- person = PersonController()
-
- root = WS(webpath='ws')
+illustrate the different protocols. Its source code is in the
+last chapter (:ref:`protocols-the-example`).
REST
----
@@ -104,7 +35,7 @@ The function parameters can be transmitted in two ways :
``/ws/person/get?id=5``
- Complex types, although not yet implemented, should work this way:
+ Complex types can be transmitted this way:
``/ws/person/update?p.id=1&p.name=Ross&p.hobbies[0]=Dinausaurs&p.hobbies[1]=Rachel``
@@ -129,6 +60,12 @@ This protocol is selected if:
- A trailing '.json' is added to the path
- A 'wsmeproto=restjson' is added in the query string
+Options
+~~~~~~~
+
+:nest_result: Nest the encoded result in a result param of an object.
+ For example, a result of ``2`` would be ``{'result': 2}``
+
Types
~~~~~
@@ -163,7 +100,7 @@ Types
Return
~~~~~~
-A json object with a single 'result' property, OR a json object
+The json encoded result when the response code is 200, OR a json object
with error properties ('faulcode', 'faultstring' and 'debuginfo' if
available).
@@ -172,16 +109,14 @@ For example, the /ws/person/get result looks like:
.. code-block:: javascript
{
- 'result': {
- 'id': 2
- 'fistname': 'Monica',
- 'lastname': 'Geller',
- 'age': 28,
- 'hobbies': [
- 'Food',
- 'Cleaning'
- ]
- }
+ 'id': 2
+ 'fistname': 'Monica',
+ 'lastname': 'Geller',
+ 'age': 28,
+ 'hobbies': [
+ 'Food',
+ 'Cleaning'
+ ]
}
And in case of error:
@@ -208,51 +143,63 @@ This protocol is selected if
Types
~~~~~
-+---------------+------------------------------------+
-| Type | XML example |
-+===============+====================================+
-| ``str`` | .. code-block:: xml |
-| | |
-| | <value>a string</value> |
-+---------------+------------------------------------+
-| ``unicode`` | .. code-block:: xml |
-| | |
-| | <value>a string</value> |
-+---------------+------------------------------------+
-| ``int`` | .. code-block:: xml |
-| | |
-| | <value>5</value> |
-+---------------+------------------------------------+
-| ``float`` | <value>3.14</value> |
-+---------------+------------------------------------+
-| ``bool`` | <value>true</value> |
-+---------------+------------------------------------+
-| ``Decimal`` | <value>5.46</value> |
-+---------------+------------------------------------+
-| ``date`` | <value>2010-04-27</value> |
-+---------------+------------------------------------+
-| ``time`` | <value>12:54:18</value> |
-+---------------+------------------------------------+
-| ``datetime`` | <value>2010-04-27T12:54:18</value> |
-+---------------+------------------------------------+
-| Arrays | .. code-block:: xml |
-| | |
-| | <value> |
-| | <item>Dinausaurs<item> |
-| | <item>Rachel<item> |
-| | </value> |
-+---------------+------------------------------------+
-| None | .. code-block:: xml |
-| | |
-| | <value nil="true"/> |
-+---------------+------------------------------------+
-| Complex types | .. code-block:: xml |
-| | |
-| | <value> |
-| | <id>1</id> |
-| | <fistname>1</fistname> |
-| | </value> |
-+---------------+------------------------------------+
++---------------+----------------------------------------+
+| Type | XML example |
++===============+========================================+
+| ``str`` | .. code-block:: xml |
+| | |
+| | <value>a string</value> |
++---------------+----------------------------------------+
+| ``unicode`` | .. code-block:: xml |
+| | |
+| | <value>a string</value> |
++---------------+----------------------------------------+
+| ``int`` | .. code-block:: xml |
+| | |
+| | <value>5</value> |
++---------------+----------------------------------------+
+| ``float`` | .. code-block:: xml |
+| | |
+| | <value>3.14</value> |
++---------------+----------------------------------------+
+| ``bool`` | .. code-block:: xml |
+| | |
+| | <value>true</value> |
++---------------+----------------------------------------+
+| ``Decimal`` | .. code-block:: xml |
+| | |
+| | <value>5.46</value> |
++---------------+----------------------------------------+
+| ``date`` | .. code-block:: xml |
+| | |
+| | <value>2010-04-27</value> |
++---------------+----------------------------------------+
+| ``time`` | .. code-block:: xml |
+| | |
+| | <value>12:54:18</value> |
++---------------+----------------------------------------+
+| ``datetime`` | .. code-block:: xml |
+| | |
+| | <value>2010-04-27T12:54:18</value> |
++---------------+----------------------------------------+
+| Arrays | .. code-block:: xml |
+| | |
+| | <value> |
+| | <item>Dinausaurs<item> |
+| | <item>Rachel<item> |
+| | </value> |
++---------------+----------------------------------------+
+| None | .. code-block:: xml |
+| | |
+| | <value nil="true"/> |
++---------------+----------------------------------------+
+| Complex types | .. code-block:: xml |
+| | |
+| | <value> |
+| | <id>1</id> |
+| | <fistname>Ross</fistname> |
+| | </value> |
++---------------+----------------------------------------+
Return
~~~~~~
@@ -336,3 +283,79 @@ expose extra options
function.
.. _Ext Direct: http://www.sencha.com/products/extjs/extdirect
+
+.. _protocols-the-example:
+
+The example
+-----------
+
+In this document the same webservice example will be used to
+illustrate the different protocols:
+
+.. code-block:: python
+
+ class Person(object):
+ id = int
+ lastname = unicode
+ firstname = unicode
+ age = int
+
+ hobbies = [unicode]
+
+ def __init__(self, id=None, lastname=None, firstname=None, age=None,
+ hobbies=None):
+ if id:
+ self.id = id
+ if lastname:
+ self.lastname = lastname
+ if firstname:
+ self.firstname = firstname
+ if age:
+ self.age = age
+ if hobbies:
+ self.hobbies = hobbies
+
+ persons = {
+ 1: Person(1, "Geller", "Ross", 30, ["Dinosaurs", "Rachel"]),
+ 2: Person(2, "Geller", "Monica", 28, ["Food", "Cleaning"])
+ }
+
+ class PersonController(object):
+ @expose(Person)
+ @validate(int)
+ def get(self, id):
+ return persons[id]
+
+ @expose([Person])
+ def list(self):
+ return persons.values()
+
+ @expose(Person)
+ @validate(Person)
+ def update(self, p):
+ if p.id is Unset:
+ raise ClientSideError("id is missing")
+ persons[p.id] = p
+ return p
+
+ @expose(Person)
+ @validate(Person)
+ def create(self, p):
+ if p.id is not Unset:
+ raise ClientSideError("I don't want an id")
+ p.id = max(persons.keys()) + 1
+ persons[p.id] = p
+ return p
+
+ @expose()
+ @validate(int)
+ def destroy(self, id):
+ if id not in persons:
+ raise ClientSideError("Unknown ID")
+
+
+ class WS(WSRoot):
+ person = PersonController()
+
+ root = WS(webpath='ws')
+
diff --git a/doc/types.rst b/doc/types.rst
index 343a012..099b811 100644
--- a/doc/types.rst
+++ b/doc/types.rst
@@ -167,7 +167,8 @@ A few things you should know about complex types:
assert Person.name.key == "name"
assert Person.name.mandatory is False
- - The default value of instances attributes is :data:`Unset <wsme.types.Unset>`.
+ - The default value of instances attributes is
+ :data:`Unset <wsme.Unset>`.
::