stub out docs

Author: timgraham

.pre-commit-config.yaml

@@ -44,6 +44,7 @@ repos:
   hooks:
   - id: rstcheck
     additional_dependencies: [sphinx]
+    args: ["--ignore-directives=fieldlookup", "--ignore-roles=lookup"]
 
 # We use the Python version instead of the original version which seems to require Docker
 # https://github.com/koalaman/shellcheck-precommit

docs/source/_ext/djangodocs.py

@@ -0,0 +1,6 @@
+def setup(app):
+    app.add_crossref_type(
+        directivename="fieldlookup",
+        rolename="lookup",
+        indextemplate="pair: %s; field lookup type",
+    )

docs/source/conf.py

@@ -7,7 +7,14 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 from __future__ import annotations
 
+import sys
 from importlib.metadata import version as _version
+from pathlib import Path
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.append(str((Path(__file__).parent / "_ext").resolve()))
 
 project = "django_mongodb"
 copyright = "2024, The MongoDB Python Team"
@@ -22,6 +29,7 @@
 add_module_names = False
 
 extensions = [
+    "djangodocs",
     "sphinx.ext.intersphinx",
 ]
 

docs/source/fields.rst

@@ -5,6 +5,172 @@ Model field reference
 
 Some MongoDB-specific fields are available in ``django_mongodb.fields``.
 
