DOCSP-46321: CRUD operations #144

norareidy · 2025-01-10T22:17:21Z

Pull Request Info

JIRA - https://jira.mongodb.org/browse/DOCSP-46321
Staging - https://deploy-preview-144--docs-pymongo.netlify.app/interact-data/crud/

Note: this PR will move to the docs-django repo.

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 · 2025-01-10T22:17:38Z

✅ Deploy Preview for docs-pymongo ready!

Name	Link
🔨 Latest commit	`60cc381`
🔍 Latest deploy log	https://app.netlify.com/sites/docs-pymongo/deploys/679132f65201d4000880d89b
😎 Deploy Preview	https://deploy-preview-144--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 · 2025-01-14T12:47:20Z

source/interact-data/crud.txt

+        genres = ArrayField(models.CharField(max_length=100), blank=True)
+        objects = MongoManager()
+
+        class Meta:


@timgraham Do we need managed=False here too?

Well, yes, there is a lot of feedback from #132 that's not yet incorporated here.

aclark4life · 2025-01-14T12:49:55Z

source/interact-data/crud.txt

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


@norareidy Can you confirm you want to keep python3 (vs. python) for MongoDB-wide compliance reasons? Just want to make sure we decide definitively somewhere in writing.

python is fine, I updated the Getting Started guide as well

aclark4life · 2025-01-14T12:51:16Z

snooty.toml

@@ -25,6 +25,7 @@ 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"


@norareidy Also here can you confirm we want to use "MongoDB Backend for Django" instead of "Django MongoDB Backend" ? Thank you!

Updated to "Django MongoDB Backend" in all PRs

aclark4life

LGTM pending minor issues resolution, which may or may not require additional edits.

timgraham · 2025-01-14T20:43:43Z

source/interact-data/crud.txt

+.. tip::
+
+    To learn more about Django's ``QuerySet`` API, see
+    `QuerySet API reference <https://docs.djangoproject.com/en/5.1/ref/models/querysets/>`__


How about using intersphinx for linking to Django docs? The objects file: http://docs.djangoproject.com/en/5.0/_objects/ I think this would be especially helpful for making sure links stay updated when switching from one Django version to the next.

Looks like there is some precedent for that.

Looking into this!

@norareidy were we able to get resolve the issue with sphinx?

timgraham · 2025-01-14T20:43:53Z

source/interact-data/crud.txt

+       released = models.DateTimeField("release date", null=True, blank=True)
+       awards = EmbeddedModelField(Award)
+       genres = ArrayField(models.CharField(max_length=100), null=True, blank=True)
+       objects = MongoManager()


no need for this

No need for MongoManager or all 4 lines?

I think MongoManager

timgraham · 2025-01-14T20:56:31Z

source/interact-data/crud.txt

+Example
+~~~~~~~
+
+The following example calls the ``create()`` method on your ``Movie`` objects


The phrasing "create() method on your Movie objects" is used several times. This isn't precisely correct and could give the impression of something like "Movie.create(). "Movie.objects" is a manager and "create" is a queryset method. Rather than get into all of that, you might just say something like, "The following example uses the create() method to insert a document..."

aclark4life · 2025-01-15T21:25:59Z

source/interact-data/crud.txt

-CRUD operations. To update documents in your collection, call the 
-``QuerySet`` operation methods on your model objects that represent the collection.
-Then, {+django-odm+} runs the operations on your collection documents.
+CRUD operations. To run these operations, call ``QuerySet`` methods


operations, ^you can call

aclark4life · 2025-01-15T21:26:06Z

source/interact-data/crud.txt

-``QuerySet`` operation methods on your model objects that represent the collection.
-Then, {+django-odm+} runs the operations on your collection documents.
+CRUD operations. To run these operations, call ``QuerySet`` methods
+your model's ``Manager``. The ``Manager`` class handles database


methods ^on your

aclark4life · 2025-01-15T21:37:11Z

source/interact-data/crud.txt

+To insert a document into a collection, call the ``create()`` method
+on an instance of your model's ``Manager`` class. Pass the new document's
+fields and values as arguments to the ``create()`` method.
+


To insert a document into a collection, call the create() method on your model's Manager class. Pass the new document's field names and field values as arguments to the create() method.

aclark4life · 2025-01-15T21:40:33Z

source/interact-data/crud.txt

+   and save the object as a collection document in one method call.
+   To view an example that creates an object then saves it to the
+   database by calling ``save()``, see `create() <https://docs.djangoproject.com/en/5.1/ref/models/querysets/#create>`__
+   in the Django documentation.


