DOCSP-43200: Get started with Django #132

norareidy · 2024-11-26T15:21:53Z

Pull Request Info

JIRA - https://jira.mongodb.org/browse/DOCSP-43200
Staging - https://deploy-preview-132--docs-pymongo.netlify.app/django-get-started/

Self-Review Checklist

Is this free of any warnings or errors in the RST?
Did you run a spell-check?
Did you run a grammar-check?
Are all the links working?
Are the facets and meta keywords accurate?

netlify · 2024-11-26T15:22:10Z

✅ Deploy Preview for docs-pymongo ready!

Name	Link
🔨 Latest commit	`ea02256`
🔍 Latest deploy log	https://app.netlify.com/sites/docs-pymongo/deploys/678926df4acf960008c906b6
😎 Deploy Preview	https://deploy-preview-132--docs-pymongo.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

aclark4life

LGTM pending various small changes, thanks @norareidy

aclark4life · 2025-01-08T19:26:23Z

source/django-get-started/django-install.txt

@@ -61,7 +61,7 @@ in your development environment.

      .. code-block:: bash

-         pip install git+https://github.com/mongodb-labs/django-mongodb
+         pip install git+https://github.com/mongodb-labs/django-mongodb-backend


The alpha release is now on PyPI, so maybe this should be pip install django-mongodb-backend. 🤔

source/django-get-started/django-connect-mongodb.txt

source/django-get-started/django-connection-string.txt

aclark4life · 2025-01-08T19:58:06Z

source/django-get-started/django-install.txt

+
+         pip install git+https://github.com/mongodb-labs/django-mongodb-backend
+
+      This command also installs the following dependencies:


Also those dependencies' dependencies but quite possibly not worth mentioning.

asgiref

dnspython

sqlparse

django-mongodb-backend v5.0a1 ├── django v5.0.10 │ ├── asgiref v3.8.1 │ └── sqlparse v0.5.3 ├── pymongo v4.10.1 │ └── dnspython v2.7.0

snooty.toml

aclark4life · 2025-01-08T20:01:37Z

source/django-get-started.txt

+   :values: tutorial
+
+.. meta::
+   :description: Learn how to create an app to connect to a MongoDB deployment by using Django MongoDB.


s/Django MongoDB/Django MongoDB Backend/

aclark4life · 2025-01-08T20:01:51Z

source/index.txt

@@ -13,6 +13,7 @@ MongoDB {+driver-short+} Documentation
 .. toctree::

   Get Started </get-started>
+   Get Started with Django MongoDB </django-get-started>


s/Django MongoDB/Django MongoDB Backend/

aclark4life

LGTM, thanks

norareidy · 2025-01-10T19:45:17Z

source/django-get-started/django-create-app.txt

+      .. code-block:: python
+
+         from django.db import models
+         from django_mongodb_backend.fields import EmbeddedModelField, ArrayField


Note: the EmbeddedModelField import and the awards Movie field below will cause errors until this PR is merged

Jibola

LGTM!!

timgraham · 2025-01-11T15:51:44Z

source/django-get-started/django-create-app.txt

+            text = models.CharField(max_length=100)
+
+            class Meta:
+               abstract = True


This should be omitted. Abstract models can't be instantiated so this approach isn't compatible with the current implementation. There isn't currently a way to avoid the collection from being created separately. I'm still thinking about how we could solve this.

timgraham · 2025-01-11T15:56:38Z

source/django-get-started/django-create-admin.txt

+
+You can create a Django admin site to edit your application's 
+data from a web interface. To learn more about the Django admin
+site and its features, see `The Django admin site <https://docs.djangoproject.com/en/5.1/ref/contrib/admin/>`__


There's a mismatch between the version number in the Django links and "django-version-number".

Updated to use the django-version-number constant

timgraham · 2025-01-11T15:58:57Z

source/django-get-started/django-create-app.txt

+
+         class Movie(models.Model):
+            title = models.CharField(max_length=200)
+            plot = models.TextField(null=True)


"Avoid using null on string-based fields such as CharField and TextField. The Django convention is to use an empty string, not NULL, as the “no data” state for string-based fields. If a string-based field has null=False, empty strings can still be saved for “no data”. If a string-based field has null=True, that means it has two possible values for “no data”: NULL, and the empty string. In most cases, it’s redundant to have two possible values for “no data”.

