Merge branch 'main' into operations

Author: ddrondo

.github/workflows/release-python.yml

@@ -39,17 +39,17 @@ jobs:
     outputs:
       version: ${{ steps.pre-publish.outputs.version }}
     steps:
-      - uses: mongodb-labs/drivers-github-tools/secure-checkout@v2
+      - uses: mongodb-labs/drivers-github-tools/secure-checkout@0e9d3008f418020d3039c45e633e887829110d9b # v3
         with:
           app_id: ${{ vars.APP_ID }}
           private_key: ${{ secrets.APP_PRIVATE_KEY }}
-      - uses: mongodb-labs/drivers-github-tools/setup@v2
+      - uses: mongodb-labs/drivers-github-tools/setup@0e9d3008f418020d3039c45e633e887829110d9b # v3
         with:
           aws_role_arn: ${{ secrets.AWS_ROLE_ARN }}
           aws_region_name: ${{ vars.AWS_REGION_NAME }}
           aws_secret_id: ${{ secrets.AWS_SECRET_ID }}
           artifactory_username: ${{ vars.ARTIFACTORY_USERNAME }}
-      - uses: mongodb-labs/drivers-github-tools/python/pre-publish@v2
+      - uses: mongodb-labs/drivers-github-tools/python/pre-publish@0e9d3008f418020d3039c45e633e887829110d9b # v3
         id: pre-publish
         with:
           dry_run: ${{ env.DRY_RUN }}
@@ -99,17 +99,17 @@ jobs:
       attestations: write
       security-events: write
     steps:
-      - uses: mongodb-labs/drivers-github-tools/secure-checkout@v2
+      - uses: mongodb-labs/drivers-github-tools/secure-checkout@0e9d3008f418020d3039c45e633e887829110d9b # v3
         with:
           app_id: ${{ vars.APP_ID }}
           private_key: ${{ secrets.APP_PRIVATE_KEY }}
-      - uses: mongodb-labs/drivers-github-tools/setup@v2
+      - uses: mongodb-labs/drivers-github-tools/setup@0e9d3008f418020d3039c45e633e887829110d9b # v3
         with:
           aws_role_arn: ${{ secrets.AWS_ROLE_ARN }}
           aws_region_name: ${{ vars.AWS_REGION_NAME }}
           aws_secret_id: ${{ secrets.AWS_SECRET_ID }}
           artifactory_username: ${{ vars.ARTIFACTORY_USERNAME }}
-      - uses: mongodb-labs/drivers-github-tools/python/post-publish@v2
+      - uses: mongodb-labs/drivers-github-tools/python/post-publish@0e9d3008f418020d3039c45e633e887829110d9b # v3
         with:
           following_version: ${{ env.FOLLOWING_VERSION }}
           product_name: ${{ env.PRODUCT_NAME }}

django_mongodb_backend/utils.py

@@ -1,10 +1,12 @@
 import copy
 import time
+import warnings
 
 import django
 from django.conf import settings
 from django.core.exceptions import ImproperlyConfigured, ValidationError
 from django.db.backends.utils import logger
+from django.utils.deprecation import RemovedInDjango60Warning
 from django.utils.functional import SimpleLazyObject
 from django.utils.text import format_lazy
 from django.utils.version import get_version_tuple