I don't know if you want to mention this shortcut here, but I think you can also do this:

movie = Movie(title="Poor Things", runtime=141)

Presumably this works because instantiation of the class calls the manager's create method or something like that.

Looks like you still need to call save() after to actually insert it into the database

aclark4life · 2025-01-15T21:41:18Z

source/interact-data/crud.txt

+
+To retrieve documents from your collection, call the ``filter()`` method on an
+instance of your model's ``Manager`` class. Pass a query filter, or criteria
+that specifies which documents to retrieve, as an argument to the ``filter()`` method.


To retrieve documents from your collection, call the filter() method on your model's Manager class.

norareidy · 2025-01-16T21:57:22Z

source/interact-data/crud.txt

+
+To learn how to create a Django application that uses the ``Movie``
+model and the Python interactive shell to interact with MongoDB documents,
+visit the :ref:`django-get-started` tutorial.


Note: link broken until #132 is merged

aclark4life

LGTM

rustagir

a few small things!

source/interact-data/crud.txt

rustagir · 2025-01-17T14:15:12Z

source/interact-data/crud.txt

+CRUD operations. To run these operations, you can call ``QuerySet`` methods
+on your model's ``Manager``. The ``Manager`` class handles database


Suggested change

CRUD operations. To run these operations, you can call ``QuerySet`` methods

on your model's ``Manager``. The ``Manager`` class handles database

CRUD operations. To run these operations, call ``QuerySet`` methods

on your model's ``Manager`` instance? object?. The ``Manager`` class handles database

@aclark4life you suggested I remove "instance" - is it more accurate to replace with "object" or just keep as is?

I like Manager object.

Manager is a class with QuerySet methods mixed in: https://github.com/django/django/blob/stable/5.1.x/django/db/models/manager.py#L176.

The default Manager is called objects … and it's an attribute of the model class… but yeah, looking at Django's documentation a manager typically referred to as just "manager". It may help to use "manager" instead of Manager since we're referring to the model's manager and not the Manager class e.g.: https://docs.djangoproject.com/en/5.1/topics/db/queries/#retrieving-objects

Lastly, I find instance and object confusing for various reasons. I would say if you see Django using those terms go for it, else stick close to how Django describers managers as much as possible.

Correcting myself: this is how Django says it:

"To retrieve objects from your database, construct a QuerySet via a Manager on your model class."

Okay thank you! I will use "model's manager" as much as possible

rustagir · 2025-01-17T14:15:43Z

source/interact-data/crud.txt

+CRUD operations. To run these operations, you can call ``QuerySet`` methods
+on your model's ``Manager``. The ``Manager`` class handles database
+operations and allows you to interact with your MongoDB data by referencing
+Django models. By default, Django adds a ``Manager`` named ``objects``


S: consider making just "Django" a source constant as its a word with a high possibility of typos, IMO

rustagir · 2025-01-17T14:16:24Z

source/interact-data/crud.txt

+- :ref:`create() <django-crud-insert>`
+- :ref:`filter() and get() <django-crud-read>`
+- :ref:`update() <django-crud-modify>`
+- :ref:`delete() <django-crud-delete>`


Suggested change

- :ref:`create() <django-crud-insert>`

- :ref:`filter() and get() <django-crud-read>`

- :ref:`update() <django-crud-modify>`

- :ref:`delete() <django-crud-delete>`

- :ref:`create() <django-crud-insert>`: Insert new data

- :ref:`filter() and get() <django-crud-read>`: Retrieve specific documents... etc

- :ref:`update() <django-crud-modify>`

- :ref:`delete() <django-crud-delete>`

rustagir · 2025-01-17T14:17:06Z

source/interact-data/crud.txt

+
+.. tip::
+
+    To learn more about Django's ``QuerySet`` API, see


Suggested change

To learn more about Django's ``QuerySet`` API, see

To learn more about Django's ``QuerySet`` API, see the

source/interact-data/crud.txt

rustagir · 2025-01-17T14:19:42Z

source/interact-data/crud.txt

+   The ``create()`` method allows you to create a new ``Movie`` object
+   and save the object as a collection document in one method call.


Suggested change

The ``create()`` method allows you to create a new ``Movie`` object

and save the object as a collection document in one method call.

The ``create()`` method allows you to create a new ``Movie`` object

and save the object to MongoDB in one method call.

rustagir · 2025-01-17T14:20:09Z

source/interact-data/crud.txt

+   To view an example that creates an object then saves it to the
+   database by calling ``save()``, see `create() <https://docs.djangoproject.com/en/5.1/ref/models/querysets/#create>`__
+   in the Django documentation.


