pub/mongoengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Documentation api and reference cleanups

Browse Source
This commit is contained in:
Ross Lawley 2013-04-26 08:46:46 +00:00
parent 13d8dfdb5f
commit 7765f272ac
10 changed files with 75 additions and 66 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/django.rst
View File

@ -98,7 +98,7 @@ Django provides session cookie, which expires after ```SESSION_COOKIE_AGE``` sec
Storage Storage
======= =======
With MongoEngine's support for GridFS via the :class:`~mongoengine.FileField`, With MongoEngine's support for GridFS via the :class:`~mongoengine.fields.FileField`,
it is useful to have a Django file storage backend that wraps this. The new it is useful to have a Django file storage backend that wraps this. The new
storage module is called :class:`~mongoengine.django.storage.GridFSStorage`. storage module is called :class:`~mongoengine.django.storage.GridFSStorage`.
Using it is very similar to using the default FileSystemStorage.:: Using it is very similar to using the default FileSystemStorage.::

82
docs/guide/defining-documents.rst
View File

@ -62,31 +62,31 @@ not provided. Default values may optionally be a callable, which will be called
to retrieve the value (such as in the above example). The field types available to retrieve the value (such as in the above example). The field types available
are as follows: are as follows:
* :class:`~mongoengine.BinaryField` * :class:`~mongoengine.fields.BinaryField`
* :class:`~mongoengine.BooleanField` * :class:`~mongoengine.fields.BooleanField`
* :class:`~mongoengine.ComplexDateTimeField` * :class:`~mongoengine.fields.ComplexDateTimeField`
* :class:`~mongoengine.DateTimeField` * :class:`~mongoengine.fields.DateTimeField`
* :class:`~mongoengine.DecimalField` * :class:`~mongoengine.fields.DecimalField`
* :class:`~mongoengine.DictField` * :class:`~mongoengine.fields.DictField`
* :class:`~mongoengine.DynamicField` * :class:`~mongoengine.fields.DynamicField`
* :class:`~mongoengine.EmailField` * :class:`~mongoengine.fields.EmailField`
* :class:`~mongoengine.EmbeddedDocumentField` * :class:`~mongoengine.fields.EmbeddedDocumentField`
* :class:`~mongoengine.FileField` * :class:`~mongoengine.fields.FileField`
* :class:`~mongoengine.FloatField` * :class:`~mongoengine.fields.FloatField`
* :class:`~mongoengine.GenericEmbeddedDocumentField` * :class:`~mongoengine.fields.GenericEmbeddedDocumentField`
* :class:`~mongoengine.GenericReferenceField` * :class:`~mongoengine.fields.GenericReferenceField`
* :class:`~mongoengine.GeoPointField` * :class:`~mongoengine.fields.GeoPointField`
* :class:`~mongoengine.ImageField` * :class:`~mongoengine.fields.ImageField`
* :class:`~mongoengine.IntField` * :class:`~mongoengine.fields.IntField`
* :class:`~mongoengine.ListField` * :class:`~mongoengine.fields.ListField`
* :class:`~mongoengine.MapField` * :class:`~mongoengine.fields.MapField`
* :class:`~mongoengine.ObjectIdField` * :class:`~mongoengine.fields.ObjectIdField`
* :class:`~mongoengine.ReferenceField` * :class:`~mongoengine.fields.ReferenceField`
* :class:`~mongoengine.SequenceField` * :class:`~mongoengine.fields.SequenceField`
* :class:`~mongoengine.SortedListField` * :class:`~mongoengine.fields.SortedListField`
* :class:`~mongoengine.StringField` * :class:`~mongoengine.fields.StringField`
* :class:`~mongoengine.URLField` * :class:`~mongoengine.fields.URLField`
* :class:`~mongoengine.UUIDField` * :class:`~mongoengine.fields.UUIDField`
Field arguments Field arguments
--------------- ---------------
@ -110,7 +110,7 @@ arguments can be set on all fields:
The definion of default parameters follow `the general rules on Python The definion of default parameters follow `the general rules on Python
<http://docs.python.org/reference/compound_stmts.html#function-definitions>`__, <http://docs.python.org/reference/compound_stmts.html#function-definitions>`__,
which means that some care should be taken when dealing with default mutable objects which means that some care should be taken when dealing with default mutable objects
(like in :class:`~mongoengine.ListField` or :class:`~mongoengine.DictField`):: (like in :class:`~mongoengine.fields.ListField` or :class:`~mongoengine.fields.DictField`)::
class ExampleFirst(Document): class ExampleFirst(Document):
# Default an empty list # Default an empty list
@ -172,8 +172,8 @@ arguments can be set on all fields:
List fields List fields
----------- -----------
MongoDB allows the storage of lists of items. To add a list of items to a MongoDB allows the storage of lists of items. To add a list of items to a
:class:`~mongoengine.Document`, use the :class:`~mongoengine.ListField` field :class:`~mongoengine.Document`, use the :class:`~mongoengine.fields.ListField` field
type. :class:`~mongoengine.ListField` takes another field object as its first type. :class:`~mongoengine.fields.ListField` takes another field object as its first
argument, which specifies which type elements may be stored within the list:: argument, which specifies which type elements may be stored within the list::
class Page(Document): class Page(Document):
@ -191,7 +191,7 @@ inherit from :class:`~mongoengine.EmbeddedDocument` rather than
content = StringField() content = StringField()
To embed the document within another document, use the To embed the document within another document, use the
:class:`~mongoengine.EmbeddedDocumentField` field type, providing the embedded :class:`~mongoengine.fields.EmbeddedDocumentField` field type, providing the embedded
document class as the first argument:: document class as the first argument::
class Page(Document): class Page(Document):
@ -206,7 +206,7 @@ Dictionary Fields
Often, an embedded document may be used instead of a dictionary -- generally Often, an embedded document may be used instead of a dictionary -- generally
this is recommended as dictionaries don't support validation or custom field this is recommended as dictionaries don't support validation or custom field
types. However, sometimes you will not know the structure of what you want to types. However, sometimes you will not know the structure of what you want to
store; in this situation a :class:`~mongoengine.DictField` is appropriate:: store; in this situation a :class:`~mongoengine.fields.DictField` is appropriate::
class SurveyResponse(Document): class SurveyResponse(Document):
date = DateTimeField() date = DateTimeField()
@ -224,7 +224,7 @@ other objects, so are the most flexible field type available.
Reference fields Reference fields
---------------- ----------------
References may be stored to other documents in the database using the References may be stored to other documents in the database using the
:class:`~mongoengine.ReferenceField`. Pass in another document class as the :class:`~mongoengine.fields.ReferenceField`. Pass in another document class as the
first argument to the constructor, then simply assign document objects to the first argument to the constructor, then simply assign document objects to the
field:: field::
@ -245,9 +245,9 @@ field::
The :class:`User` object is automatically turned into a reference behind the The :class:`User` object is automatically turned into a reference behind the
scenes, and dereferenced when the :class:`Page` object is retrieved. scenes, and dereferenced when the :class:`Page` object is retrieved.
To add a :class:`~mongoengine.ReferenceField` that references the document To add a :class:`~mongoengine.fields.ReferenceField` that references the document
being defined, use the string ``'self'`` in place of the document class as the being defined, use the string ``'self'`` in place of the document class as the
argument to :class:`~mongoengine.ReferenceField`'s constructor. To reference a argument to :class:`~mongoengine.fields.ReferenceField`'s constructor. To reference a
document that has not yet been defined, use the name of the undefined document document that has not yet been defined, use the name of the undefined document
as the constructor's argument:: as the constructor's argument::
@ -325,7 +325,7 @@ Its value can take any of the following constants:
:const:`mongoengine.PULL` :const:`mongoengine.PULL`
Removes the reference to the object (using MongoDB's "pull" operation) Removes the reference to the object (using MongoDB's "pull" operation)
from any object's fields of from any object's fields of
:class:`~mongoengine.ListField` (:class:`~mongoengine.ReferenceField`). :class:`~mongoengine.fields.ListField` (:class:`~mongoengine.fields.ReferenceField`).
.. warning:: .. warning::
@ -352,7 +352,7 @@ Its value can take any of the following constants:
Generic reference fields Generic reference fields
'''''''''''''''''''''''' ''''''''''''''''''''''''
A second kind of reference field also exists, A second kind of reference field also exists,
:class:`~mongoengine.GenericReferenceField`. This allows you to reference any :class:`~mongoengine.fields.GenericReferenceField`. This allows you to reference any
kind of :class:`~mongoengine.Document`, and hence doesn't take a kind of :class:`~mongoengine.Document`, and hence doesn't take a
:class:`~mongoengine.Document` subclass as a constructor argument:: :class:`~mongoengine.Document` subclass as a constructor argument::
@ -376,15 +376,15 @@ kind of :class:`~mongoengine.Document`, and hence doesn't take a
.. note:: .. note::
Using :class:`~mongoengine.GenericReferenceField`\ s is slightly less Using :class:`~mongoengine.fields.GenericReferenceField`\ s is slightly less
efficient than the standard :class:`~mongoengine.ReferenceField`\ s, so if efficient than the standard :class:`~mongoengine.fields.ReferenceField`\ s, so if
you will only be referencing one document type, prefer the standard you will only be referencing one document type, prefer the standard
:class:`~mongoengine.ReferenceField`. :class:`~mongoengine.fields.ReferenceField`.
Uniqueness constraints Uniqueness constraints
---------------------- ----------------------
MongoEngine allows you to specify that a field should be unique across a MongoEngine allows you to specify that a field should be unique across a
collection by providing ``unique=True`` to a :class:`~mongoengine.Field`\ 's collection by providing ``unique=True`` to a :class:`~mongoengine.fields.Field`\ 's
constructor. If you try to save a document that has the same value for a unique constructor. If you try to save a document that has the same value for a unique
field as a document that is already in the database, a field as a document that is already in the database, a
:class:`~mongoengine.OperationError` will be raised. You may also specify :class:`~mongoengine.OperationError` will be raised. You may also specify
@ -492,11 +492,11 @@ Geospatial indexes
------------------ ------------------
Geospatial indexes will be automatically created for all Geospatial indexes will be automatically created for all
:class:`~mongoengine.GeoPointField`\ s :class:`~mongoengine.fields.GeoPointField`\ s
It is also possible to explicitly define geospatial indexes. This is It is also possible to explicitly define geospatial indexes. This is
useful if you need to define a geospatial index on a subfield of a useful if you need to define a geospatial index on a subfield of a
:class:`~mongoengine.DictField` or a custom field that contains a :class:`~mongoengine.fields.DictField` or a custom field that contains a
point. To create a geospatial index you must prefix the field with the point. To create a geospatial index you must prefix the field with the
***** sign. :: ***** sign. ::