+``ArrayField``
+--------------
+
+.. class:: ArrayField(base_field, size=None, **options)
+
+    A field for storing lists of data. Most field types can be used, and you
+    pass another field instance as the :attr:`base_field
+    <ArrayField.base_field>`. You may also specify a :attr:`size
+    <ArrayField.size>`. ``ArrayField`` can be nested to store multi-dimensional
+    arrays.
+
+    If you give the field a :attr:`~django.db.models.Field.default`, ensure
+    it's a callable such as ``list`` (for an empty default) or a callable that
+    returns a list (such as a function). Incorrectly using ``default=[]``
+    creates a mutable default that is shared between all instances of
+    ``ArrayField``.
+
+    .. attribute:: base_field
+
+        This is a required argument.
+
+        Specifies the underlying data type and behavior for the array. It
+        should be an instance of a subclass of
+        :class:`~django.db.models.Field`. For example, it could be an
+        :class:`~django.db.models.IntegerField` or a
+        :class:`~django.db.models.CharField`. Most field types are permitted,
+        with the exception of those handling relational data
+        (:class:`~django.db.models.ForeignKey`,
+        :class:`~django.db.models.OneToOneField` and
+        :class:`~django.db.models.ManyToManyField`) and file fields (
+        :class:`~django.db.models.FileField` and
+        :class:`~django.db.models.ImageField`).
+
+        It is possible to nest array fields - you can specify an instance of
+        ``ArrayField`` as the ``base_field``. For example::
+
+            from django.db import models
+            from django_mongodb.fields import ArrayField
+
+
+            class ChessBoard(models.Model):
+                board = ArrayField(
+                    ArrayField(
+                        models.CharField(max_length=10, blank=True),
+                        size=8,
+                    ),
+                    size=8,
+                )
+
+        Transformation of values between the database and the model, validation
+        of data and configuration, and serialization are all delegated to the
+        underlying base field.
+
+    .. attribute:: size
+
+        This is an optional argument.
+
+        If passed, the array will have a maximum size as specified, validated
+        only by forms.
+
+Querying ``ArrayField``
+~~~~~~~~~~~~~~~~~~~~~~~
+
+There are a number of custom lookups and transforms for :class:`ArrayField`.
+We will use the following example model::
+
+    from django.db import models
+    from django_mongodb.fields import ArrayField
+
+
+    class Post(models.Model):
+        name = models.CharField(max_length=200)
+        tags = ArrayField(models.CharField(max_length=200), blank=True)
+
+        def __str__(self):
+            return self.name
+
+.. fieldlookup:: arrayfield.contains
+
+``contains``
+^^^^^^^^^^^^
+
+The :lookup:`contains` lookup is overridden on :class:`ArrayField`. The
+returned objects will be those where the values passed are a subset of the
+data. It uses the ``$setIntersection`` operator. For example:
+
+.. code-block:: pycon
+
+    >>> Post.objects.create(name="First post", tags=["thoughts", "django"])
+    >>> Post.objects.create(name="Second post", tags=["thoughts"])
+    >>> Post.objects.create(name="Third post", tags=["tutorial", "django"])
+
+    >>> Post.objects.filter(tags__contains=["thoughts"])
+    <QuerySet [<Post: First post>, <Post: Second post>]>
+
+    >>> Post.objects.filter(tags__contains=["django"])
+    <QuerySet [<Post: First post>, <Post: Third post>]>
+
+    >>> Post.objects.filter(tags__contains=["django", "thoughts"])
+    <QuerySet [<Post: First post>]>
+
+.. fieldlookup:: arrayfield.len
+
+``len``
+^^^^^^^
+
+Returns the length of the array. The lookups available afterward are those
+available for :class:`~django.db.models.IntegerField`. For example:
+
+.. code-block:: pycon
+
+    >>> Post.objects.create(name="First post", tags=["thoughts", "django"])
+    >>> Post.objects.create(name="Second post", tags=["thoughts"])
+
+    >>> Post.objects.filter(tags__len=1)
+    <QuerySet [<Post: Second post>]>
+
+.. fieldlookup:: arrayfield.index
+
+Index transforms
+^^^^^^^^^^^^^^^^
+
+Index transforms index into the array. Any non-negative integer can be used.
+There are no errors if it exceeds the :attr:`size <ArrayField.size>` of the
+array. The lookups available after the transform are those from the
+:attr:`base_field <ArrayField.base_field>`. For example:
+
+.. code-block:: pycon
+
+    >>> Post.objects.create(name="First post", tags=["thoughts", "django"])
+    >>> Post.objects.create(name="Second post", tags=["thoughts"])
+
+    >>> Post.objects.filter(tags__0="thoughts")
+    <QuerySet [<Post: First post>, <Post: Second post>]>
+
+    >>> Post.objects.filter(tags__1__iexact="Django")
+    <QuerySet [<Post: First post>]>
+
+    >>> Post.objects.filter(tags__276="javascript")
+    <QuerySet []>
+
+These indexes use 0-based indexing.
+
+.. fieldlookup:: arrayfield.slice
+
+Slice transforms
+^^^^^^^^^^^^^^^^
+
+Slice transforms take a slice of the array. Any two non-negative integers can
+be used, separated by a single underscore. The lookups available after the
+transform do not change. For example:
+
+.. code-block:: pycon
+
+    >>> Post.objects.create(name="First post", tags=["thoughts", "django"])
+    >>> Post.objects.create(name="Second post", tags=["thoughts"])
+    >>> Post.objects.create(name="Third post", tags=["django", "python", "thoughts"])
+
+    >>> Post.objects.filter(tags__0_1=["thoughts"])
+    <QuerySet [<Post: First post>, <Post: Second post>]>
+
+    >>> Post.objects.filter(tags__0_2__contains=["thoughts"])
+    <QuerySet [<Post: First post>, <Post: Second post>]>
+
+These indexes use 0-based indexing.
+
 ``ObjectIdField``
 -----------------
 

docs/source/forms.rst

@@ -11,3 +11,136 @@ Some MongoDB-specific fields are available in ``django_mongodb.forms``.
 .. class:: ObjectIdField
 
 Stores an :class:`~bson.objectid.ObjectId`.