Q: why not include this example here?

rustagir · 2025-01-17T14:21:48Z

source/interact-data/crud.txt

+
+   If your query matches no documents or multiple documents, the ``get()``
+   method generates an error. To retrieve one document from a query
+   that might match multiple, chain the ``first()`` method to ``filter()``.


S: you can still link to the specify a query guide in the TODO, but adding a one line example here of chaining first() wouldnt be a bad idea either!

rustagir · 2025-01-17T14:22:16Z

source/interact-data/crud.txt

+       Movie.objects.filter(title="High Fidelity").update(plot=
+       "Rob, a record store owner and compulsive list maker, recounts his top five breakups, including the one in progress.")


Q: fix indentation?

Jibola

Another great read. Provided some additional feedback. Let me know what you think

Jibola · 2025-01-16T04:50:50Z

source/interact-data/crud.txt

+       class Meta:
+           db_table = "movies"
+           managed = False


Could you add a helpful tooltip or note to explain the purpose of these two meta configurations. A blurb along the lines of:
"""
In Django, defining a Meta class within a Model allows you to configure the Meta options for the model. In this example, we use db_table = "movies" to change the collection referenced in the database to look for movies, and we set managed = False to stop database creation, modification, or deletion during migration commands. To read more, check out Django's Meta Options documentation.
"""

Since I use this sample data on almost every page, what do you think of linking to the Models guide (which explains Meta and str()) instead of repeating the explanation every time?

Sounds good to me

Jibola · 2025-01-16T04:57:38Z

source/interact-data/crud.txt

+       def __str__(self):
+           return self.title


Same here. Another helpful tooltip:
"""
In Django, you can override the str method of a model to define how its instances are represented as strings.
"""

same comment as above

Yep. Works for me

Jibola · 2025-01-16T05:08:04Z

source/interact-data/crud.txt

+       <MongoQuerySet [<Movie: The Bumblebee Flies Anyway>, <Movie: Angels of the Universe>,
+       <Movie: First Person Plural>, <Movie: Just, Melvin: Just Evil>, <Movie: Sound and Fury>,
+       <Movie: Peppermint Candy>]>
+


I'm thinking we should add a tooltip to link to the lookup operations documentation in Django.

cc: @aclark4life @timgraham

Here's our intersphinx config: https://github.com/mongodb-labs/django-mongodb-backend/blob/main/docs/source/conf.py#L39-L45

Do you mean add a link to the Django documentation for each method at the end of the sections? I can do that!

Jibola · 2025-01-17T16:59:46Z

source/interact-data/crud.txt

+CRUD operations. To run these operations, you can call ``QuerySet`` methods
+on your model's ``Manager``. The ``Manager`` class handles database


I like Manager object.

rustagir

lgtm!

timgraham · 2025-01-22T14:36:24Z

Are there instructions on building the docs locally so we can debug intersphinx? I got this far:

$ ./build.sh 
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  2039  100  2039    0     0   9396      0 --:--:-- --:--:-- --:--:--  9396
make: *** No rule to make target 'examples'.  Stop.
=======================================================================================================================================================================
========================================================================== Running parser... ==========================================================================
INFO:snooty.main:Snooty 0.18.11 starting
INFO:snooty.parser:cache: 0 hits and 101 misses
INFO:snooty.gizaparser.domain:Parsing steps YAML
INFO:snooty.gizaparser.domain:Parsing extracts YAML
INFO:snooty.gizaparser.domain:Parsing release YAML
WARNING(fundamentals/collations.txt:0ish): Page not included in any toctree and not marked :orphan:
WARNING(fundamentals/type-hints.txt:0ish): Page not included in any toctree and not marked :orphan:
2 diagnostics; 74 pages; 3 assets
========================================================================== Parser complete ============================================================================
=======================================================================================================================================================================
Error: Failed to replace env in config: ${NPM_BASE_64_AUTH}
    at /usr/local/lib/node_modules/npm/lib/config/core.js:415:13
    at String.replace (<anonymous>)
    at envReplace (/usr/local/lib/node_modules/npm/lib/config/core.js:411:12)
    at parseField (/usr/local/lib/node_modules/npm/lib/config/core.js:389:7)
    at /usr/local/lib/node_modules/npm/lib/config/core.js:330:24
    at Array.forEach (<anonymous>)
    at Conf.add (/usr/local/lib/node_modules/npm/lib/config/core.js:328:23)
    at ConfigChain.addString (/usr/local/lib/node_modules/npm/node_modules/config-chain/index.js:244:8)
    at Conf.<anonymous> (/usr/local/lib/node_modules/npm/lib/config/core.js:316:10)
    at /usr/local/lib/node_modules/npm/node_modules/graceful-fs/graceful-fs.js:90:16