@@ -33,6 +35,11 @@ def parse_uri(uri, *, db_name=None, options=None, test=None):
     Convert the given uri into a dictionary suitable for Django's DATABASES
     setting.
     """
+    warnings.warn(
+        'parse_uri() is deprecated. Put the connection string in DATABASES["HOST"] instead.',
+        RemovedInDjango60Warning,
+        stacklevel=2,
+    )
     uri = pymongo_parse_uri(uri)
     host = None
     port = None

docs/conf.py

@@ -51,6 +51,7 @@
     "python": ("https://docs.python.org/3/", None),
     "atlas": ("https://www.mongodb.com/docs/atlas/", None),
     "manual": ("https://www.mongodb.com/docs/manual/", None),
+    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
 }
 
 # -- Options for HTML output -------------------------------------------------

docs/contents.rst

@@ -15,7 +15,7 @@ Table of contents
     howto/index
     faq
     releases/index
-    internals
+    internals/index
 
 Indices
 =======

docs/index.rst

@@ -61,7 +61,7 @@ Miscellaneous
 =============
 
 - :doc:`releases/index`
-- :doc:`internals`
+- :doc:`internals/index`
 
 .. Keep this toctree in sync with contents.rst.
 
@@ -75,4 +75,4 @@ Miscellaneous
     howto/index
     faq
     releases/index
-    internals
+    internals/index

docs/internals/bugs-and-features.rst

@@ -0,0 +1,25 @@
+======================================
+Reporting bugs and requesting features
+======================================
+
+.. Important::
+
+    Please :ref:`report security issues privately <reporting-security-issues>`.
+
+.. _issue-tracker:
+
+Issue tracker
+=============
+
+To report a bug or request a new feature in Django MongoDB Backend, please open
+an issue in our issue tracker, JIRA:
+
+1. Create a `JIRA account <https://jira.mongodb.org/>`_.
+
+2. Navigate to the `Python Integrations project
+   <https://jira.mongodb.org/projects/INTPYTHON/>`_.
+
+3. Click **Create Issue**. Please provide as much information as possible about
+   the issue and the steps to reproduce it.
+
+Bug reports in JIRA for this project can be viewed by everyone.

docs/internals/contributing/coding-style.rst

@@ -0,0 +1,35 @@
+============
+Coding style
+============
+
+Please follow these coding standards when writing code.
+
+.. _coding-style-pre-commit:
+
+Pre-commit checks
+=================
+
+`pre-commit <https://pre-commit.com>`_ is a framework for managing pre-commit
+hooks. These hooks help to identify simple issues before committing code for
+review. By checking for these issues before code review it allows the reviewer
+to focus on the change itself, and it can also help to reduce the number of CI
+runs.
+
+To use the tool, first install ``pre-commit`` and then the git hooks:
+
+.. code-block:: bash
+
+    $ python -m pip install pre-commit
+    $ pre-commit install
+
+On the first commit ``pre-commit`` will install the hooks, these are installed
+in their own environments and will take a short while to install on the first
+run. Subsequent checks will be significantly faster. If an error is found an
+appropriate error message will be displayed. If the error was with ``ruff`` (a
+tool to standardize code formatting), then it will go ahead and fix it for you.
+Review the changes and re-stage for commit if you are happy with them.
+
+.. seealso::
+
+    The guidelines from Django's :ref:`Python style guide<coding-style-python>`
+    are generally applicable.

docs/internals/contributing/index.rst

@@ -0,0 +1,12 @@
+=================
+Contributing code
+=================
+
+So you'd like to write some code or documentation to improve Django MongoDB
+Backend? Here are some resources:
+
+.. toctree::
+
+   coding-style
+   unit-tests
+   writing-documentation

docs/internals/contributing/unit-tests.rst

@@ -0,0 +1,88 @@
+==========
+Unit tests
+==========
+
+Django MongoDB Backend uses the Django test suite, located in
+``django-repo/tests``, as well as additional tests of its own, located in the
+``tests`` directory of the Django MongoDB Backend repository.
+
+The tests use the testing infrastructure that ships with Django. See
+:doc:`django:topics/testing/overview` for an explanation of how to write new
+tests.
+
+.. _running-unit-tests:
+
+Running the unit tests
+======================
+
+First, `fork Django MongoDB Backend on GitHub
+<https://github.com/mongodb/django-mongodb-backend/fork>`__.
+
+Second, create and activate a Python virtual environment:
+
+.. code-block:: bash
+
+    $ python -m venv .venv
+    $ source .venv/bin/activate
+
+Third, clone your fork and install it:
+
+.. code-block:: bash
+
+    $ git clone https://github.com/YourGitHubName/django-mongodb-backend.git
+    $ cd django-mongodb-backend
+    $ pip install -e .
+
+Next, get and install a copy of MongoDB's Django fork. This fork has some
+test suite adaptions for Django MongoDB Backend. There is a branch for each
+feature release of Django (e.g. ``mongodb-5.2.x`` below).
+
+.. code-block:: bash
+
+   $ git clone https://github.com/mongodb-forks/django.git django-repo
+   $ cd django-repo
+   $ git checkout -t origin/mongodb-5.2.x
+   $ python -m pip install -e .
+   $ python -m pip install -r tests/requirements/py3.txt
+
+Next, start :doc:`a local instance of mongod
+<manual:tutorial/manage-mongodb-processes>`.
+
+Then, create a test settings file, ``django-repo/tests/test_mongo.py``::
+
+    from test_sqlite import *
+
+    DATABASES = {
+        "default": {
+            "ENGINE": "django_mongodb_backend",
+            "NAME": "django",
+            # Needed if connecting to the Atlas test VM.
+            "OPTIONS": {"directConnection": True},
+        },
+        "other": {
+            "ENGINE": "django_mongodb_backend",
+            "NAME": "django1",
+            "OPTIONS": {"directConnection": True},
+        },
+    }
+
+    DEFAULT_AUTO_FIELD = "django_mongodb_backend.fields.ObjectIdAutoField"
+
+Finally, you can run the test script in the Django repository:
+
+   $ ./tests/runtests.py --settings=test_mongo basic
+
+This runs the tests in ``django-repo/tests/basic``. You can also specify a
+directory in ``django-mongodb-backend/tests``. All of these directories
+have an underscore suffix (e.g. ``queries_``) to distinguish them from Django's
+own test directories.
+
+.. warning::
+
+    Don't try to invoke ``runtests.py`` without specifying any test apps
+    (directories) as running all the tests at once will take hours.
+
+.. seealso::
+
+    :doc:`Django's guide to running its test suite
+    <django:internals/contributing/writing-code/unit-tests>`.

docs/internals/contributing/writing-documentation.rst

@@ -0,0 +1,107 @@
+=====================
+Writing documentation
+=====================
+
+The documentation uses the `Sphinx <https://www.sphinx-doc.org/>`_
+documentation system.
+
+How the documentation is organized
+==================================
+
+The documentation is organized into several categories:
+
+* :doc:`Tutorials </intro/index>` take the reader by the hand through a series
+  of steps to create something.
+
+  The important thing in a tutorial is to help the reader achieve something
+  useful, preferably as early as possible, in order to give them confidence.
+
+  Explain the nature of the problem we're solving, so that the reader
+  understands what we're trying to achieve. Don't feel that you need to begin
+  with explanations of how things work - what matters is what the reader does,
+  not what you explain. It can be helpful to refer back to what you've done and
+  explain afterward.
+
+* :doc:`Topic guides </topics/index>` aim to explain a concept or subject at a
+  fairly high level.
+
+  Link to reference material rather than repeat it. Use examples and don't be
+  reluctant to explain things that seem very basic to you - it might be the
+  explanation someone else needs.
+
+  Providing background context helps a newcomer connect the topic to things
+  that they already know.
+
+* :doc:`Reference guides </ref/index>` contain technical references for APIs.
+  They describe the functioning of Django MongoDB Backend's internal machinery
+  and instruct in its use.
+
+  Keep reference material tightly focused on the subject. Assume that the
+  reader already understands the basic concepts involved but needs to know or
+  be reminded of how Django MongoDB Backend does it.
+
+  Reference guides aren't the place for general explanation. If you find
+  yourself explaining basic concepts, you may want to move that material to a
+  topic guide.
+
+* :doc:`How-to guides </howto/index>` are recipes that take the reader through
+  steps in key subjects.
+
+  What matters most in a how-to guide is what a user wants to achieve.
+  A how-to should always be result-oriented rather than focused on internal
+  details of how Django MongoDB Backend implements whatever is being discussed.
+
+  These guides are more advanced than tutorials and assume some knowledge about
+  how Django MongoDB Backendo works.
+
+How to start contributing documentation
+=======================================
+
+Clone the Django repository to your local machine
+-------------------------------------------------
+
+If you'd like to start contributing to the docs, get the source code
+repository:
+
+.. code-block:: bash
+
+     $ git clone https://github.com/mongodb/django-mongodb-backend.git
+
+If you're planning to submit these changes, you might find it useful to make a
+fork of this repository and clone your fork instead.
+
+Set up a virtual environment and install dependencies
+-----------------------------------------------------
+
+Create and activate a virtual environment, then install the dependencies:
+
+.. code-block:: bash
+
+     $ python -m venv .venv
+     $ source .venv/bin/activate
+     $ python -m pip install -e ".[docs]"
+
+Build the documentation locally
+-------------------------------
+
+You build the HTML output from the ``docs`` directory:
+
+.. code-block:: bash
+
+     $ cd docs
+     $ make html
+
+Your locally-built documentation will be accessible at
+``_build/html/index.html`` and it can be viewed in any web browser.
+
+Making edits to the documentation
+---------------------------------
+
+The source files are ``.rst`` files located in the ``docs/`` directory.
+
+These files are written in the reStructuredText markup language. To learn the
+markup, see the :ref:`reStructuredText reference <sphinx:rst-index>`.
+
+To edit this page, for example, edit the file
+``docs/internals/contributing/writing-documentation.txt`` and rebuild the
+HTML with ``make html``.