+
+``SimpleArrayField``
+--------------------
+
+.. class:: SimpleArrayField(base_field, delimiter=',', max_length=None, min_length=None)
+
+    A field which maps to an array. It is represented by an HTML ``<input>``.
+
+    .. attribute:: base_field
+
+        This is a required argument.
+
+        It specifies the underlying form field for the array. This is not used
+        to render any HTML, but it is used to process the submitted data and
+        validate it. For example:
+
+        .. code-block:: pycon
+
+            >>> from django import forms
+            >>> from django_mongodb.forms import SimpleArrayField
+
+            >>> class NumberListForm(forms.Form):
+            ...     numbers = SimpleArrayField(forms.IntegerField())
+            ...
+
+            >>> form = NumberListForm({"numbers": "1,2,3"})
+            >>> form.is_valid()
+            True
+            >>> form.cleaned_data
+            {'numbers': [1, 2, 3]}
+
+            >>> form = NumberListForm({"numbers": "1,2,a"})
+            >>> form.is_valid()
+            False
+
+    .. attribute:: delimiter
+
+        This is an optional argument which defaults to a comma: ``,``. This
+        value is used to split the submitted data. It allows you to chain
+        ``SimpleArrayField`` for multidimensional data:
+
+        .. code-block:: pycon
+
+            >>> from django import forms
+            >>> from django_mongodb.forms import SimpleArrayField
+
+            >>> class GridForm(forms.Form):
+            ...     places = SimpleArrayField(SimpleArrayField(IntegerField()), delimiter="|")
+            ...
+
+            >>> form = GridForm({"places": "1,2|2,1|4,3"})
+            >>> form.is_valid()
+            True
+            >>> form.cleaned_data
+            {'places': [[1, 2], [2, 1], [4, 3]]}
+
+        .. note::
+
+            The field does not support escaping of the delimiter, so be careful
+            in cases where the delimiter is a valid character in the underlying
+            field. The delimiter does not need to be only one character.
+
+    .. attribute:: max_length
+
+        This is an optional argument which validates that the array does not
+        exceed the stated length.
+
+    .. attribute:: min_length
+
+        This is an optional argument which validates that the array reaches at
+        least the stated length.
+
+    .. admonition:: User friendly forms
+
+        ``SimpleArrayField`` is not particularly user friendly in most cases,
+        however it is a useful way to format data from a client-side widget for
+        submission to the server.
+
+``SplitArrayField``
+-------------------
+
+.. class:: SplitArrayField(base_field, size, remove_trailing_nulls=False)
+
+    This field handles arrays by reproducing the underlying field a fixed
+    number of times.
+
+    .. attribute:: base_field
+
+        This is a required argument. It specifies the form field to be
+        repeated.
+
+    .. attribute:: size
+
+        This is the fixed number of times the underlying field will be used.
+
+    .. attribute:: remove_trailing_nulls
+
+        By default, this is set to ``False``. When ``False``, each value from
+        the repeated fields is stored. When set to ``True``, any trailing
+        values which are blank will be stripped from the result. If the
+        underlying field has ``required=True``, but ``remove_trailing_nulls``
+        is ``True``, then null values are only allowed at the end, and will be
+        stripped.
+
+        Some examples::
+
+            SplitArrayField(IntegerField(required=True), size=3, remove_trailing_nulls=False)
+
+            ["1", "2", "3"]  # -> [1, 2, 3]
+            ["1", "2", ""]  # -> ValidationError - third entry required.
+            ["1", "", "3"]  # -> ValidationError - second entry required.
+            ["", "2", ""]  # -> ValidationError - first and third entries required.
+
+            SplitArrayField(IntegerField(required=False), size=3, remove_trailing_nulls=False)
+
+            ["1", "2", "3"]  # -> [1, 2, 3]
+            ["1", "2", ""]  # -> [1, 2, None]
+            ["1", "", "3"]  # -> [1, None, 3]
+            ["", "2", ""]  # -> [None, 2, None]
+
+            SplitArrayField(IntegerField(required=True), size=3, remove_trailing_nulls=True)
+
+            ["1", "2", "3"]  # -> [1, 2, 3]
+            ["1", "2", ""]  # -> [1, 2]
+            ["1", "", "3"]  # -> ValidationError - second entry required.
+            ["", "2", ""]  # -> ValidationError - first entry required.
+
+            SplitArrayField(IntegerField(required=False), size=3, remove_trailing_nulls=True)
+
+            ["1", "2", "3"]  # -> [1, 2, 3]
+            ["1", "2", ""]  # -> [1, 2]
+            ["1", "", "3"]  # -> [1, None, 3]
+            ["", "2", ""]  # -> [None, 2]