Changeset 16

Timestamp:

10/12/04 23:26:49

Author:

fumanchu

Message:

Doc, docstring, and comment updates

Files:

• trunk/__init__.py (modified) (4 diffs)
• trunk/containers.py (modified) (1 diff)
• trunk/doc/index.html (modified) (1 diff)
• trunk/doc/intro.html (modified) (3 diffs)
• trunk/doc/modeling.html (modified) (10 diffs)
• trunk/storage/sockets.py (modified) (1 diff)

trunk/__init__.py

@@ -239 +239 @@
-    
-    def indices(cls):
+        """cls.indices() -> tuple of names of indexed UnitProperties."""
-        product = []
-        for key in cls.properties():
@@ -251 +252 @@
-    
-    def properties(cls):
+        """cls.properties() -> list of UnitProperty names."""
-        return cls._properties.iterkeys()
-    properties = classmethod(properties)
-    
-    def property_type(cls, key):
+        """cls.property_type(key) -> type of the given UnitProperty."""
-        # Retrieving from the class gives us
-        # the UnitProperty object, not its value.
@@ -261 +264 @@
-    
-    def adjust(self, **values):
+        """adjust(**values) -> Set UnitProperties by key, value pairs."""
-        for key, val in values.iteritems():
-            setattr(self, key, val)
-    
-    def repress(self):
+        """repress() -> Remove this Unit from memory (do not destroy)."""
-        self.sandbox.repress(self)
-    
-    def forget(self):
+        """forget() -> Destroy this Unit."""
-        self.sandbox.forget(self)
-    
@@ -301 +307 @@
-# The default ID type is int. If you wish to use a different type for
-# the ID's of a subclass of Unit, just overwrite ID, e.g.:
+#     ID = UnitProperty('ID', unicode, index=True)
+#       or
-#     UnitSubclass.set_property('ID', unicode, index=True)
-
+
+
+
-Unit.set_property(u'ID', int, index=True)
-

trunk/containers.py

@@ -9 +9 @@
-and map.
-
-Chain, Graph, and Index
+Graph, Index, and Prism
-
-This work, including the source code, documentation

trunk/doc/index.html

@@ -48 +48 @@
-        <ul>
-        <li>The <tt>Expression</tt> class</li>
+        <li>Early binding</li>
-        <li>External functions within Expressions</li>
-        <li>Combining Expressions</li>
-
+
+
-        <li>Exporting the <tt>logic</tt> module</li>
-        </ul>
-    </li>
-
+
+
+
+
+
+
-    <li>Analysis Tools</li>
-    <li>The Arena Object
-        <ul>
-
+
+
+
-        </ul>
-    </li>

trunk/doc/intro.html

@@ -29 +29 @@
-mindsets, each Unit subclass corresponds to a table; instances of the class
-correspond to the rows. Each subclass possesses a set of attributes known
-<tt>properties</tt>
+"properties"
-table. These attributes are generally formed from a <tt>UnitProperty</tt>
-descriptor. Any Unit data which needs to be persisted ought to be contained
@@ -157 +157 @@
-</p>
-
+<p>In particular, Dejavu was designed to make complex integration easier.
+Unlike most generic storage wrappers, Dejavu does not <i>require</i> you to
+have complete control of your back end. For example, consider Mission
+Control, the first application built on Dejavu. Mission Control required
+an ORM which transparently supported two very different backends. Half of
+the data was to be stored in an MS Access database (which is being migrated
+to SQL Server), over which the application developers had full control.
+But half of the data was stored in a third-party application, "The Raiser's
+Edge" (RE) from Blackbaud. RE provides read-only database access; all writes
+must go through their object-oriented API. Further, reading via that API was
+found to be too slow. Therefore, a custom Storage Manager (about 2500 lines
+of code) was developed, which searches for and loads objects via SQL, but
+writes Unit data via the REAPI. Dejavu allows the application logic to be
+completely ignorant of this complex mass of storage details. If Blackbaud
+closed its doors tomorrow, the solution could be quickly migrated to another
+data store; business downtime is reduced in the face of inevitable change.<p>
-
-<h3>Obtaining and Installing</h3>
@@ -164 +180 @@
-installed in <tt>site-packages/dejavu</tt>.</p>
-
+<p>Dejavu was built using Python 2.3.2. You should probably use
+at least 2.3; Dejavu depends upon the <tt>datetime</tt> module.
+Although Dejavu <i>supports</i> additional modules like
+<tt>fixedpoint</tt> and <tt>decimal</tt>, it does not <i>require</i>
+them.</p>
+
+<p>Dejavu uses bytecode hacks, and therefore requires CPython
+<a href='#cpython'>[2]</a>.</p>
+
-<h3>Compared To Other Database Wrappers</h3>
-<p>TBW</p>
-
-
-
-
-
+
+
+
-<a href='http://www.martinfowler.com/eaaCatalog/identityMap.html'>Patterns
-of Enterprise Application Architecture</a>.<br />

