Deprecate parse_uri()

Author: timgraham

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/internals.rst

@@ -62,3 +62,36 @@ merge of a "Add support for Django X.Y" pull request. Before merging that pull
 request, a branch is created off of main to track the previous feature release.
 For example, the 5.1.x branch is created shortly after the release of Django
 5.2, and main starts tracking the Django 5.2.x series.
+
+Deprecation Timeline
+====================
+
+This document outlines when various pieces of Django MongoDB Backend will be
+removed or altered in a backward incompatible way, following their deprecation.
+
+6.0
+---
+
+.. _parse-uri-deprecation:
+
+``parse_uri()`` will be removed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``django_mongodb_backend.utils.parse_uri()`` is deprecated in favor of putting
+the connection string in ``DATABASES["HOST"]``.
+
+For example, instead of::
+
+    DATABASES = {
+        "default": django_mongodb_backend.parse_uri("mongodb://localhost:27017/", db_name="db"),
+    }
+
+use::
+
+    DATABASES = {
+        'default': {
+            'ENGINE': 'django_mongodb_backend',
+            'HOST': 'mongodb://localhost:27017/',
+            'NAME': 'db',
+        },
+    }

docs/ref/utils.rst

@@ -14,6 +14,12 @@ following parts can be considered stable.
 
 .. function:: parse_uri(uri, db_name=None, options=None, test=None)
 
+    .. deprecated:: 5.2.2
+
+        ``parse_uri()`` is deprecated in favor of putting the connection string
+        in ``DATABASES["HOST"]``. See :ref:`parse-uri-deprecation` for upgrade
+        instructions.
+
     Parses a MongoDB `connection string`_ into a dictionary suitable for
     Django's :setting:`DATABASES` setting.
 

docs/releases/5.2.x.rst

@@ -17,6 +17,13 @@ Bug fixes
 
 - ...
 
+Deprecations
+------------
+
+- ``django_mongod_backend.utils.parse_uri()`` is deprecated in favor of
+  putting the connection string in ``DATABASES["HOST"]``. See
+  :ref:`parse-uri-deprecation` for upgrade instructions.
+
 5.2.1
 =====
 

tests/backend_/utils/test_parse_uri.py

@@ -3,10 +3,13 @@
 import pymongo
 from django.core.exceptions import ImproperlyConfigured
 from django.test import SimpleTestCase
+from django.test.utils import ignore_warnings
+from django.utils.deprecation import RemovedInDjango60Warning
 
 from django_mongodb_backend import parse_uri
 
 
+@ignore_warnings(category=RemovedInDjango60Warning)
 class ParseURITests(SimpleTestCase):
     def test_simple_uri(self):
         settings_dict = parse_uri("mongodb://cluster0.example.mongodb.net/myDatabase")
@@ -105,3 +108,10 @@ def test_invalid_credentials(self):
     def test_no_scheme(self):
         with self.assertRaisesMessage(pymongo.errors.InvalidURI, "Invalid URI scheme"):
             parse_uri("cluster0.example.mongodb.net")
+
+
+class ParseURIDeprecationTests(SimpleTestCase):
+    def test_message(self):
+        msg = 'parse_uri() is deprecated. Put the connection string in DATABASES["HOST"] instead.'
+        with self.assertRaisesMessage(RemovedInDjango60Warning, msg):
+            parse_uri("mongodb://cluster0.example.mongodb.net/")