Permalink
Browse files

Adding Documentation

  • Loading branch information...
1 parent fcbba36 commit 318833df8e1248f8772c4be9ff7de5e608d7ebce @reedobrien reedobrien committed Jan 28, 2011
Showing with 57 additions and 27 deletions.
  1. +2 −6 docs/api/son.rst
  2. +7 −0 docs/glossary.rst
  3. +48 −21 lumin/son.py
View
@@ -12,11 +12,7 @@
.. autoclass:: DecimalTransformer(son, collection)
:members:
-.. autoclass:: DeNull(son)
- :members:
-
-.. autoclass:: DeSentinel(son)
- :members:
-
+.. autoattribute:: lumin.son.denull
+.. autoattribute:: lumin.son.desentinel
View
@@ -13,6 +13,13 @@
JSON, an HTML form post or any other equally simple data
serialization.
+ colander.null
+ A `null value
+ <http://docs.repoze.org/colander/api.html#colander.null>` for
+ colander related operations. See the `colander docs
+ <http://docs.repoze.org/colander/null.html>` for more
+ informration.
+
deform
`deform <http://docs.repoze.org/deform/>` is a Python HTML form
generation library.
View
@@ -8,7 +8,7 @@
class ColanderNullTransformer(SONManipulator):
"""
- Added to the db at load time, this allows MongoDB to store and
+ Added to the db after connection is created. This allows MongoDB to store and
retrieve sentinals for ``colander.null`` values. ``colander.null``
is a object which represents that a colander.Schema value is
missing or undefined. A :term:`son_manipulator` is a object that
@@ -75,9 +75,22 @@ def _recursive_out(self, subson):
class DecimalTransformer(SONManipulator):
"""
+ Added to the db after connection is created. This allows MongoDB
+ to store and retrieve Decimal values. A :term:`son_manipulator` is
+ a object that edits :term:`SON` objects as they enter or exit a
+ MongoDB
+
+ .. code-block:: python
+
+ import pymongo
+ db = pymongo.Connection().testdb['acollection']
+ from lumin.son import DecimalTransformer
+ db.add_son_manipulator(DecimalTransformer())
+
"""
def transform_incoming(self, son, collection):
"""
+ sets any DecimalTransformer to a serializable value.
"""
for (k, v) in son.items():
if isinstance(v, Decimal):
@@ -88,6 +101,8 @@ def transform_incoming(self, son, collection):
def transform_outgoing(self, son, collection):
"""
+ Sets any top level serialized Decimal to a Decimal. This is
+ not recursive.
"""
for (k, v) in son.items():
if isinstance(v, dict):
@@ -100,61 +115,72 @@ def transform_outgoing(self, son, collection):
class DeNull:
"""
+ ``DeNull`` is a callable that recursively replaces
+ :term:`colander.null` with an empty ``string`` ``u''``. It is
+ usefull for allowing items where :term:`colander.null` is not
+ supported.
+
+ .. code-block:: python
+
+ from lumin.son import denull
+ foo = desentinel({u"foo" : colander.null})
+ assert foo == {u"foo" : u''}
"""
def __call__(self, son):
- """
- """
- return self.transform(son)
+ return self._transform(son)
- def transform(self, son):
- """
- """
+ def _transform(self, son):
for (k, v) in son.items():
if v is colander.null:
- son[k] = ''
+ son[k] = u''
continue
if isinstance(v, dict):
- self.recurse(v)
+ self._recurse(v)
return son
- def recurse(self, subson):
- """
- """
+ def _recurse(self, subson):
for (k, v) in subson.items():
if v is colander.null:
subson[k] = ''
continue
if isinstance(v, dict):
for (key, value) in v.items():
if value is colander.null:
- v[key] = ''
+ v[key] = u''
if isinstance(value, dict):
self.recurse(value)
denull = DeNull()
class DeSentinel:
"""
+ ``DeSentinel`` is similar to ``DeNull``. It is a callable that
+ recursively replaces ``lumin.son.SENTINAL`` with an empty
+ ``string`` ``u''``. It is usefull to allow using items where
+ ``lumin.son.SENTINAL`` is not supported or useful, such as a text
+ index.
+
+ .. code-block:: python
+
+ from lumin.son import desentinel
+ foo = desentinel({u"foo" : SENTINEL})
+ assert foo == {u"foo" : u''}
"""
def __call__(self, son):
- """
- """
- return self.transform(son)
+ return self._transform(son)
- def transform(self, son):
+ def _transform(self, son):
"""
"""
for (k, v) in son.items():
if v is SENTINEL:
son[k] = ''
continue
if isinstance(v, dict):
- self.recurse(v)
+ self._recurse(v)
return son
- def recurse(self, subson):
- """
- """
+ def _recurse(self, subson):
for (k, v) in subson.items():
if v is SENTINEL:
subson[k] = ''
@@ -166,3 +192,4 @@ def recurse(self, subson):
if isinstance(value, dict):
self.recurse(value)
desentinel = DeSentinel()
+

0 comments on commit 318833d

Please sign in to comment.