4
docs/guide/document-instances.rst
View File

@ -68,8 +68,8 @@ document values for example::
Cascading Saves Cascading Saves
--------------- ---------------
If your document contains :class:`~mongoengine.ReferenceField` or If your document contains :class:`~mongoengine.fields.ReferenceField` or
:class:`~mongoengine.GenericReferenceField` objects, then by default the :class:`~mongoengine.fields.GenericReferenceField` objects, then by default the
:meth:`~mongoengine.Document.save` method will automatically save any changes to :meth:`~mongoengine.Document.save` method will automatically save any changes to
those objects as well. If this is not desired passing :attr:`cascade` as False those objects as well. If this is not desired passing :attr:`cascade` as False
to the save method turns this feature off. to the save method turns this feature off.

6
docs/guide/gridfs.rst
View File

@ -7,7 +7,7 @@ GridFS
Writing Writing
------- -------
GridFS support comes in the form of the :class:`~mongoengine.FileField` field GridFS support comes in the form of the :class:`~mongoengine.fields.FileField` field
object. This field acts as a file-like object and provides a couple of object. This field acts as a file-like object and provides a couple of
different ways of inserting and retrieving data. Arbitrary metadata such as different ways of inserting and retrieving data. Arbitrary metadata such as
content type can also be stored alongside the files. In the following example, content type can also be stored alongside the files. In the following example,
@ -27,7 +27,7 @@ a document is created to store details about animals, including a photo::
Retrieval Retrieval
--------- ---------
So using the :class:`~mongoengine.FileField` is just like using any other So using the :class:`~mongoengine.fields.FileField` is just like using any other
field. The file can also be retrieved just as easily:: field. The file can also be retrieved just as easily::
marmot = Animal.objects(genus='Marmota').first() marmot = Animal.objects(genus='Marmota').first()
@ -37,7 +37,7 @@ field. The file can also be retrieved just as easily::
Streaming Streaming
--------- ---------
Streaming data into a :class:`~mongoengine.FileField` is achieved in a Streaming data into a :class:`~mongoengine.fields.FileField` is achieved in a
slightly different manner. First, a new file must be created by calling the slightly different manner. First, a new file must be created by calling the
:func:`new_file` method. Data can then be written using :func:`write`:: :func:`new_file` method. Data can then be written using :func:`write`::

