Skip to content

Made directive indentation consistent in docs #307

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 23, 2025
Merged

Made directive indentation consistent in docs #307

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
26b0055
Made directive indentation consistent in docs
timgraham May 22, 2025
2915bbb
Use tilde prefix for a couple links in docs/source/ref/models/fields.rst
timgraham May 22, 2025
c5bfebf
Update mongodb.com Django MongoDB Backend links to 5.2
timgraham May 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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),
Expand Down
10 changes: 5 additions & 5 deletions docs/source/ref/django-admin.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,10 +19,10 @@ Available commands

.. django-admin:: createcachecollection

Creates the cache collection for use with the :doc:`database cache backend
</topics/cache>` using the information from your :setting:`CACHES` setting.
Creates the cache collection for use with the :doc:`database cache backend
</topics/cache>` 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``.
2 changes: 1 addition & 1 deletion docs/source/ref/forms.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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``
--------------------
Expand Down
16 changes: 8 additions & 8 deletions docs/source/ref/models/fields.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <ArrayField.max_size>` of
the array. The lookups available after the transform are those from the
:attr:`base_field <ArrayField.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

Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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`.
53 changes: 27 additions & 26 deletions docs/source/ref/models/indexes.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <atlas:atlas-search/index-definitions>` on
the given field(s).
Creates a basic :doc:`search index <atlas:atlas-search/index-definitions>`
on the given field(s).

Some fields such as :class:`~django.db.models.DecimalField` aren't
supported. See the :ref:`Atlas documentation <atlas:bson-data-chart>` 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 <atlas:bson-data-chart>` 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
<atlas:atlas-vector-search/vector-search-type>` on the given field(s).
A subclass of :class:`SearchIndex` that creates a :doc:`vector search index
<atlas:atlas-vector-search/vector-search-type>` 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.
11 changes: 6 additions & 5 deletions docs/source/ref/models/models.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 </topics/embedded-models>`
must subclass.
An abstract model which all :doc:`embedded models </topics/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.
118 changes: 59 additions & 59 deletions docs/source/ref/models/querysets.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,34 +18,34 @@ queries that span multiple collections.
``QuerySet.explain()``
======================

- :meth:`QuerySet.explain() <django.db.models.query.QuerySet.explain>` supports
the `comment and verbosity options
<https://www.mongodb.com/docs/manual/reference/command/explain/#command-fields>`_.
:meth:`QuerySet.explain() <django.db.models.query.QuerySet.explain>` supports
the `comment and verbosity options
<https://www.mongodb.com/docs/manual/reference/command/explain/#command-fields>`_.

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
Expand All @@ -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()<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`.

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()<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`.

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.
30 changes: 15 additions & 15 deletions docs/source/ref/utils.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:[email protected]/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:[email protected]/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 <DATABASE-TEST>`.
- Use ``test`` to provide a dictionary of settings for test databases in
the format of :setting:`TEST <DATABASE-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`.
Loading