diff --git a/docs/source/conf.py b/docs/source/conf.py index 9b9f84e0..a4e54938 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -41,7 +41,7 @@ "https://docs.djangoproject.com/en/5.2/", "https://docs.djangoproject.com/en/5.2/_objects/", ), - "mongodb": ("https://www.mongodb.com/docs/languages/python/django-mongodb/v5.1/", None), + "mongodb": ("https://www.mongodb.com/docs/languages/python/django-mongodb/v5.2/", None), "pymongo": ("https://pymongo.readthedocs.io/en/stable/", None), "python": ("https://docs.python.org/3/", None), "atlas": ("https://www.mongodb.com/docs/atlas/", None), diff --git a/docs/source/ref/django-admin.rst b/docs/source/ref/django-admin.rst index 34e7a45b..93f90f9f 100644 --- a/docs/source/ref/django-admin.rst +++ b/docs/source/ref/django-admin.rst @@ -19,10 +19,10 @@ Available commands .. django-admin:: createcachecollection -Creates the cache collection for use with the :doc:`database cache backend -` using the information from your :setting:`CACHES` setting. + Creates the cache collection for use with the :doc:`database cache backend + ` using the information from your :setting:`CACHES` setting. -.. django-admin-option:: --database DATABASE + .. django-admin-option:: --database DATABASE -Specifies the database in which the cache collection(s) will be created. -Defaults to ``default``. + Specifies the database in which the cache collection(s) will be created. + Defaults to ``default``. diff --git a/docs/source/ref/forms.rst b/docs/source/ref/forms.rst index 934af20e..74ef26f9 100644 --- a/docs/source/ref/forms.rst +++ b/docs/source/ref/forms.rst @@ -28,7 +28,7 @@ Some MongoDB-specific fields are available in ``django_mongodb_backend.forms``. .. class:: ObjectIdField -Stores an :class:`~bson.objectid.ObjectId`. + Stores an :class:`~bson.objectid.ObjectId`. ``SimpleArrayField`` -------------------- diff --git a/docs/source/ref/models/fields.rst b/docs/source/ref/models/fields.rst index 56c0902c..be9ff6dd 100644 --- a/docs/source/ref/models/fields.rst +++ b/docs/source/ref/models/fields.rst @@ -176,9 +176,9 @@ Index transforms ^^^^^^^^^^^^^^^^ Index transforms index into the array. Any non-negative integer can be used. -There are no errors if it exceeds the :attr:`max_size ` of -the array. The lookups available after the transform are those from the -:attr:`base_field `. For example: +There are no errors if it exceeds the :attr:`~ArrayField.max_size` of the +array. The lookups available after the transform are those from the +:attr:`~ArrayField.base_field`. For example: .. code-block:: pycon @@ -224,7 +224,7 @@ These indexes use 0-based indexing. .. class:: EmbeddedModelField(embedded_model, **kwargs) -Stores a model of type ``embedded_model``. + Stores a model of type ``embedded_model``. .. attribute:: embedded_model @@ -256,7 +256,7 @@ Stores a model of type ``embedded_model``. class Book(models.Model): author = EmbeddedModelField(Author) -See :doc:`/topics/embedded-models` for more details and examples. + See :doc:`/topics/embedded-models` for more details and examples. .. admonition:: Migrations support is limited @@ -273,12 +273,12 @@ See :doc:`/topics/embedded-models` for more details and examples. .. class:: ObjectIdAutoField -This field is typically the default primary key field for all models stored in -MongoDB. See :ref:`specifying the-default-pk-field`. + This field is typically the default primary key field for all models stored + in MongoDB. See :ref:`specifying the-default-pk-field`. ``ObjectIdField`` ----------------- .. class:: ObjectIdField -Stores an :class:`~bson.objectid.ObjectId`. + Stores an :class:`~bson.objectid.ObjectId`. diff --git a/docs/source/ref/models/indexes.rst b/docs/source/ref/models/indexes.rst index cae18fd1..5662d3ef 100644 --- a/docs/source/ref/models/indexes.rst +++ b/docs/source/ref/models/indexes.rst @@ -14,42 +14,43 @@ available in ``django_mongodb_backend.indexes``. .. class:: SearchIndex(fields=(), name=None) -.. versionadded:: 5.2.0b0 + .. versionadded:: 5.2.0b0 -Creates a basic :doc:`search index ` on -the given field(s). + Creates a basic :doc:`search index ` + on the given field(s). -Some fields such as :class:`~django.db.models.DecimalField` aren't -supported. See the :ref:`Atlas documentation ` for a -complete list of unsupported data types. + Some fields such as :class:`~django.db.models.DecimalField` aren't + supported. See the :ref:`Atlas documentation ` for a + complete list of unsupported data types. -If ``name`` isn't provided, one will be generated automatically. If you need -to reference the name in your search query and don't provide your own name, -you can lookup the generated one using ``Model._meta.indexes[0].name`` -(substiting the name of your model as well as a different list index if your -model has multiple indexes). + If ``name`` isn't provided, one will be generated automatically. If you + need to reference the name in your search query and don't provide your own + name, you can lookup the generated one using ``Model._meta.indexes[0].name`` + (substituting the name of your model as well as a different list index if + your model has multiple indexes). ``VectorSearchIndex`` ===================== .. class:: VectorSearchIndex(*, fields=(), name=None, similarities) -.. versionadded:: 5.2.0b0 + .. versionadded:: 5.2.0b0 -A subclass of :class:`SearchIndex` that creates a :doc:`vector search index -` on the given field(s). + A subclass of :class:`SearchIndex` that creates a :doc:`vector search index + ` on the given field(s). -The index must reference at least one vector field: an :class:`.ArrayField` -with a :attr:`~.ArrayField.base_field` of :class:`~django.db.models.FloatField` -or :class:`~django.db.models.IntegerField` and a :attr:`~.ArrayField.size`. It -cannot reference an :class:`.ArrayField` of any other type. + The index must reference at least one vector field: an :class:`.ArrayField` + with a :attr:`~.ArrayField.base_field` of + :class:`~django.db.models.FloatField` or + :class:`~django.db.models.IntegerField` and a :attr:`~.ArrayField.size`. It + cannot reference an :class:`.ArrayField` of any other type. -It may also have other fields to filter on, provided the field stores -``boolean``, ``date``, ``objectId``, ``numeric``, ``string``, or ``uuid``. + It may also have other fields to filter on, provided the field stores + ``boolean``, ``date``, ``objectId``, ``numeric``, ``string``, or ``uuid``. -Available values for the required ``similarities`` keyword argument are -``"cosine"``, ``"dotProduct"``, and ``"euclidean"`` (see -:ref:`atlas:avs-similarity-functions` for how to choose). You can provide this -value either a string, in which case that value will be applied to all vector -fields, or a list or tuple of values with a similarity corresponding to each -vector field. + Available values for the required ``similarities`` keyword argument are + ``"cosine"``, ``"dotProduct"``, and ``"euclidean"`` (see + :ref:`atlas:avs-similarity-functions` for how to choose). You can provide + this value either a string, in which case that value will be applied to all + vector fields, or a list or tuple of values with a similarity corresponding + to each vector field. diff --git a/docs/source/ref/models/models.rst b/docs/source/ref/models/models.rst index b85505bd..a4491228 100644 --- a/docs/source/ref/models/models.rst +++ b/docs/source/ref/models/models.rst @@ -7,9 +7,10 @@ One MongoDB-specific model is available in ``django_mongodb_backend.models``. .. class:: EmbeddedModel -An abstract model which all :doc:`embedded models ` -must subclass. + An abstract model which all :doc:`embedded models ` + must subclass. -Since these models are not stored in their own collection, they do not have -any of the normal ``QuerySet`` methods (``all()``, ``filter()``, ``delete()``, -etc.) You also cannot call ``Model.save()`` and ``delete()`` on them. + Since these models are not stored in their own collection, they do not have + any of the normal ``QuerySet`` methods (``all()``, ``filter()``, + ``delete()``, etc.) You also cannot call ``Model.save()`` and ``delete()`` + on them. diff --git a/docs/source/ref/models/querysets.rst b/docs/source/ref/models/querysets.rst index 601e79d1..c789d24d 100644 --- a/docs/source/ref/models/querysets.rst +++ b/docs/source/ref/models/querysets.rst @@ -18,34 +18,34 @@ queries that span multiple collections. ``QuerySet.explain()`` ====================== -- :meth:`QuerySet.explain() ` supports - the `comment and verbosity options - `_. +:meth:`QuerySet.explain() ` supports +the `comment and verbosity options +`_. - Example:: +Example:: - Model.objects.explain(comment="...", verbosity="...") + Model.objects.explain(comment="...", verbosity="...") - Valid values for ``verbosity`` are ``"queryPlanner"`` (default), - ``"executionStats"``, and ``"allPlansExecution"``. +Valid values for ``verbosity`` are ``"queryPlanner"`` (default), +``"executionStats"``, and ``"allPlansExecution"``. MongoDB-specific ``QuerySet`` methods ===================================== .. class:: django_mongodb_backend.managers.MongoManager -Some MongoDB-specific ``QuerySet`` methods are available by adding a custom -:class:`~django.db.models.Manager`, ``MongoManager``, to your model:: + 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.db import models - from django_mongodb_backend.managers import MongoManager + from django_mongodb_backend.managers import MongoManager - class MyModel(models.Model): - ... + class MyModel(models.Model): + ... - objects = MongoManager() + objects = MongoManager() .. currentmodule:: django_mongodb_backend.queryset.MongoQuerySet @@ -55,48 +55,48 @@ Some MongoDB-specific ``QuerySet`` methods are available by adding a custom .. method:: raw_aggregate(pipeline, using=None) -Similar to :meth:`QuerySet.raw()`, but -instead of a raw SQL query, this method accepts a pipeline that will be passed -to :meth:`pymongo.collection.Collection.aggregate`. - -For example, you could write a custom match criteria:: - - Question.objects.raw_aggregate([{"$match": {"question_text": "What's up"}}]) - -The pipeline may also return additional fields that will be added as -annotations on the models:: - - >>> questions = Question.objects.raw_aggregate([{ - ... "$project": { - ... "question_text": 1, - ... "pub_date": 1, - ... "year_published": {"$year": "$pub_date"} - ... } - ... }]) - >>> for q in questions: - ... print(f"{q.question_text} was published in {q.year_published}.") - ... - What's up? was published in 2024. - -Fields may also be left out: - - >>> Question.objects.raw_aggregate([{"$project": {"question_text": 1}}]) - -The ``Question`` objects returned by this query will be deferred model instances -(see :meth:`~django.db.models.query.QuerySet.defer()`). This means that the -fields that are omitted from the query will be loaded on demand. For example:: - - >>> for q in Question.objects.raw_aggregate([{"$project": {"question_text": 1}}]): - >>> print( - ... q.question_text, # This will be retrieved by the original query. - ... q.pub_date, # This will be retrieved on demand. - ... ) - ... - What's new 2023-09-03 12:00:00+00:00 - What's up 2024-08-23 20:57:30+00:00 - -From outward appearances, this looks like the query has retrieved both the -question text and published date. However, this example actually issued three -queries. Only the question texts were retrieved by the ``raw_aggregate()`` -query -- the published dates were both retrieved on demand when they were -printed. + Similar to :meth:`QuerySet.raw()`, but + instead of a raw SQL query, this method accepts a pipeline that will be passed + to :meth:`pymongo.collection.Collection.aggregate`. + + For example, you could write a custom match criteria:: + + Question.objects.raw_aggregate([{"$match": {"question_text": "What's up"}}]) + + The pipeline may also return additional fields that will be added as + annotations on the models:: + + >>> questions = Question.objects.raw_aggregate([{ + ... "$project": { + ... "question_text": 1, + ... "pub_date": 1, + ... "year_published": {"$year": "$pub_date"} + ... } + ... }]) + >>> for q in questions: + ... print(f"{q.question_text} was published in {q.year_published}.") + ... + What's up? was published in 2024. + + Fields may also be left out: + + >>> Question.objects.raw_aggregate([{"$project": {"question_text": 1}}]) + + The ``Question`` objects returned by this query will be deferred model instances + (see :meth:`~django.db.models.query.QuerySet.defer()`). This means that the + fields that are omitted from the query will be loaded on demand. For example:: + + >>> for q in Question.objects.raw_aggregate([{"$project": {"question_text": 1}}]): + >>> print( + ... q.question_text, # This will be retrieved by the original query. + ... q.pub_date, # This will be retrieved on demand. + ... ) + ... + What's new 2023-09-03 12:00:00+00:00 + What's up 2024-08-23 20:57:30+00:00 + + From outward appearances, this looks like the query has retrieved both the + question text and published date. However, this example actually issued three + queries. Only the question texts were retrieved by the ``raw_aggregate()`` + query -- the published dates were both retrieved on demand when they were + printed. diff --git a/docs/source/ref/utils.rst b/docs/source/ref/utils.rst index a05ad8b7..cf13fc9c 100644 --- a/docs/source/ref/utils.rst +++ b/docs/source/ref/utils.rst @@ -14,26 +14,26 @@ following parts can be considered stable. .. function:: parse_uri(uri, db_name=None, test=None) -Parses a MongoDB `connection string`_ into a dictionary suitable for Django's -:setting:`DATABASES` setting. + Parses a MongoDB `connection string`_ into a dictionary suitable for + Django's :setting:`DATABASES` setting. -.. _connection string: https://www.mongodb.com/docs/manual/reference/connection-string/ + .. _connection string: https://www.mongodb.com/docs/manual/reference/connection-string/ -Example:: + Example:: - import django_mongodb_backend + import django_mongodb_backend - MONGODB_URI = "mongodb+srv://my_user:my_password@cluster0.example.mongodb.net/defaultauthdb?retryWrites=true&w=majority&tls=false" - DATABASES["default"] = django_mongodb_backend.parse_uri(MONGODB_URI, db_name="example") + MONGODB_URI = "mongodb+srv://my_user:my_password@cluster0.example.mongodb.net/defaultauthdb?retryWrites=true&w=majority&tls=false" + DATABASES["default"] = django_mongodb_backend.parse_uri(MONGODB_URI, db_name="example") -You must specify ``db_name`` (the :setting:`NAME` of your database) if the URI -doesn't specify ``defaultauthdb``. + You must specify ``db_name`` (the :setting:`NAME` of your database) if the + URI doesn't specify ``defaultauthdb``. -You can use the parameters to customize the resulting :setting:`DATABASES` -setting: + You can use the parameters to customize the resulting :setting:`DATABASES` + setting: -- Use ``test`` to provide a dictionary of settings for test databases in the - format of :setting:`TEST `. + - Use ``test`` to provide a dictionary of settings for test databases in + the format of :setting:`TEST `. -But for maximum flexibility, construct :setting:`DATABASES` manually as -described in :ref:`configuring-databases-setting`. + But for maximum flexibility, construct :setting:`DATABASES` manually as + described in :ref:`configuring-databases-setting`.