From 78d8cc7df83da4abbd147131ca1d44583f5a29e9 Mon Sep 17 00:00:00 2001 From: Harry Marr Date: Mon, 21 Dec 2009 04:33:36 +0000 Subject: [PATCH] Started work on user guide --- docs/index.rst | 6 ++- docs/tutorial.rst | 12 ++---- docs/userguide.rst | 80 +++++++++++++++++++++++++++++++++++++++ mongoengine/connection.py | 4 +- 4 files changed, 89 insertions(+), 13 deletions(-) create mode 100644 docs/userguide.rst diff --git a/docs/index.rst b/docs/index.rst index e6a2bde6..fbc5faa9 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,18 +6,20 @@ MongoEngine User Documentation ======================================= -Contents: +MongoEngine is an Object-Document Mapper, written in Python for working with +MongoDB. The source is available on +`GitHub `_. .. toctree:: :maxdepth: 2 tutorial.rst + userguide.rst apireference.rst Indices and tables ================== * :ref:`genindex` -* :ref:`modindex` * :ref:`search` diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 0ff2c494..48069ef1 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -9,14 +9,14 @@ application. As the purpose of this tutorial is to introduce MongoEngine, we'll focus on the data-modelling side of the application, leaving out a user interface. -Connecting to MongoDB ---------------------- +Getting started +--------------- Before we start, make sure that a copy of MongoDB is running in an accessible location --- running it locally will be easier, but if that is not an option then it may be run on a remote server. Before we can start using MongoEngine, we need to tell it how to connect to our -instance of **mongod**. For this we use the :func:`mongoengine.connect` +instance of :program:`mongod`. For this we use the :func:`~mongoengine.connect` function. The only argument we need to provide is the name of the MongoDB database to use:: @@ -24,11 +24,7 @@ database to use:: connect('tumblelog') -This will connect to a mongod instance running locally on the default port. To -connect to a mongod instance running elsewhere, specify the host and port -explicitly:: - - connect('tumblelog', host='192.168.1.35', port=12345) +For more information about connecting to MongoDB see :ref:`guide-connecting`. Defining our documents ---------------------- diff --git a/docs/userguide.rst b/docs/userguide.rst new file mode 100644 index 00000000..d4b8ecab --- /dev/null +++ b/docs/userguide.rst @@ -0,0 +1,80 @@ +User Guide +========== + +.. _guide-connecting: + +Connecting to MongoDB +--------------------- +To connect to a running instance of :program:`mongod`, use the +:func:`~mongoengine.connect` function. The first argument is the name of the +database to connect to. If the database does not exist, it will be created. If +the database requires authentication, :attr:`username` and :attr:`password` +arguments may be provided:: + + from mongoengine import connect + connect('project1', username='webapp', password='pwd123') + +By default, MongoEngine assumes that the :program:`mongod` instance is running +on **localhost** on port **27017**. If MongoDB is running elsewhere, you may +provide :attr:`host` and :attr:`port` arguments to +:func:`~mongoengine.connect`:: + + connect('project1', host='192.168.1.35', port=12345) + +Defining documents +------------------ +In MongoDB, a **document** is roughly equivalent to a **row** in an RDBMS. When +working with relational databases, rows are stored in **tables**, which have a +strict **schema** that the rows follow. MongoDB stores documents in +**collections** rather than tables - the principle difference is that no schema +is enforced at a database level. + +Defining a document's schema +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +MongoEngine allows you to define schemata for documents as this helps to reduce +coding errors, and allows for utility methods to be defined on fields which may +be present. + +To define a schema for a document, create a class that inherits from +:class:`~mongoengine.Document`. Fields are specified by adding **field +objects** as class attributes to the document class:: + + from mongoengine import * + import datetime + + class Page(Document): + title = StringField(max_length=200, required=True) + date_modified = DateTimeField(default=datetime.now) + +Fields +^^^^^^ +By default, fields are not required. To make a field mandatory, set the +:attr:`required` keyword argument of a field to ``True``. Fields also may have +validation constraints available (such as :attr:`max_length` in the example +above). Fields may also take default values, which will be used if a value is +not provided. Default values may optionally be a callable, which will be called +to retrieve the value (such as in the above example). The field types available +are as follows: + +* :class:`~mongoengine.StringField` +* :class:`~mongoengine.IntField` +* :class:`~mongoengine.FloatField` +* :class:`~mongoengine.DateTimeField` +* :class:`~mongoengine.ObjectIdField` +* :class:`~mongoengine.EmbeddedDocumentField` +* :class:`~mongoengine.ReferenceField` + +Document collections +^^^^^^^^^^^^^^^^^^^^ +Document classes that inherit **directly** from :class:`~mongoengine.Document` +will have their own **collection** in the database. The name of the collection +is by default the name of the class, coverted to lowercase (so in the example +above, the collection would be called `page`). If you need to change the name +of the collection (e.g. to use MongoEngine with an existing database), then +create a class dictionary attribute called :attr:`meta` on your document, and +set :attr:`collection` to the name of the collection that you want your +document class to use:: + + class Page(Document): + title = StringField(max_length=200, required=True) + meta = {'collection': 'cmsPage'} diff --git a/mongoengine/connection.py b/mongoengine/connection.py index de66c476..15e07fd5 100644 --- a/mongoengine/connection.py +++ b/mongoengine/connection.py @@ -29,15 +29,13 @@ def _get_db(): raise ConnectionError('Not connected to database') return _db -def connect(db=None, username=None, password=None, **kwargs): +def connect(db, username=None, password=None, **kwargs): """Connect to the database specified by the 'db' argument. Connection settings may be provided here as well if the database is not running on the default port on localhost. If authentication is needed, provide username and password arguments as well. """ global _db - if db is None: - raise TypeError('"db" argument must be provided to connect()') _connection_settings.update(kwargs) connection = _get_connection()