From fc94201b0cf6f17e30bd1cf9a7ad0060ad139db5 Mon Sep 17 00:00:00 2001 From: Christophe de Vienne 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 | -| | | -| | a string | -+---------------+------------------------------------+ -| ``unicode`` | .. code-block:: xml | -| | | -| | a string | -+---------------+------------------------------------+ -| ``int`` | .. code-block:: xml | -| | | -| | 5 | -+---------------+------------------------------------+ -| ``float`` | 3.14 | -+---------------+------------------------------------+ -| ``bool`` | true | -+---------------+------------------------------------+ -| ``Decimal`` | 5.46 | -+---------------+------------------------------------+ -| ``date`` | 2010-04-27 | -+---------------+------------------------------------+ -| ``time`` | 12:54:18 | -+---------------+------------------------------------+ -| ``datetime`` | 2010-04-27T12:54:18 | -+---------------+------------------------------------+ -| Arrays | .. code-block:: xml | -| | | -| | | -| | Dinausaurs | -| | Rachel | -| | | -+---------------+------------------------------------+ -| None | .. code-block:: xml | -| | | -| | | -+---------------+------------------------------------+ -| Complex types | .. code-block:: xml | -| | | -| | | -| | 1 | -| | 1 | -| | | -+---------------+------------------------------------+ ++---------------+----------------------------------------+ +| Type | XML example | ++===============+========================================+ +| ``str`` | .. code-block:: xml | +| | | +| | a string | ++---------------+----------------------------------------+ +| ``unicode`` | .. code-block:: xml | +| | | +| | a string | ++---------------+----------------------------------------+ +| ``int`` | .. code-block:: xml | +| | | +| | 5 | ++---------------+----------------------------------------+ +| ``float`` | .. code-block:: xml | +| | | +| | 3.14 | ++---------------+----------------------------------------+ +| ``bool`` | .. code-block:: xml | +| | | +| | true | ++---------------+----------------------------------------+ +| ``Decimal`` | .. code-block:: xml | +| | | +| | 5.46 | ++---------------+----------------------------------------+ +| ``date`` | .. code-block:: xml | +| | | +| | 2010-04-27 | ++---------------+----------------------------------------+ +| ``time`` | .. code-block:: xml | +| | | +| | 12:54:18 | ++---------------+----------------------------------------+ +| ``datetime`` | .. code-block:: xml | +| | | +| | 2010-04-27T12:54:18 | ++---------------+----------------------------------------+ +| Arrays | .. code-block:: xml | +| | | +| | | +| | Dinausaurs | +| | Rachel | +| | | ++---------------+----------------------------------------+ +| None | .. code-block:: xml | +| | | +| | | ++---------------+----------------------------------------+ +| Complex types | .. code-block:: xml | +| | | +| | | +| | 1 | +| | Ross | +| | | ++---------------+----------------------------------------+ 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 `. + - The default value of instances attributes is + :data:`Unset `. ::