From edef8cb38b968228b0721d3cf93ac246e81e6c82 Mon Sep 17 00:00:00 2001 From: David Lord Date: Sun, 6 Jan 2019 15:38:14 -0800 Subject: [PATCH] simplify mongoengine doc, redirect from mongokit --- docs/patterns/mongoengine.rst | 140 +++++++++++----------------------- docs/patterns/mongokit.rst | 7 ++ 2 files changed, 52 insertions(+), 95 deletions(-) create mode 100644 docs/patterns/mongokit.rst diff --git a/docs/patterns/mongoengine.rst b/docs/patterns/mongoengine.rst index d635128e..015e7b61 100644 --- a/docs/patterns/mongoengine.rst +++ b/docs/patterns/mongoengine.rst @@ -1,32 +1,30 @@ -.. mongoengine-pattern: +MongoDB with MongoEngine +======================== -MongoEngine in Flask -==================== +Using a document database like MongoDB is a common alternative to +relational SQL databases. This pattern shows how to use +`MongoEngine`_, a document mapper library, to integrate with MongoDB. -Using a document database rather than a full DBMS gets more common these days. -This pattern shows how to use MongoEngine, a document mapper library, to -integrate with MongoDB. - -This pattern requires a running MongoDB server, MongoEngine_ and Flask-MongoEngine_ -libraries installed:: +A running MongoDB server and `Flask-MongoEngine`_ are required. :: pip install flask-mongoengine .. _MongoEngine: http://mongoengine.org -.. _Flask-MongoEngine: http://docs.mongoengine.org/projects/flask-mongoengine/en/latest/>`_ +.. _Flask-MongoEngine: https://flask-mongoengine.readthedocs.io + Configuration ------------- -Basic setup can be done by defining ``MONGODB_SETTINGS`` on App config and then -creating a ``MongoEngine`` instance:: +Basic setup can be done by defining ``MONGODB_SETTINGS`` on +``app.config`` and creating a ``MongoEngine`` instance. :: from flask import Flask from flask_mongoengine import MongoEngine app = Flask(__name__) app.config['MONGODB_SETTINGS'] = { - 'host': "mongodb://localhost:27017/mydb" + "db": "myapp", } db = MongoEngine(app) @@ -34,40 +32,38 @@ creating a ``MongoEngine`` instance:: Mapping Documents ----------------- -To declare models that will represent your Mongo documents, just create a class that -inherits from ``Document`` and declare each of the fields:: +To declare a model that represents a Mongo document, create a class that +inherits from ``Document`` and declare each of the fields. :: - from mongoengine import * + import mongoengine as me + class Movie(me.Document): + title = me.StringField(required=True) + year = me.IntField() + rated = me.StringField() + director = me.StringField() + actors = me.ListField() - class Movie(Document): +If the document has nested fields, use ``EmbeddedDocument`` to +defined the fields of the embedded document and +``EmbeddedDocumentField`` to declare it on the parent document. :: - title = StringField(required=True) - year = IntField() - rated = StringField() - director = StringField() - actors = ListField() - -If the model has embedded documents, use ``EmbeddedDocument`` to defined the fields of -the embedded document and ``EmbeddedDocumentField`` to declare it on the parent document:: - - class Imdb(EmbeddedDocument): - - imdb_id = StringField() - rating = DecimalField() - votes = IntField() - - - class Movie(Document): + class Imdb(me.EmbeddedDocument): + imdb_id = me.StringField() + rating = me.DecimalField() + votes = me.IntField() + class Movie(me.Document): ... - imdb = EmbeddedDocumentField(Imdb) + imdb = me.EmbeddedDocumentField(Imdb) Creating Data ------------- -Just create the objects and call ``save()``:: +Instantiate your document class with keyword arguments for the fields. +You can also assign values to the field attributes after instantiation. +Then call ``doc.save()``. :: bttf = Movie(title="Back To The Future", year=1985) bttf.actors = [ @@ -81,73 +77,27 @@ Just create the objects and call ``save()``:: Queries ------- -Use the class ``objects`` attribute to make queries:: +Use the class ``objects`` attribute to make queries. A keyword argument +looks for an equal value on the field. :: - bttf = Movies.objects(title="Back To The Future").get() # Throw error if not unique + bttf = Movies.objects(title="Back To The Future").get_or_404() -``objects`` is an iterable. Query operators may be user by concatenating it with the document -key using a double-underscore:: +Query operators may be used by concatenating them with the field name +using a double-underscore. ``objects``, and queries returned by +calling it, are iterable. :: some_theron_movie = Movie.objects(actors__in=["Charlize Theron"]).first() for recents in Movie.objects(year__gte=2017): print(recents.title) -Available operators are as follows: -* ``ne`` -- not equal to -* ``lt`` -- less than -* ``lte`` -- less than or equal to -* ``gt`` -- greater than -* ``gte`` -- greater than or equal to -* ``not`` -- negate a standard check, may be used before other operators (e.g. - ``Q(age__not__mod=5)``) -* ``in`` -- value is in list (a list of values should be provided) -* ``nin`` -- value is not in list (a list of values should be provided) -* ``mod`` -- ``value % x == y``, where ``x`` and ``y`` are two provided values -* ``all`` -- every item in list of values provided is in array -* ``size`` -- the size of the array is -* ``exists`` -- value for field exists +Documentation +------------- -String queries -:::::::::::::: +There are many more ways to define and query documents with MongoEngine. +For more information, check out the `official documentation +`_. -The following operators are available as shortcuts to querying with regular -expressions: - -* ``exact`` -- string field exactly matches value -* ``iexact`` -- string field exactly matches value (case insensitive) -* ``contains`` -- string field contains value -* ``icontains`` -- string field contains value (case insensitive) -* ``startswith`` -- string field starts with value -* ``istartswith`` -- string field starts with value (case insensitive) -* ``endswith`` -- string field ends with value -* ``iendswith`` -- string field ends with value (case insensitive) -* ``match`` -- performs an $elemMatch so you can match an entire document within an array - -Some Tips ---------- - -* Attributes can be set as ``unique`` -* ``MongoEngine`` creates the ``_id`` attribute automatically to acess ``ObjectIds`` -* You can add choices to string fields: ``StringField(choices=['Apple', 'Banana'])`` -* If you don't want your class name to be the same name as the collection, you can define - a ``meta`` class member and use the ``collection`` parameter:: - - class Movie(Document): - - meta ={'collection': 'movie_documents'} - -Accessing PyMongo MongoClient ------------------------------ - -If, for some reason, you want to access PyMongo instance, use ``get_connection`` function:: - - from mongoengine.connection import get_connection - - conn = get_connection() - collection = conn.mydb.movie - collection({'title': u'Days of Thunder'}) - -For more information about MongoEngine, head over to the -`website `_. +Flask-MongoEngine adds helpful utilities on top of MongoEngine. Check +out their `documentation `_ as well. diff --git a/docs/patterns/mongokit.rst b/docs/patterns/mongokit.rst new file mode 100644 index 00000000..cf072d5d --- /dev/null +++ b/docs/patterns/mongokit.rst @@ -0,0 +1,7 @@ +:orphan: + +MongoDB with MongoKit +===================== + +MongoKit is no longer maintained. See :doc:`/patterns/mongoengine` +instead.