/usr/local/lib/node_modules/npm/lib/npm.js:59
      throw new Error('npm.load() required')
      ^

Error: npm.load() required
    at Object.get (/usr/local/lib/node_modules/npm/lib/npm.js:59:13)
    at process.errorHandler (/usr/local/lib/node_modules/npm/lib/utils/error-handler.js:205:32)
    at emitOne (events.js:125:13)
    at process.emit (events.js:221:7)
    at process._fatalException (bootstrap_node.js:382:26)

Jibola · 2025-01-22T17:10:26Z

source/interact-data/crud.txt

+       class Meta:
+           db_table = "movies"
+           managed = False


Sounds good to me

Jibola · 2025-01-22T17:10:36Z

source/interact-data/crud.txt

+       def __str__(self):
+           return self.title


Yep. Works for me

norareidy · 2025-01-22T22:58:31Z

Moved to the Django repo: mongodb/docs-django#11

R-shubham

LGTM

R-shubham · 2025-01-23T17:57:42Z

source/interact-data/crud.txt

+.. tip::
+
+    To learn more about Django's ``QuerySet`` API, see
+    `QuerySet API reference <https://docs.djangoproject.com/en/5.1/ref/models/querysets/>`__


@norareidy were we able to get resolve the issue with sphinx?

DOCSP-46321: CRUD operations

4230372

norareidy added 4 commits January 10, 2025 17:31

edits

924788d

snooty

6123720

add get() example

84bc486

more info

b81892b

norareidy requested review from aclark4life, Jibola and R-shubham January 13, 2025 15:55

aclark4life reviewed Jan 14, 2025

View reviewed changes

aclark4life approved these changes Jan 14, 2025

View reviewed changes

norareidy added 2 commits January 14, 2025 10:56

feedback

158ff3d

edits

da3ac8c

norareidy requested a review from timgraham January 14, 2025 20:43

timgraham reviewed Jan 14, 2025

View reviewed changes

norareidy added 2 commits January 15, 2025 16:17

feedback

15fee18

fix

ce6bcc4

aclark4life reviewed Jan 15, 2025

View reviewed changes

norareidy added 2 commits January 15, 2025 16:27

AC feedback

1283d40

output fix

073c29c

aclark4life reviewed Jan 15, 2025

View reviewed changes

norareidy added 2 commits January 16, 2025 10:30

AC feedback

3861026

wording

9c34109

norareidy commented Jan 16, 2025

View reviewed changes

aclark4life approved these changes Jan 17, 2025

View reviewed changes

rustagir suggested changes Jan 17, 2025

View reviewed changes

RR feedback

13fbf87

norareidy requested a review from rustagir January 17, 2025 15:53

fix

b3bfeb8

Jibola suggested changes Jan 17, 2025

View reviewed changes

rustagir approved these changes Jan 17, 2025

View reviewed changes

norareidy added 6 commits January 21, 2025 18:16

feedback

5ba56dc

method links

9636386

test intersphinx

6b99b50

fix

64f1e0b

another test

8999776

doesn't work, revert

df740e8

link fix

73fe484

Jibola approved these changes Jan 22, 2025

View reviewed changes

remove embedded

60cc381

norareidy closed this Jan 22, 2025

norareidy mentioned this pull request Jan 22, 2025

DOCSP-46321: CRUD operations mongodb/docs-django#11

Merged

5 tasks

R-shubham reviewed Jan 23, 2025

View reviewed changes

		CRUD operations. To run these operations, you can call ``QuerySet`` methods
		on your model's ``Manager``. The ``Manager`` class handles database

	To learn more about Django's ``QuerySet`` API, see
	To learn more about Django's ``QuerySet`` API, see the

		The ``create()`` method allows you to create a new ``Movie`` object
		and save the object as a collection document in one method call.

		Movie.objects.filter(title="High Fidelity").update(plot=
		"Rob, a record store owner and compulsive list maker, recounts his top five breakups, including the one in progress.")

DOCSP-46321: CRUD operations #144

DOCSP-46321: CRUD operations #144

Uh oh!

Conversation

norareidy commented Jan 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Info

Self-Review Checklist

Uh oh!

netlify bot commented Jan 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docs-pymongo ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aclark4life left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aclark4life left a comment

Choose a reason for hiding this comment

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

norareidy commented Jan 10, 2025 •

edited

Loading

netlify bot commented Jan 10, 2025 •

edited

Loading