docs

Author: timgraham

django_mongodb/queryset.py

@@ -13,6 +13,19 @@ def raw_aggregate(self, pipeline, using=None):
         return RawQuerySet(pipeline, model=self.model, using=using)
 
 
+class RawQuerySet(BaseRawQuerySet):
+    def __init__(self, pipeline, model=None, using=None):
+        super().__init__(pipeline, model=model, using=using)
+        self.query = RawQuery(pipeline, using=self.db, model=self.model)
+        # Override the superclass's columns property which relies on PEP 249's
+        # cursor.description. Instead, RawModelIterable will set the columns
+        # based on the keys in the first result.
+        self.columns = None
+
+    def iterator(self):
+        yield from RawModelIterable(self)
+
+
 class RawQuery(BaseRawQuery):
     def __init__(self, pipeline, using, model):
         self.pipeline = pipeline
@@ -28,24 +41,11 @@ def __str__(self):
         return str(self.pipeline)
 
 
-class RawQuerySet(BaseRawQuerySet):
-    def __init__(self, pipeline, model=None, using=None):
-        super().__init__(pipeline, model=model, using=using)
-        self.query = RawQuery(pipeline, using=self.db, model=self.model)
-        # Override the superclass's columns property which relies on PEP 249's
-        # cursor.description. Instead, RawModelIterable will set the columns
-        # based on the keys in the first result.
-        self.columns = None
-
-    def iterator(self):
-        yield from RawModelIterable(self)
-
-
 class RawModelIterable(BaseRawModelIterable):
     def __iter__(self):
         """
-        This is mostly copied from the superclass except for the part that sets
-        self.queryset.columns from the first document.
+        This is copied from the superclass except for the part that sets
+        self.queryset.columns from the first result.
         """
         db = self.queryset.db
         query = self.queryset.query
@@ -55,13 +55,13 @@ def __iter__(self):
         try:
             # Get the columns from the first result.
             try:
-                first_item = next(query_iterator)
+                first_result = next(query_iterator)
             except StopIteration:
                 # No results.
                 return
-            self.queryset.columns = list(first_item.keys())
+            self.queryset.columns = list(first_result.keys())
             # Reset the iterator to include the first item.
-            query_iterator = self._make_result(chain([first_item], query_iterator))
+            query_iterator = self._make_result(chain([first_result], query_iterator))
             (
                 model_init_names,
                 model_init_pos,
@@ -88,5 +88,9 @@ def __iter__(self):
             query.cursor.close()
 
     def _make_result(self, query):
+        """
+        Convert documents (dictionaries) to tuples as expected by the rest
+        of __iter__().
+        """
         for result in query:
-            yield list(result.values())
+            yield tuple(result.values())

docs/source/conf.py

@@ -17,11 +17,25 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = False
+
+extensions = [
+    "sphinx.ext.intersphinx",
+]
 
 # templates_path = ["_templates"]
 exclude_patterns = []
 
+intersphinx_mapping = {
+    "pymongo": ("https://pymongo.readthedocs.io/en/stable/", None),
+    "python": ("https://docs.python.org/3/", None),
+    "django": (
+        "https://docs.djangoproject.com/en/5.0/",
+        "http://docs.djangoproject.com/en/5.0/_objects/",
+    ),
+}
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

docs/source/index.rst

@@ -1,16 +1,11 @@
-.. django_mongodb documentation master file, created by
-   sphinx-quickstart on Mon Apr 15 12:38:26 2024.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root ``toctree`` directive.
-
 Welcome to django_mongodb's documentation!
 ==========================================
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Contents:
 
-
+   querysets
 
 Indices and tables
 ==================

docs/source/querysets.rst

@@ -0,0 +1,33 @@
+``QuerySet`` API reference
+==========================
+
+Some MongoDB-specific ``QuerySet`` methods are available by adding a custom
+:class:`~django.db.models.Manager`, ``MongoManager``, to your model::
+
+    from django.db import models
+
+    from django_mongodb.managers import MongoManager
+
+
+    class MyModel(models.Model):
+        ...
+
+        objects = MongoManager()
+
+
+.. currentmodule:: django_mongodb.queryset.MongoQuerySet
+
+``raw_aggregate()``
+-------------------
+
+.. method:: raw_aggregate(pipeline, using=None)
+
+Similar to :meth:`QuerySet.raw()<django.db.models.query.QuerySet.raw>`, but
+instead of a raw SQL query, this method accepts a pipeline that will be passed
+to :meth:`pymongo.collection.Collection.aggregate`. The pipeline must return
+the necessary fields to construct model instances and may also return
+additional fields that will be added as annotations on the models.
+
+For example, you could write a custom match criteria::
+
+    Post.objects.raw_aggregate([{"$match": {"title": "MongoDB is fun!"}}])