https://docs.djangoproject.com/en/dev/ref/models/fields/#null
(you should have blank=True though)

timgraham · 2025-01-11T16:02:29Z

source/django-get-started/django-connect-mongodb.txt

+      .. code-block:: bash
+
+         DATABASES = {
+            "default": {


The indentation is incorrect throughout these documents (only 3 spaces).

timgraham · 2025-01-11T16:03:51Z

source/django-get-started/django-create-app.txt

+            title = models.CharField(max_length=200)
+            plot = models.TextField(null=True)
+            runtime = models.IntegerField(default=0)
+            released = models.DateTimeField("release date", null=True)


Typically, any time you have null=True, you'll also need blank=True.

timgraham · 2025-01-12T00:43:06Z

source/django-get-started/django-query-data.txt

+         python3 manage.py shell
+         from sample_mflix.models import Movie, Viewer


This is a combination of bash and pycon.

timgraham · 2025-01-12T00:44:32Z

source/django-get-started/django-install.txt

+      Before installing {+django-odm+}, ensure you have the following dependencies installed
+      in your development environment:
+
+      - `Python3 version 3.10 or later <https://www.python.org/downloads/>`__


"Python 3.10 or later"

timgraham · 2025-01-12T00:45:37Z

source/django-get-started/django-install.txt

+      in your development environment:
+
+      - `Python3 version 3.10 or later <https://www.python.org/downloads/>`__
+      - `pip <https://pip.pypa.io/en/stable/installation/>`__


Python 3 includes pip, so I think there should be no need install it separately.

timgraham · 2025-01-12T00:47:36Z

source/django-get-started/django-create-app.txt

+
+         def index(request):
+            return HttpResponse("Hello, world. You're at the application index.")
+


Extra blank line compared to rest of example.

timgraham · 2025-01-12T00:49:18Z

source/django-get-started/django-create-app.txt

+
+      .. code-block:: bash
+
+         python3 manage.py startapp sample_mflix --template https://github.com/mongodb-labs/django-mongodb-app/archive/refs/heads/5.0.x.zip


use {+django-version-number+} as in startproject?

R-shubham · 2025-01-13T20:48:22Z

source/django-get-started/django-connect-mongodb.txt

+      Atlas database user's username and password. Then, replace the
+      ``<connection string URI>`` placeholder with the connection string
+      that you copied from the :ref:`django-get-started-connection-string`
+      step of this guide.


@norareidy The connection string that user copies will have username and password by default. If they are using this approach then "HOST" will expect connection string in this format: "mongodb+srv://cluster0.example.mongodb.net". @Jibola / @aclark4life can you confirm?

There are at least two things going on here:

DATABASES dictionary: DATABASES["default"]["HOST"] can accept a prefix of mongodb+srv:// but does not require one.

django_mongodb_backend.parse_uri: Connection string is terminology only used in the context of parse_uri and in that context, the MONGODB_URI from Atlas can be "cut and pasted" with the exception of the NAME key which is not present in the Atlas MONGODB_URI but must be present in the parse_uri connection string.

To put it another way:

DATABASES dictionary: DATABASES["default"]["NAME"] must be defined. -or-

django_mongodb_backend.parse_uri: MONGODB_URI must include /mydatabase e.g. mongodb+srv://cluster0.example.mongodb.net/mydatabase.

Again, if it's easier to steer clear of parse_uri for clarity's sake that's OK.

aclark4life · 2025-01-13T22:52:57Z

snooty.toml

@@ -25,12 +25,14 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 driver-short = "PyMongo"
 driver-long = "PyMongo, the MongoDB synchronous Python driver,"
 driver-async = "PyMongo Async"
+django-odm = "Django MongoDB"


s/Django MongoDB/Django MongoDB Backend/?

timgraham · 2025-01-13T23:26:59Z

snooty.toml

@@ -25,12 +26,15 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
 driver-short = "PyMongo"
 driver-long = "PyMongo, the MongoDB synchronous Python driver,"
 driver-async = "PyMongo Async"
+django-odm = "MongoDB Backend for Django"
+django-api = "https://django-mongodb.readthedocs.io/en/latest/"


Be aware this is changing to "django-mongodb-backend".

timgraham · 2025-01-13T23:29:24Z

source/django-get-started.txt

+   Create an Admin Site </django-get-started/django-create-admin/>
+   Next Steps </django-get-started/django-next-steps/>
+
+{+django-odm+} is a PyMongo integration that allows you to use the


Open to what others think, but I would call it "a MongoDB integration that uses PyMongo under the hood." i.e. the primary purpose is to use MongoDB! The fact that it uses PyMongo is incidental.

Agree. "Django MongoDB Backend is a MongoDB database backend for Django that uses PyMongo to connect to MongoDB and implements the Django database specification so users can use MongoDB with Django."

I tend to avoid colloquialisms like "under the hood" and PyMongo is incidental here.

That is a rather verbose and redundant sentence. 😆

"Django MongoDB Backend is a Django database backend that uses PyMongo to connect to MongoDB." might be sufficient!

Updated! Do you have a preference between "Django MongoDB Backend" and "MongoDB Backend for Django"?

The other backends I've written use the latter phrasing, however, since we had to rename our package from django-mongondb to django-mongodb-backend, we can use the former.

timgraham · 2025-01-14T01:11:06Z

source/django-get-started/django-connect-mongodb.txt

+
+      .. code-block:: bash
+
+         python3 manage.py runserver


Maybe this is consistent with the rest of your documentation and you want to leave it alone, but if you are working in a Python 3 virtual environment, you can write python without the 3. Coming from Django's docs, it looks odd to include that 3 on all commands.

I was going to raise this too, but would defer to MongoDB-wide conventions. If there are no such conventions, then I prefer python too.

timgraham · 2025-01-14T01:11:16Z

source/django-get-started/django-connect-mongodb.txt

+      Open your ``settings.py`` file and navigate to the ``DATABASES`` setting.
+      Replace this setting with the following code:
+
+      .. code-block:: bash


timgraham · 2025-01-14T01:12:37Z

source/django-get-started/django-connection-string.txt

+
+After completing these steps, you have a connection string that
+contains your database username and password.
+


You may want to delete the stray blank line(s) at the end of some documents. ;-)

timgraham · 2025-01-14T01:29:47Z

source/django-get-started/django-create-app.txt

+      .. code-block:: bash
+
+         python3 manage.py makemigrations sample_mflix
+         python3 manage.py migrate


sample_mflix is an existing database, so the models should have an inner Meta class with managed = False so that Django doesn't try to create (and otherwise modify) the collections. Otherwise, I believe MongoDB will error with "collection already exists) here when running migrate...

@timgraham As well as set db_name correct?

Yes, db_table is already set.

timgraham · 2025-01-14T01:32:21Z

source/django-get-started/django-install.txt

+      This command also installs the following dependencies:
+
+      - PyMongo version {+version-number+} and its dependencies
+      - Django version {+django-version-number+} and its dependencies


More precisely, this will be "The latest Django 5.0.x version...'

timgraham · 2025-01-14T01:34:02Z

source/django-get-started/django-query-data.txt

+
+      This code returns the name of the matching user:
+
+      .. code-block:: bash


Technically the formatter is "pycon" but since you don't format your console sessions normally, I'm not sure it matters.

pycon is not an option for the .. code-block:: directive unfortunately

timgraham · 2025-01-14T01:38:27Z

source/django-get-started/django-write-data.txt

+         movie_awards = Award(wins=122, nominations=245, text="Won 1 Oscar")
+         movie = Movie(title="Minari", plot=
+         "A Korean-American family moves to an Arkansas farm in search of their own American Dream",
+         runtime=217, released=timezone.make_aware(datetime(2020, 1, 26, 0, 0)),


0, 0 is optional (default values)

timgraham · 2025-01-14T01:42:24Z

source/django-get-started/django-write-data.txt

+      .. code-block:: python
+
+         movie_awards = Award(wins=122, nominations=245, text="Won 1 Oscar")
+         movie = Movie(title="Minari", plot=


If you like, it would be more readable to format these using hanging indent, e.g.

movie = Movie( title="Minari", plot="...", ... )

Also, you can use movie = Movie.objects.create(...)if you want to avoid the separate save() step. That's the usual pattern unless you need to do something between initializing the model and saving it.

gmiller-mdb

LGTM!

DOCSP-43200: Get started with Django

40ffb76

norareidy added 23 commits November 26, 2024 10:38

edits

be878e5

edit code

704c54e

more info

1caf1a3

query steps

4142196

edit

aa27f12

edits

8585730

landing page

e520bf4

wording

123a2d5

fix query structure

d439dac

fixes

7bb56ea

template edit

2d3224f

copyable code blocks

0fbb2e1

connection string

735bccf

fix image

4d9999e

AR feedback

a14aae2

fix

b353a24

fix admonition

711af57

wording

f2b7d40

admin site, more crud operations

6b599a7

edits

aa3814b

more wording changes

a993adf

fix intro text

c0c53b1

fix

6bd451d

norareidy requested review from Jibola, aclark4life and R-shubham January 8, 2025 18:34

django_mongodb_backend

6f46a1c

aclark4life suggested changes Jan 8, 2025

View reviewed changes

norareidy changed the base branch from master to django-mongodb-backend January 8, 2025 22:00

AC feedback

be3b2ed

norareidy requested a review from aclark4life January 8, 2025 22:17

norareidy mentioned this pull request Jan 8, 2025

DOCSP-46328: Django connection configuration #142

Closed

5 tasks

next steps edits

595ee65

aclark4life approved these changes Jan 10, 2025

View reviewed changes

rustagir self-requested a review January 10, 2025 19:04

norareidy commented Jan 10, 2025

View reviewed changes

Jibola approved these changes Jan 10, 2025

View reviewed changes

timgraham reviewed Jan 12, 2025

View reviewed changes

norareidy added 2 commits January 13, 2025 14:12

TG feedback

c863134

spacing

ecff738

norareidy requested a review from timgraham January 13, 2025 20:16

R-shubham reviewed Jan 13, 2025

View reviewed changes

aclark4life reviewed Jan 13, 2025

View reviewed changes

timgraham reviewed Jan 14, 2025

View reviewed changes

timgraham mentioned this pull request Jan 14, 2025

DOCSP-46321: CRUD operations #144

Open

5 tasks

norareidy added 3 commits January 14, 2025 10:27

parse_uri edits

1c06aec

TG feedback 2

58b3541

connection string

7bf9018

norareidy requested a review from timgraham January 14, 2025 18:31

rustagir removed request for timgraham and rustagir January 14, 2025 20:10

norareidy requested review from timgraham and R-shubham January 14, 2025 22:39

norareidy added 2 commits January 15, 2025 13:50

code fix

7a54a24

model edit

ea02256

gmiller-mdb approved these changes Jan 17, 2025

View reviewed changes


		pip install git+https://github.com/mongodb-labs/django-mongodb-backend

		This command also installs the following dependencies:

		python3 manage.py shell
		from sample_mflix.models import Movie, Viewer


		def index(request):
		return HttpResponse("Hello, world. You're at the application index.")


		.. code-block:: bash

		python3 manage.py startapp sample_mflix --template https://github.com/mongodb-labs/django-mongodb-app/archive/refs/heads/5.0.x.zip


		After completing these steps, you have a connection string that
		contains your database username and password.


		This code returns the name of the matching user:

		.. code-block:: bash

DOCSP-43200: Get started with Django #132

Are you sure you want to change the base?

DOCSP-43200: Get started with Django #132

Conversation

norareidy commented Nov 26, 2024 • edited Loading

Pull Request Info

Self-Review Checklist

netlify bot commented Nov 26, 2024 • edited Loading

✅ Deploy Preview for docs-pymongo ready!

aclark4life left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aclark4life left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Jibola left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

R-shubham Jan 13, 2025 • edited Loading

Choose a reason for hiding this comment

aclark4life Jan 13, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gmiller-mdb left a comment

Choose a reason for hiding this comment

norareidy commented Nov 26, 2024 •

edited

Loading

netlify bot commented Nov 26, 2024 •

edited

Loading

R-shubham Jan 13, 2025 •

edited

Loading

aclark4life Jan 13, 2025 •

edited

Loading