diff --git a/docs/apireference.rst b/docs/apireference.rst index 4fff317a..34d4536d 100644 --- a/docs/apireference.rst +++ b/docs/apireference.rst @@ -66,3 +66,5 @@ Fields .. autoclass:: mongoengine.GenericReferenceField .. autoclass:: mongoengine.FileField + +.. autoclass:: mongoengine.GeoPointField diff --git a/docs/changelog.rst b/docs/changelog.rst index 8dd5b00d..64bdf90a 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -4,16 +4,25 @@ Changelog Changes in v0.4 =============== +- New Q-object implementation, which is no longer based on Javascript - Added ``SortedListField`` - Added ``EmailField`` - Added ``GeoPointField`` - Added ``exact`` and ``iexact`` match operators to ``QuerySet`` - Added ``get_document_or_404`` and ``get_list_or_404`` Django shortcuts -- Fixed bug in Q-objects +- Added new query operators for Geo queries +- Added ``not`` query operator +- Added new update operators: ``pop`` and ``add_to_set`` +- Added ``__raw__`` query parameter - Fixed document inheritance primary key issue +- Added support for querying by array element position - Base class can now be defined for ``DictField`` - Fixed MRO error that occured on document inheritance +- Added ``QuerySet.distinct``, ``QuerySet.create``, ``QuerySet.snapshot``, + ``QuerySet.timeout`` and ``QuerySet.all`` +- Subsequent calls to ``connect()`` now work - Introduced ``min_length`` for ``StringField`` +- Fixed multi-process connection issue - Other minor fixes Changes in v0.3 diff --git a/docs/guide/defining-documents.rst b/docs/guide/defining-documents.rst index dc136f27..106d4ec8 100644 --- a/docs/guide/defining-documents.rst +++ b/docs/guide/defining-documents.rst @@ -47,11 +47,11 @@ are as follows: * :class:`~mongoengine.ReferenceField` * :class:`~mongoengine.GenericReferenceField` * :class:`~mongoengine.BooleanField` -* :class:`~mongoengine.GeoLocationField` * :class:`~mongoengine.FileField` * :class:`~mongoengine.EmailField` * :class:`~mongoengine.SortedListField` * :class:`~mongoengine.BinaryField` +* :class:`~mongoengine.GeoPointField` Field arguments --------------- @@ -298,6 +298,10 @@ or a **-** sign. Note that direction only matters on multi-field indexes. :: meta = { 'indexes': ['title', ('title', '-rating')] } + +.. note:: + Geospatial indexes will be automatically created for all + :class:`~mongoengine.GeoPointField`\ s Ordering ======== diff --git a/docs/guide/querying.rst b/docs/guide/querying.rst index bef19bc5..58bf9f63 100644 --- a/docs/guide/querying.rst +++ b/docs/guide/querying.rst @@ -53,6 +53,16 @@ lists that contain that item will be matched:: # 'tags' list Page.objects(tags='coding') +Raw queries +----------- +It is possible to provide a raw PyMongo query as a query parameter, which will +be integrated directly into the query. This is done using the ``__raw__`` +keyword argument:: + + Page.objects(__raw__={'tags': 'coding'}) + +.. versionadded:: 0.4 + Query operators =============== Operators other than equality may also be used in queries; just attach the @@ -68,6 +78,8 @@ Available operators are as follows: * ``lte`` -- less than or equal to * ``gt`` -- greater than * ``gte`` -- greater than or equal to +* ``not`` -- negate a standard check, may be used before other operators (e.g. + ``Q(age__not__mod=5)``) * ``in`` -- value is in list (a list of values should be provided) * ``nin`` -- value is not in list (a list of values should be provided) * ``mod`` -- ``value % x == y``, where ``x`` and ``y`` are two provided values @@ -89,6 +101,27 @@ expressions: .. versionadded:: 0.3 +There are a few special operators for performing geographical queries, that +may used with :class:`~mongoengine.GeoPointField`\ s: + +* ``within_distance`` -- provide a list containing a point and a maximum + distance (e.g. [(41.342, -87.653), 5]) +* ``within_box`` -- filter documents to those within a given bounding box (e.g. + [(35.0, -125.0), (40.0, -100.0)]) +* ``near`` -- order the documents by how close they are to a given point + +.. versionadded:: 0.4 + +Querying by position +==================== +It is possible to query by position in a list by using a numerical value as a +query operator. So if you wanted to find all pages whose first tag was ``db``, +you could use the following query:: + + BlogPost.objects(tags__0='db') + +.. versionadded:: 0.4 + Limiting and skipping results ============================= Just as with traditional ORMs, you may limit the number of results returned, or @@ -181,6 +214,22 @@ custom manager methods as you like:: assert len(BlogPost.objects) == 2 assert len(BlogPost.live_posts) == 1 +Custom QuerySets +================ +Should you want to add custom methods for interacting with or filtering +documents, extending the :class:`~mongoengine.queryset.QuerySet` class may be +the way to go. To use a custom :class:`~mongoengine.queryset.QuerySet` class on +a document, set ``queryset_class`` to the custom class in a +:class:`~mongoengine.Document`\ s ``meta`` dictionary:: + + class AwesomerQuerySet(QuerySet): + pass + + class Page(Document): + meta = {'queryset_class': AwesomerQuerySet} + +.. versionadded:: 0.4 + Aggregation =========== MongoDB provides some aggregation methods out of the box, but there are not as @@ -402,8 +451,10 @@ that you may use with these methods: * ``pop`` -- remove the last item from a list * ``push`` -- append a value to a list * ``push_all`` -- append several values to a list +* ``pop`` -- remove the first or last element of a list * ``pull`` -- remove a value from a list * ``pull_all`` -- remove several values from a list +* ``add_to_set`` -- add value to a list only if its not in the list already The syntax for atomic updates is similar to the querying syntax, but the modifier comes before the field, not after it:: diff --git a/docs/index.rst b/docs/index.rst index a28b344c..ccb7fbe2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -7,7 +7,7 @@ MongoDB. To install it, simply run .. code-block:: console - # easy_install -U mongoengine + # pip install -U mongoengine The source is available on `GitHub `_. diff --git a/mongoengine/fields.py b/mongoengine/fields.py index 9fc50d68..62d2ef2f 100644 --- a/mongoengine/fields.py +++ b/mongoengine/fields.py @@ -112,6 +112,8 @@ class URLField(StringField): class EmailField(StringField): """A field that validates input as an E-Mail-Address. + + .. versionadded:: 0.4 """ EMAIL_REGEX = re.compile( @@ -355,6 +357,8 @@ class SortedListField(ListField): """A ListField that sorts the contents of its list before writing to the database in order to ensure that a sorted list is always retrieved. + + .. versionadded:: 0.4 """ _ordering = None @@ -666,6 +670,8 @@ class FileField(BaseField): class GeoPointField(BaseField): """A list storing a latitude and longitude. + + .. versionadded:: 0.4 """ _geo_index = True diff --git a/mongoengine/queryset.py b/mongoengine/queryset.py index f6296dd2..86f8b1d5 100644 --- a/mongoengine/queryset.py +++ b/mongoengine/queryset.py @@ -590,6 +590,7 @@ class QuerySet(object): def create(self, **kwargs): """Create new object. Returns the saved object instance. + .. versionadded:: 0.4 """ doc = self._document(**kwargs)