Skip to content
Browse files

Add BetterDict documentation

  • Loading branch information...
1 parent ae1cdcc commit 79f13067aae15a6a57ae6dd0f899ecc4e52794af @thomasw committed Nov 25, 2012
Showing with 172 additions and 5 deletions.
  1. +128 −0 docs/source/betterdict.rst
  2. +6 −0 docs/source/changelog.rst
  3. +22 −5 docs/source/index.rst
  4. +14 −0 docs/source/installation.rst
  5. +2 −0 docs/source/querylist.rst
View
128 docs/source/betterdict.rst
@@ -0,0 +1,128 @@
+BetterDict
+==========
+
+A BetterDict is a data structure that is backwards compatible with Python's
+built in dict type. It has all of the usual dict methods and can still preform
+index based lookup and assignment of key values. Even an equal to comparison
+of a BetterDict instance invoked with the same data as a dict instance will
+evaluate to true.
+
+In addition to standard dict functionality,
+BetterDicts also allows dot lookup and assignment of key values.
+
+ >>> from querylist import BetterDict
+ >>> a = BetterDict()
+ >>> b = dict()
+ >>> a.cats = 18
+ >>> a['dogs'] = 372
+ >>> a.hedgehogs = 19
+ >>> b['cats'] = 18
+ >>> b['dogs'] = 372
+ >>> b['hedgehogs'] = 19
+ >>> a == b
+ True
+ >>> dir(a)
+ ['__class__', '__cmp__', '__contains__', '__delattr__', '__delitem__',
+ '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__',
+ '__getitem__', '__gt__', '__hash__', '__init__', '__iter__', '__le__',
+ '__len__', '__lt__', '__ne__', '__new__', '__reduce__', '__reduce_ex__',
+ '__repr__', '__setattr__', '__setitem__', '__sizeof__', '__str__',
+ '__subclasshook__', 'cats', 'clear', 'copy', 'dogs', 'fromkeys', 'get',
+ 'has_key', 'hedgehogs', 'items', 'iteritems', 'iterkeys', 'itervalues',
+ 'keys', 'pop', 'popitem', 'setdefault', 'update', 'values']
+
+Dot lookups and assignments
+---------------------------
+
+Dot lookups that correspond to keys will return the key's value
+
+ >>> foo = BetterDict()
+ >>> foo['yay'] = 1
+ >>> foo.yay
+ 1
+
+An assignment will update that key's value:
+
+ >>> foo.yay = 0
+ >>> foo['yay']
+ 0
+
+Assignment of an attribute that has not yet been added as a key to the
+BetterDict will add the key/value pair.
+
+ >>> foo.yeah = True
+ >>> foo['yeah']
+ True
+
+However, a lookup for an attribute that is neither a key nor a normal dict
+attribute will raise an ``AttributeError``:
+
+ >>> foo.bar
+ Traceback (most recent call last):
+ File "<stdin>", line 1, in <module>
+ File "querylist/betterdict.py", line 6, in __getattr__
+ raise AttributeError
+ AttributeError
+
+Nested Dictionaries
+-------------------
+
+A nested dictionary's keys are also accessible via dot lookup. BetterDict
+achieves this by converting member dicts to BetterDicts:
+
+Consider the following BetterDict definition:
+
+ >>> c = BetterDict({
+ ... 'foo': 1,
+ ... 'bar': {
+ ... 'a': 0,
+ ... 'b': 1,
+ ... 'c': 2,
+ ... 'another': {
+ ... 'd': 0,
+ ... 'e': 1,
+ ... 'f': 2,
+ ... }
+ ... },
+ ... })
+
+``c.bar`` will return the BetterDict at ``c['bar']``:
+
+ >>> c.bar
+ {'a': 0, 'c': 2, 'b': 1, 'another': {'e': 1, 'd': 0, 'f': 2}}
+
+Similarly, ``c.bar.another.d`` will descend down to
+``c['bar']['another']['d']`` and an assignment using the same identifier chain
+will update that value:
+
+ >>> c.bar.another.d
+ 0
+ >>> c.bar.another.d = True
+ >>> c.bar.another
+ {'e': 1, 'd': True, 'f': 2}
+
+Resolving key name / dict attribute conflicts (the ``_bd_`` attribute)
+-----------------------------------------------------------------------
+
+When a BetterDict has a key that conflicts with the name of a standard dict
+attribute, the BetterDict does not overwrite the standard attribute. Doing so
+would break backwards compatibility for BetterDicts with specific key/value
+pairs.
+
+ >>> problem = BetterDict({'update': '3 days ago'})
+ >>> problem.update
+ <built-in method update of BetterDict object at 0x7fb9f047b610>
+ >>> problem['update']
+ '3 days ago'
+
+As a work around for this issue, all BetterDicts have an attribute named
+``_bd_``, which is protected from being overwritten just like standard dict
+attributes. The ``_bd_`` attribute allows dot lookup and assignment of all a
+BetterDict's keys regardless of whether or not their name conflicts with a
+dict attribute.
+
+ >>> problem._bd_.update
+ '3 days ago'
+ >>> problem._bd_.update = '4 days ago'
+ >>> problem['update']
+ '4 days ago'
View
6 docs/source/changelog.rst
@@ -0,0 +1,6 @@
+Changelog
+=========
+
+**0.0.1**
+
+* Initial relase
View
27 docs/source/index.rst
@@ -3,18 +3,35 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
-Welcome to Querylist's documentation!
-=====================================
+Querylist
+=========
-Contents:
+Sick of for loop + conditional soup when dealing with complicated lists?
+Querylist is here to help.
+
+This package provides a data structure called a QueryList, an extension of
+Python's built in list data type that adds django ORM-eseque filtering,
+exclusion, and get methods. QueryLists allow developers to easily query and
+retrieve data from complex lists without the need for unnecessarily verbose
+iteration and selection cruft.
+
+The package also provides BetterDict, a backwards-compatible wrapper for
+dictionaries that enables dot lookups and assignment for key values.
+
+Contents
+--------
.. toctree::
:maxdepth: 2
-
+
+ installation
+ betterdict
+ querylist
+ changelog
Indices and tables
-==================
+------------------
* :ref:`genindex`
* :ref:`modindex`
View
14 docs/source/installation.rst
@@ -0,0 +1,14 @@
+Installation
+============
+
+You can install querylist like you'd install any other python package:
+
+ $ pip install querylist
+
+Once installed, you can import both QueryList and BetterDict directly from
+the querylist module and use them to your heart's content.
+
+ >>> from querylist import BetterDict, QueryList
+
+QueryList is currently only tested against Python 2.6 and 2.7, though it
+should work in 2.5 as well.
View
2 docs/source/querylist.rst
@@ -0,0 +1,2 @@
+QueryList
+=========

0 comments on commit 79f1306

Please sign in to comment.
Something went wrong with that request. Please try again.