Permalink
Browse files

Updated documentation

  • Loading branch information...
1 parent e10156f commit 885c5eed1fb2e4bfa412df3822693c08cd1ebaee @jeffjenkins committed Feb 24, 2013
@@ -84,7 +84,14 @@ Mapping Type Fields
Document Field Objects
--------------------------------------------------------
-.. autoclass:: mongoalchemy.document.DocumentField
+.. autoclass:: mongoalchemy.fields.DocumentField
+ :members:
+ :undoc-members:
+
+Reference Field Objects
+--------------------------------------------------------
+
+.. autoclass:: mongoalchemy.fields.RefField
:members:
:undoc-members:
@@ -32,32 +32,52 @@ significantly slower and more likely to cause data loss.
There's more detail in the :doc:`tutorial`, but a small example is on
this page below the contents of the documentation.
-Interesting Features
+A Tour of MongoAlchemy's Features
+
+Object-Document Mapping
+-----------------------------
+
+Turn MongoDB documents into Python objects and vice-versa, add schemas and
+validatation to your models, and allow the separation of the python and
+mongo representations of your data.
+
+* Support for all of the basic mongo types.
+* Separate Python and Mongo names. Field and collection names can be
+ overridden.
+* Indexing on dict keys. MA provides a dict-like field which can have
+ arbitrary key and value types as well as allowing indexing on the keys —
+ not normally possible in Mongo. See: :class:`~mongoalchemy.fields.KVField`
+* Computed values, generate from other fields.
+ See: :class:`~mongoalchemy.fields.ComputedField`
+* Created and Modified fields based on the computed fields which record the
+ date something was first created or last updated.
+* Timezone support. A timezone can be passed using pytz and all dates will
+ have timezone data attached and be converted to the given timezone.
+* User-defined validation — Provide your own validation functions for
+ simple validations of fields. See :class:`~mongoalchemy.fields.Field`
+* User-defined fields — For more customization, entirely new fields can be
+ created
+* A field that can hold arbitrary values: :class:`~mongoalchemy.fields.AnythingField`
+* Validation happens at assignment time, so you'll know exactly where
+* Indexes are defined on the class
+
+Sessions and Query Language
-----------------------------
-* **Object-Document-Mapping**: Turn MongoDB documents into Python objects and vice-versa.
-* **A rich expression language**: which can be used to do queries for loading documents \
- as well as updating documents without loading them.
-* **Use Any Collection and Field Names** — Configuration allows collection names and \
- field names to be different from their python names.
-* **Computed Fields** :class:`~mongoalchemy.fields.ComputedField` fields allow a function \
- to be used to generate the value for a field. Extremely useful for fields \
- where the value is a function (like a last-updated field), or where the \
- field is generated from other fields (like a set of keywords generated \
- or the components of a URL)
-* **User-defined validation** — for values being wrapped for the database or unwrapped \
- into a python object, as well as validators which happen for both. See :class:`~mongoalchemy.fields.Field` \
-* **Arbitrary Value Fields** — A field that can hold arbitrary values: :class:`~mongoalchemy.fields.AnythingField`
-* **More Flexible Mapping Type** A dict-like field which can have arbitrary key and value types as well as allowing \
- indexing on the keys — not normally possible in Mongo — by storing them in \
- a different format than how they appear when accessed in python a plain dict. :class:`~mongoalchemy.fields.KVField`
-* **Automatically Calculated Updates** — The session object has an :func:`mongoalchemy.session.Session.update` function which \
- determines which fields are dirty and will execute the appropriate update operations to update the object in the database. \
- The operations used for updating can be overriden at the field definition level as well as in the ``update`` call.
-* **Drop into raw Mongo** — Most functions will accept raw pymongo instead of the mongoalchemy objects. \
+* Type-safe queries. Queries are validated to make sure the values passed are
+ allowed in the query fields.
+* Faux-Transactions. When using the session with the ``with`` statement updates
+ are accumulated until the block is done, making it much less likely that a
+ python error will leave your database in a bad state.
+* Automatically Calculated Updates — The session object has an :func:`mongoalchemy.session.Session.update`
+ function which determines which fields are dirty and will execute the
+ appropriate update operations to update the object in the database.
+* Drop into raw Mongo. Most functions will accept raw pymongo instead of
+ the mongoalchemy objects. Type safety will be maintained either way
+
For example::
- session.query('SomeClass').filter(SomeClass.name == foo).limit(5)``
+ session.query('SomeClass').filter(SomeClass.name == foo).limit(5)
is perfectly valid, as is::
@@ -66,11 +86,10 @@ Interesting Features
-
Installation
-----------------------------
-``easy_install MongoAlchemy``
+``pip MongoAlchemy``
You can also download the source code from the Python Package index or GitHub:
@@ -83,7 +102,7 @@ Examples
------------------------------
>>> from mongoalchemy.session import Session
- >>> from mongoalchemy.document import Document, Index, DocumentField
+ >>> from mongoalchemy.document import Document, Index
>>> from mongoalchemy.fields import *
>>> # Subclasses of Document both provide the mapping needed for
... # queries as well as the classes for loading/saving objects.
@@ -451,7 +451,7 @@
<dl class="class">
<dt id="mongoalchemy.query.QueryResult">
-<em class="property">class </em><tt class="descclassname">mongoalchemy.query.</tt><tt class="descname">QueryResult</tt><big>(</big><em>cursor</em>, <em>type</em>, <em>raw_output=False</em>, <em>fields=None</em><big>)</big><a class="headerlink" href="#mongoalchemy.query.QueryResult" title="Permalink to this definition">¶</a></dt>
+<em class="property">class </em><tt class="descclassname">mongoalchemy.query.</tt><tt class="descname">QueryResult</tt><big>(</big><em>session</em>, <em>cursor</em>, <em>type</em>, <em>raw_output=False</em>, <em>fields=None</em><big>)</big><a class="headerlink" href="#mongoalchemy.query.QueryResult" title="Permalink to this definition">¶</a></dt>
<dd><dl class="method">
<dt id="mongoalchemy.query.QueryResult.next">
<tt class="descname">next</tt><big>(</big><big>)</big><a class="headerlink" href="#mongoalchemy.query.QueryResult.next" title="Permalink to this definition">¶</a></dt>
@@ -137,6 +137,12 @@
</dd></dl>
<dl class="method">
+<dt id="mongoalchemy.query_expression.QueryField.exists">
+<tt class="descname">exists</tt><big>(</big><em>exists=True</em><big>)</big><a class="headerlink" href="#mongoalchemy.query_expression.QueryField.exists" title="Permalink to this definition">¶</a></dt>
+<dd><p>Create a MongoDB query to check if a field exists on a Document.</p>
+</dd></dl>
+
+<dl class="method">
<dt id="mongoalchemy.query_expression.QueryField.eq_">
<tt class="descname">eq_</tt><big>(</big><em>value</em><big>)</big><a class="headerlink" href="#mongoalchemy.query_expression.QueryField.eq_" title="Permalink to this definition">¶</a></dt>
<dd><p>Creates a query expression where <tt class="docutils literal"><span class="pre">this</span> <span class="pre">field</span> <span class="pre">==</span> <span class="pre">value</span></tt></p>
@@ -69,6 +69,7 @@
<li class="toctree-l3"><a class="reference internal" href="schema/fields.html#sequence-type-fields">Sequence Type Fields</a></li>
<li class="toctree-l3"><a class="reference internal" href="schema/fields.html#mapping-type-fields">Mapping Type Fields</a></li>
<li class="toctree-l3"><a class="reference internal" href="schema/fields.html#document-field-objects">Document Field Objects</a></li>
+<li class="toctree-l3"><a class="reference internal" href="schema/fields.html#reference-field-objects">Reference Field Objects</a></li>
<li class="toctree-l3"><a class="reference internal" href="schema/fields.html#computed-field-objects">Computed Field Objects</a></li>
</ul>
</li>
@@ -110,6 +110,30 @@
</dd></dl>
<dl class="attribute">
+<dt id="mongoalchemy.document.Document.config_polymorphic">
+<tt class="descname">config_polymorphic</tt><a class="headerlink" href="#mongoalchemy.document.Document.config_polymorphic" title="Permalink to this definition">¶</a></dt>
+<dd><p>The variable to use when determining which class to instantiate a
+database object with. It is the name of an attribute which
+will be used to decide the type of the object. If you want more
+control over which class is selected, you can override
+<tt class="docutils literal"><span class="pre">get_subclass</span></tt>.</p>
+</dd></dl>
+
+<dl class="attribute">
+<dt id="mongoalchemy.document.Document.config_polymorphic_collection">
+<tt class="descname">config_polymorphic_collection</tt><a class="headerlink" href="#mongoalchemy.document.Document.config_polymorphic_collection" title="Permalink to this definition">¶</a></dt>
+<dd><p>Use the base class collection name for the subclasses. Default: False</p>
+</dd></dl>
+
+<dl class="attribute">
+<dt id="mongoalchemy.document.Document.config_polymorphic_identity">
+<tt class="descname">config_polymorphic_identity</tt><a class="headerlink" href="#mongoalchemy.document.Document.config_polymorphic_identity" title="Permalink to this definition">¶</a></dt>
+<dd><p>When using a string value with <tt class="docutils literal"><span class="pre">config_polymorphic_on</span></tt> in a parent
+class, this is the value that the attribute is compared to when
+determining</p>
+</dd></dl>
+
+<dl class="attribute">
<dt id="mongoalchemy.document.Document.config_full_name">
<tt class="descname">config_full_name</tt><a class="headerlink" href="#mongoalchemy.document.Document.config_full_name" title="Permalink to this definition">¶</a></dt>
<dd><p>If namespaces are being used, the key for a class is normally
@@ -128,6 +152,33 @@
<a class="reference internal" href="#mongoalchemy.document.Document.get_extra_fields" title="mongoalchemy.document.Document.get_extra_fields"><tt class="xref py py-func docutils literal"><span class="pre">get_extra_fields()</span></tt></a></p>
</dd></dl>
+<dl class="classmethod">
+<dt id="mongoalchemy.document.Document.schema_json">
+<em class="property">classmethod </em><tt class="descname">schema_json</tt><big>(</big><big>)</big><a class="headerlink" href="#mongoalchemy.document.Document.schema_json" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
+
+<dl class="classmethod">
+<dt id="mongoalchemy.document.Document.add_subclass">
+<em class="property">classmethod </em><tt class="descname">add_subclass</tt><big>(</big><em>subclass</em><big>)</big><a class="headerlink" href="#mongoalchemy.document.Document.add_subclass" title="Permalink to this definition">¶</a></dt>
+<dd><p>Register a subclass of this class. Maps the subclass to the
+value of subclass.config_polymorphic_identity if available.</p>
+</dd></dl>
+
+<dl class="classmethod">
+<dt id="mongoalchemy.document.Document.get_subclass">
+<em class="property">classmethod </em><tt class="descname">get_subclass</tt><big>(</big><em>obj</em><big>)</big><a class="headerlink" href="#mongoalchemy.document.Document.get_subclass" title="Permalink to this definition">¶</a></dt>
+<dd><p>Get the subclass to use when instantiating a polymorphic object.
+The default implementation looks at <tt class="docutils literal"><span class="pre">cls.config_polymorphic</span></tt>
+to get the name of an attribute. Subclasses automatically
+register their value for that attribute on creation via their
+<tt class="docutils literal"><span class="pre">config_polymorphic_identity</span></tt> field. This process is then
+repeated recursively until None is returned (indicating that the
+current class is the correct one)</p>
+<p>This method can be overridden to allow any method you would like
+to use to select subclasses. It should return either the subclass
+to use or None, if the original class should be used.</p>
+</dd></dl>
+
<dl class="method">
<dt id="mongoalchemy.document.Document.get_dirty_ops">
<tt class="descname">get_dirty_ops</tt><big>(</big><em>with_required=False</em><big>)</big><a class="headerlink" href="#mongoalchemy.document.Document.get_dirty_ops" title="Permalink to this definition">¶</a></dt>
@@ -184,25 +235,23 @@
for the current class.</p>
</dd></dl>
+<dl class="classmethod">
+<dt id="mongoalchemy.document.Document.transform_incoming">
+<em class="property">classmethod </em><tt class="descname">transform_incoming</tt><big>(</big><em>obj</em>, <em>session</em><big>)</big><a class="headerlink" href="#mongoalchemy.document.Document.transform_incoming" title="Permalink to this definition">¶</a></dt>
+<dd><p>Tranform the SON object into one which will be able to be
+unwrapped by this document class.</p>
+<p>This method is designed for schema migration systems.</p>
+</dd></dl>
+
<dl class="method">
<dt id="mongoalchemy.document.Document.has_id">
<tt class="descname">has_id</tt><big>(</big><big>)</big><a class="headerlink" href="#mongoalchemy.document.Document.has_id" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="method">
-<dt id="mongoalchemy.document.Document.commit">
-<tt class="descname">commit</tt><big>(</big><em>db</em>, <em>safe=True</em><big>)</big><a class="headerlink" href="#mongoalchemy.document.Document.commit" title="Permalink to this definition">¶</a></dt>
-<dd><p>Save this object to the database and set the <tt class="docutils literal"><span class="pre">_id</span></tt> field of this
-document to the returned id.</p>
-<table class="docutils field-list" frame="void" rules="none">
-<col class="field-name" />
-<col class="field-body" />
-<tbody valign="top">
-<tr class="field"><th class="field-name">Parameters:</th><td class="field-body"><strong>db</strong> &#8211; The pymongo database to write to</td>
-</tr>
-</tbody>
-</table>
-</dd></dl>
+<dt id="mongoalchemy.document.Document.to_ref">
+<tt class="descname">to_ref</tt><big>(</big><em>db=None</em><big>)</big><a class="headerlink" href="#mongoalchemy.document.Document.to_ref" title="Permalink to this definition">¶</a></dt>
+<dd></dd></dl>
<dl class="method">
<dt id="mongoalchemy.document.Document.wrap">
@@ -213,17 +262,8 @@
</dd></dl>
<dl class="classmethod">
-<dt id="mongoalchemy.document.Document.validate_unwrap">
-<em class="property">classmethod </em><tt class="descname">validate_unwrap</tt><big>(</big><em>obj</em>, <em>fields=None</em><big>)</big><a class="headerlink" href="#mongoalchemy.document.Document.validate_unwrap" title="Permalink to this definition">¶</a></dt>
-<dd><p>Attempts to unwrap the document, and raises a BadValueException if
-the operation fails. A TODO is to make this function do the checks
-without actually doing the (potentially expensive)
-deserialization</p>
-</dd></dl>
-
-<dl class="classmethod">
<dt id="mongoalchemy.document.Document.unwrap">
-<em class="property">classmethod </em><tt class="descname">unwrap</tt><big>(</big><em>obj</em>, <em>fields=None</em><big>)</big><a class="headerlink" href="#mongoalchemy.document.Document.unwrap" title="Permalink to this definition">¶</a></dt>
+<em class="property">classmethod </em><tt class="descname">unwrap</tt><big>(</big><em>obj</em>, <em>fields=None</em>, <em>session=None</em><big>)</big><a class="headerlink" href="#mongoalchemy.document.Document.unwrap" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns an instance of this document class based on the mongo object
<tt class="docutils literal"><span class="pre">obj</span></tt>. This is done by using the <tt class="docutils literal"><span class="pre">unwrap()</span></tt> methods of the
underlying fields to set values.</p>
Oops, something went wrong.

0 comments on commit 885c5ee

Please sign in to comment.