x/wsme
Code Issues Proposed changes

Document a bit

Browse Source
This commit is contained in:
Christophe de Vienne 2011-11-28 23:21:52 +01:00
parent 3f6796f3bb
commit fc94201b0c
6 changed files with 191 additions and 137 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
doc/_static/wsme.css vendored Normal file
View File

@ -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;
}

3
doc/api.rst
View File

@ -18,6 +18,9 @@ Public API
.. autoclass:: wsproperty .. autoclass:: wsproperty
.. autoclass:: wsattr .. autoclass:: wsattr
.. data:: Unset
Default value of the complex type attributes.
Internals Internals
--------- ---------

14
doc/changes.rst
View File

@ -14,18 +14,16 @@ next
* The restjson protocol do not nest the results in an object anymore. * 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 * Fix user types, str and None values encoding/decoding.
registered complex types.
* Fix user types, str and None values encoding/decoding.
0.2.0 (2011-10-29) 0.2.0 (2011-10-29)
------------------ ------------------

2
doc/conf.py
View File

@ -94,6 +94,8 @@ pygments_style = 'sphinx'
# a list of builtin themes. # a list of builtin themes.
html_theme = 'agogo' html_theme = 'agogo'
html_style = 'wsme.css'
# Theme options are theme-specific and customize the look and feel of a theme # 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 # further. For a list of options available for each theme, see the
# documentation. # documentation.

279
doc/protocols.rst
View File

@ -1,78 +1,9 @@
Protocols Protocols
========= =========
The example
-----------
In this document the same webservice example will be used to In this document the same webservice example will be used to
illustrate the different protocols: illustrate the different protocols. Its source code is in the
last chapter (:ref:`protocols-the-example`).
.. 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')
REST REST
---- ----
@ -104,7 +35,7 @@ The function parameters can be transmitted in two ways :
``/ws/person/get?id=5`` ``/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`` ``/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 trailing '.json' is added to the path
- A 'wsmeproto=restjson' is added in the query string - 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 Types
~~~~~ ~~~~~
@ -163,7 +100,7 @@ Types
Return 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 with error properties ('faulcode', 'faultstring' and 'debuginfo' if
available). available).
@ -172,16 +109,14 @@ For example, the /ws/person/get result looks like:
.. code-block:: javascript .. code-block:: javascript
{ {
'result': { 'id': 2
'id': 2 'fistname': 'Monica',
'fistname': 'Monica', 'lastname': 'Geller',
'lastname': 'Geller', 'age': 28,
'age': 28, 'hobbies': [
'hobbies': [ 'Food',
'Food', 'Cleaning'
'Cleaning' ]
]
}
} }
And in case of error: And in case of error:
@ -208,51 +143,63 @@ This protocol is selected if
Types Types
~~~~~ ~~~~~
+---------------+------------------------------------+ +---------------+----------------------------------------+
| Type | XML example | | Type | XML example |
+===============+====================================+ +===============+========================================+
| ``str`` | .. code-block:: xml | | ``str`` | .. code-block:: xml |
| | | | | |
| | <value>a string</value> | | | <value>a string</value> |
+---------------+------------------------------------+ +---------------+----------------------------------------+
| ``unicode`` | .. code-block:: xml | | ``unicode`` | .. code-block:: xml |
| | | | | |
| | <value>a string</value> | | | <value>a string</value> |
+---------------+------------------------------------+ +---------------+----------------------------------------+
| ``int`` | .. code-block:: xml | | ``int`` | .. code-block:: xml |
| | | | | |
| | <value>5</value> | | | <value>5</value> |
+---------------+------------------------------------+ +---------------+----------------------------------------+
| ``float`` | <value>3.14</value> | | ``float`` | .. code-block:: xml |
+---------------+------------------------------------+ | | |
| ``bool`` | <value>true</value> | | | <value>3.14</value> |
+---------------+------------------------------------+ +---------------+----------------------------------------+
| ``Decimal`` | <value>5.46</value> | | ``bool`` | .. code-block:: xml |
+---------------+------------------------------------+ | | |
| ``date`` | <value>2010-04-27</value> | | | <value>true</value> |
+---------------+------------------------------------+ +---------------+----------------------------------------+
| ``time`` | <value>12:54:18</value> | | ``Decimal`` | .. code-block:: xml |
+---------------+------------------------------------+ | | |
| ``datetime`` | <value>2010-04-27T12:54:18</value> | | | <value>5.46</value> |
+---------------+------------------------------------+ +---------------+----------------------------------------+
| Arrays | .. code-block:: xml | | ``date`` | .. code-block:: xml |
| | | | | |
| | <value> | | | <value>2010-04-27</value> |
| | <item>Dinausaurs<item> | +---------------+----------------------------------------+
| | <item>Rachel<item> | | ``time`` | .. code-block:: xml |
| | </value> | | | |
+---------------+------------------------------------+ | | <value>12:54:18</value> |
| None | .. code-block:: xml | +---------------+----------------------------------------+
| | | | ``datetime`` | .. code-block:: xml |
| | <value nil="true"/> | | | |
+---------------+------------------------------------+ | | <value>2010-04-27T12:54:18</value> |
| Complex types | .. code-block:: xml | +---------------+----------------------------------------+
| | | | Arrays | .. code-block:: xml |
| | <value> | | | |
| | <id>1</id> | | | <value> |
| | <fistname>1</fistname> | | | <item>Dinausaurs<item> |
| | </value> | | | <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 Return
~~~~~~ ~~~~~~
@ -336,3 +283,79 @@ expose extra options
function. function.
.. _Ext Direct: http://www.sencha.com/products/extjs/extdirect .. _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')

3
doc/types.rst
View File

@ -167,7 +167,8 @@ A few things you should know about complex types:
assert Person.name.key == "name" assert Person.name.key == "name"
assert Person.name.mandatory is False 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>`.
:: ::