16
docs/guide/querying.rst
View File

@ -79,7 +79,7 @@ expressions:
* ``match`` -- performs an $elemMatch so you can match an entire document within an array * ``match`` -- performs an $elemMatch so you can match an entire document within an array
There are a few special operators for performing geographical queries, that There are a few special operators for performing geographical queries, that
may used with :class:`~mongoengine.GeoPointField`\ s: may used with :class:`~mongoengine.fields.GeoPointField`\ s:
* ``within_distance`` -- provide a list containing a point and a maximum * ``within_distance`` -- provide a list containing a point and a maximum
distance (e.g. [(41.342, -87.653), 5]) distance (e.g. [(41.342, -87.653), 5])
@ -100,7 +100,7 @@ Querying lists
-------------- --------------
On most fields, this syntax will look up documents where the field specified On most fields, this syntax will look up documents where the field specified
matches the given value exactly, but when the field refers to a matches the given value exactly, but when the field refers to a
:class:`~mongoengine.ListField`, a single item may be provided, in which case :class:`~mongoengine.fields.ListField`, a single item may be provided, in which case
lists that contain that item will be matched:: lists that contain that item will be matched::
class Page(Document): class Page(Document):
@ -319,7 +319,7 @@ Retrieving a subset of fields
Sometimes a subset of fields on a :class:`~mongoengine.Document` is required, Sometimes a subset of fields on a :class:`~mongoengine.Document` is required,
and for efficiency only these should be retrieved from the database. This issue and for efficiency only these should be retrieved from the database. This issue
is especially important for MongoDB, as fields may often be extremely large is especially important for MongoDB, as fields may often be extremely large
(e.g. a :class:`~mongoengine.ListField` of (e.g. a :class:`~mongoengine.fields.ListField` of
:class:`~mongoengine.EmbeddedDocument`\ s, which represent the comments on a :class:`~mongoengine.EmbeddedDocument`\ s, which represent the comments on a
blog post. To select only a subset of fields, use blog post. To select only a subset of fields, use
:meth:`~mongoengine.queryset.QuerySet.only`, specifying the fields you want to :meth:`~mongoengine.queryset.QuerySet.only`, specifying the fields you want to
@ -351,14 +351,14 @@ If you later need the missing fields, just call
Getting related data Getting related data
-------------------- --------------------
When iterating the results of :class:`~mongoengine.ListField` or When iterating the results of :class:`~mongoengine.fields.ListField` or
:class:`~mongoengine.DictField` we automatically dereference any :class:`~mongoengine.fields.DictField` we automatically dereference any
:class:`~pymongo.dbref.DBRef` objects as efficiently as possible, reducing the :class:`~pymongo.dbref.DBRef` objects as efficiently as possible, reducing the
number the queries to mongo. number the queries to mongo.
There are times when that efficiency is not enough, documents that have There are times when that efficiency is not enough, documents that have
:class:`~mongoengine.ReferenceField` objects or :class:`~mongoengine.fields.ReferenceField` objects or
:class:`~mongoengine.GenericReferenceField` objects at the top level are :class:`~mongoengine.fields.GenericReferenceField` objects at the top level are
expensive as the number of queries to MongoDB can quickly rise. expensive as the number of queries to MongoDB can quickly rise.
To limit the number of queries use To limit the number of queries use
@ -541,7 +541,7 @@ Javascript code. When accessing a field on a collection object, use
square-bracket notation, and prefix the MongoEngine field name with a tilde. square-bracket notation, and prefix the MongoEngine field name with a tilde.
The field name that follows the tilde will be translated to the name used in The field name that follows the tilde will be translated to the name used in
the database. Note that when referring to fields on embedded documents, the database. Note that when referring to fields on embedded documents,
the name of the :class:`~mongoengine.EmbeddedDocumentField`, followed by a dot, the name of the :class:`~mongoengine.fields.EmbeddedDocumentField`, followed by a dot,
should be used before the name of the field on the embedded document. The should be used before the name of the field on the embedded document. The
following example shows how the substitutions are made:: following example shows how the substitutions are made::

8
docs/tutorial.rst
View File

@ -115,7 +115,7 @@ by setting :attr:`allow_inheritance` to True in the :attr:`meta`::
link_url = StringField() link_url = StringField()
We are storing a reference to the author of the posts using a We are storing a reference to the author of the posts using a
:class:`~mongoengine.ReferenceField` object. These are similar to foreign key :class:`~mongoengine.fields.ReferenceField` object. These are similar to foreign key
fields in traditional ORMs, and are automatically translated into references fields in traditional ORMs, and are automatically translated into references
when they are saved, and dereferenced when they are loaded. when they are saved, and dereferenced when they are loaded.
@ -137,7 +137,7 @@ size of our database. So let's take a look that the code our modified
author = ReferenceField(User) author = ReferenceField(User)
tags = ListField(StringField(max_length=30)) tags = ListField(StringField(max_length=30))
The :class:`~mongoengine.ListField` object that is used to define a Post's tags The :class:`~mongoengine.fields.ListField` object that is used to define a Post's tags
takes a field object as its first argument --- this means that you can have takes a field object as its first argument --- this means that you can have
lists of any type of field (including lists). lists of any type of field (including lists).
@ -174,7 +174,7 @@ We can then store a list of comment documents in our post document::
Handling deletions of references Handling deletions of references
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The :class:`~mongoengine.ReferenceField` object takes a keyword The :class:`~mongoengine.fields.ReferenceField` object takes a keyword
`reverse_delete_rule` for handling deletion rules if the reference is deleted. `reverse_delete_rule` for handling deletion rules if the reference is deleted.
To delete all the posts if a user is deleted set the rule:: To delete all the posts if a user is deleted set the rule::
@ -184,7 +184,7 @@ To delete all the posts if a user is deleted set the rule::
tags = ListField(StringField(max_length=30)) tags = ListField(StringField(max_length=30))
comments = ListField(EmbeddedDocumentField(Comment)) comments = ListField(EmbeddedDocumentField(Comment))
See :class:`~mongoengine.ReferenceField` for more information. See :class:`~mongoengine.fields.ReferenceField` for more information.
.. note:: .. note::
MapFields and DictFields currently don't support automatic handling of MapFields and DictFields currently don't support automatic handling of

11
docs/upgrade.rst
View File

@ -120,6 +120,9 @@ eg::
p._mark_as_dirty('friends') p._mark_as_dirty('friends')
p.save() p.save()
`An example test migration is available on github
<https://github.com/MongoEngine/mongoengine/blob/master/tests/migration/refrencefield_dbref_to_object_id.py>`_.
UUIDField UUIDField
--------- ---------
@ -145,6 +148,9 @@ eg::
a._mark_as_dirty('uuid') a._mark_as_dirty('uuid')
a.save() a.save()
`An example test migration is available on github
<https://github.com/MongoEngine/mongoengine/blob/master/tests/migration/uuidfield_to_binary.py>`_.
DecimalField DecimalField
------------ ------------
@ -172,7 +178,10 @@ eg::
p.save() p.save()
.. note:: DecimalField's have also been improved with the addition of precision .. note:: DecimalField's have also been improved with the addition of precision
and rounding. See :class:`~mongoengine.DecimalField` for more information. and rounding. See :class:`~mongoengine.fields.DecimalField` for more information.
`An example test migration is available on github
<https://github.com/MongoEngine/mongoengine/blob/master/tests/migration/decimalfield_as_float.py>`_.
Cascading Saves Cascading Saves
--------------- ---------------

2
mongoengine/document.py
View File

@ -559,7 +559,7 @@ class DynamicDocument(Document):
way as an ordinary document but has expando style properties. Any data way as an ordinary document but has expando style properties. Any data
passed or set against the :class:`~mongoengine.DynamicDocument` that is passed or set against the :class:`~mongoengine.DynamicDocument` that is
not a field is automatically converted into a not a field is automatically converted into a
:class:`~mongoengine.DynamicField` and data can be attributed to that :class:`~mongoengine.fields.DynamicField` and data can be attributed to that
field. field.
.. note:: .. note::

2
mongoengine/fields.py
View File

@ -782,7 +782,7 @@ class ReferenceField(BaseField):
* NULLIFY - Updates the reference to null. * NULLIFY - Updates the reference to null.
* CASCADE - Deletes the documents associated with the reference. * CASCADE - Deletes the documents associated with the reference.
* DENY - Prevent the deletion of the reference object. * DENY - Prevent the deletion of the reference object.
* PULL - Pull the reference from a :class:`~mongoengine.ListField` * PULL - Pull the reference from a :class:`~mongoengine.fields.ListField`
of references of references
Alternative syntax for registering delete rules (useful when implementing Alternative syntax for registering delete rules (useful when implementing

6
mongoengine/queryset/queryset.py
View File

@ -1062,11 +1062,11 @@ class QuerySet(object):
.. note:: .. note::
Can only do direct simple mappings and cannot map across Can only do direct simple mappings and cannot map across
:class:`~mongoengine.ReferenceField` or :class:`~mongoengine.fields.ReferenceField` or
:class:`~mongoengine.GenericReferenceField` for more complex :class:`~mongoengine.fields.GenericReferenceField` for more complex
counting a manual map reduce call would is required. counting a manual map reduce call would is required.
If the field is a :class:`~mongoengine.ListField`, the items within If the field is a :class:`~mongoengine.fields.ListField`, the items within
each list will be counted individually. each list will be counted individually.
:param field: the field to use :param field: the field to use