trunk/doc/modeling.html

@@ -114 +114 @@
-<tt>index</tt> value tells Storage Managers whether or not to index the
-column. The <tt>type</tt> attribute limits property values to instances
-, or None. Finally, the <tt>hints</tt> dictionary provides
-
-
+ (or <tt>None</tt>). Finally, the <tt>hints</tt> dictionary
+
+for 
-as strings of length 255, that a particular value should be a larger object;
-this is done with a 'Size' mapping, such as <tt>hints = {u'Size': 0}</tt>,
@@ -160 +160 @@
-Storage Manager.</p>
-
-
-he top-level <tt>Arena</tt> object. Arenas
+ the
+op-level <tt>Arena</tt> object. Arenas also
-<tt>new_sandbox</tt>, which does this for you. The following lines are
-equivalent:
@@ -171 +171 @@
-the Sandbox class.</p>
-
-
+ Units
-<p>When you create a Unit instance, it exists in isolation. There is no
-connection between that Unit and storage; your Unit will not be persisted,
@@ -303 +303 @@
-a given class. In Dejavu, you filter the set according to the UnitProperty
-attributes for each object. Naturally, there must be a way to express
-
+
+
-
-<h4>The <tt>Expression</tt> class</h4>
@@ -320 +321 @@
-into an Expression must possess a single positional argument, which will
-always be bound to a Unit instance. In the example above, it's named 'x',
-
-
-
-
-
-
+
+
+
+
+
+
+
-<p>What is not obvious from the above code snippet is perhaps the <b>most
-important aspect</b> of Expressions: any globals or cell references (from 
@@ -433 +435 @@
-instead, they will simply retrieve a larger set of objects from storage,
-evaluate each one against the function you provide, and return those
-
+
+
+
+
+
-
-<h4>Combining Expressions</h4>
-"&" operator, the two condition
-list
+<tt>&</tt> operator, the two
+expression
-<pre>>>> a = logic.Expression(lambda x: x.Size > 3)
->>> b = logic.Expression(lambda x: x.Size <= 15)
@@ -446 +452 @@
-<tt>|</tt> operator combines the two Expressions with a logical 'or'.</p>
-
-Expressions using <tt>filter</tt> and <tt>comparison</tt>
+Using <tt>filter</tt> to form Expressions
-<p>The <tt>logic</tt> module also provides convenient methods to
-create common types of Expression objects via the <tt>filter</tt> and
@@ -458 +464 @@
-</p>
-
+<h4>Using <tt>comparison</tt> to form Expressions</h4>
-<p>The <tt>comparison(attr, cmp_op, criteria)</tt> function allows you to
-form Expressions with dynamic operators. This can come in handy when you
@@ -507 +514 @@
-
-
+<h3>Associations between Unit Classes</h3>
+<p>Once you've put together some Unit classes, chances are you're going to
+want to associate them. Generally, this is accomplished by creating a
+property in the Unit_B class which stores IDs of Unit_A objects (which
+might be called <i>foreign keys</i> in a database context).
+<pre>class Archaeologist(Unit):
+    Height = UnitProperty('Height', float)
+
+class Biography(Unit):
+    ArchID = UnitProperty('ArchID', int)</pre>
+In this example, each <tt>Biography</tt> object will have an <tt>ArchID</tt>
+attribute, which will equal the <tt>ID</tt> of some <tt>Archaeologist</tt>.
+In Dejavu terms, we say that there is a <i>near class</i> (with a <i>near
+key</i>) and a <i>far class</i> (with a <i>far key</i>). Associations in
+Dejavu are not one-way, so it doesn't matter which class you choose for the
+"near" one and which for the "far" one.</p>
+
+<p>You could stop at this point in your design, and simply remember what
+these keys are and how they relate, and manipulate them accordingly. But
+Dejavu allows you to <i>register</i> these associations explicitly in your
+<tt>Arena</tt>:
+<pre>myArena.associate(Archaeologist, 'ID', Biography, 'ArchID')</pre>
+You pass in the near class, the near key, the far class, and the far key.
+</p>
+
+<p>What does an explicit association buy for you? First, the <tt>associate</tt>
+call adds an entry in the <tt>Arena.associations</tt> registry, so that
+smart consumer code (like Unit Engine Rules, below) can automatically
+follow association paths for you. Second, each Unit class has a private
+<tt>_associations</tt> attribute, a <tt>dict</tt>. Each Unit involved
+in the association gains an entry in that dict: the key is the far class
+itself (not the class name), and the value is a tuple of (far key, near key).
+Third, <tt>associate()</tt> can be used to register your Unit classes in
+the Arena's <tt>roster</tt>; you don't have to call <tt>register</tt> for
+either class if you call <tt>associate</tt> (see <u>The Arena Object</u>,
+below).</p>
+
+<p>In addition, each of the Unit classes will gain a new <i>synapse</i>
+method which simplifies looking up related instances of the other class.
+The new method for Unit_B will have the name of Unit_A, and vice-versa.
+In our example:
+<pre>>>> Archaeologist.Biography
+&lt;unbound method Archaeologist.synapses>
+>>> Eversley = Archaeologist(Height=(6.417))
+>>> Eversley.Biography
+&lt;bound method Archaeologist.synapses of &lt;__main__.Archaeologist
+object at 0x011A1930>>
+>>> bios = Eversley.Biography()
+>>> bios
+&lt;listiterator object at 0x012150D0>
+>>> list(bios)
+[]
+</pre>
+We haven't created any Biographies, so there aren't any to be recalled,
+which is why we get an empty iterator at this point. At the other extreme
+(when you have hundreds of Biographies to filter), you can pass an optional
+<tt>Expression</tt> object to the synapse method. When you do, the list of
+associated Units will be filtered accordingly.</p>
+
+<p>Because the synapse method names are formed automatically, you need
+to take care not to use the names of Unit classes for your Unit properties.
+In our example, we used "ArchID" for the name of our "foreign key".
+If we had used "Archaeologist" instead, we would have had problems;
+when we associated the classes, the <i>property</i> named "Archaeologist"
+would have collided with the <i>synapse method</i> named "Archaeologist".
+Be careful when naming your properties, and plan for the future.</p>
+
+<p>Unlike some other ORM's, Dejavu doesn't cache far Units within
+the near Unit. Each time you call the synapse method, the data is recalled
+from your Sandbox. It is quite probable that those far Units are still
+sitting in memory in the Sandbox, but they're not going to persist in
+the near Unit itself in any way.</p>
+
+<p>Finally, some of you may want to override the default synapse methods.
+Feel free; <tt>Arena.associate</tt> takes two optional arguments, which
+should be callables that return the new function(s). See the source code
+of <tt>Arena</tt> and the private method <tt>dejavu._synapses_func</tt>
+for more information.</p>
+
-<h3>Unit Engines</h3>
+<p></p>
+
+<h4>Engine Functions</h4>
-<p></p>
-
@@ -524 +613 @@
-running instance of the program.</p>
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-
-<p><a name='hettinger'>[1]</a> Python Cookbook,

trunk/storage/sockets.py

@@ -100 +100 @@
-        data = dechunk(''.join(data))
-        if data and data[0] == 'ERROR':
+            # The value in data[1] is a pickled Exception.
-            raise pickle.loads(data[1])
-        return data