diff --git a/README.rst b/README.rst index fff4e8438..4e92e3308 100644 --- a/README.rst +++ b/README.rst @@ -70,44 +70,4 @@ Testing ======= The easiest way to run the tests is to install `nose `_ (**easy_install nose**) and run **nosetests** or **python setup.py test** in the root of the distribution. Tests are located in the *test/* directory. -Credits -======= -Thanks to (in no particular order) (if you belong here and are missing please let us know): - -- moe at mbox dot bz: - - - Turn off nagle - -- Michael Stephens (mikejs): - - - Seek and tell for read mode GridFile - -- Joakim Sernbrant (serbaut): - - - Fix decref bug in tuple encoder - - Hex __repr__ and __str__ for ObjectId - - Performance optimizations for writing large files to GridFS - - Some updates to the README - - Fix for ObjectId + multiprocessing - -- Alexander Artemenko (svetlyak40wt): - - - Fix spurious errors in thread test - -- Mathias Stearn (RedBeard0531): - - - Add support for finalize in group() - -- Fajran Iman Rusadi (fajran): - - - Add Debian control files - -- Brad Clements (bkc): - - - A fix for Python 2.3 compatability - -- Andrey Fedorov (andreyf) - - - Added __hash__ methods to DBRef and ObjectId - .. _sphinx http://sphinx.pocoo.org/ diff --git a/doc/contributors.rst b/doc/contributors.rst new file mode 100644 index 000000000..ba77d28ef --- /dev/null +++ b/doc/contributors.rst @@ -0,0 +1,16 @@ +Contributors +============ +The following is a list of people who have contributed to +**PyMongo**. If you belong here and are missing please let us know +(or send a pull request after adding yourself to the list): + +- Mike Dirolf (mdirolf) +- Jim Jones +- Eliot Horowitz (erh) +- Michael Stephens (mikejs) +- Joakim Sernbrant (serbaut) +- Alexander Artemenko (svetlyak40wt) +- Mathias Stearn (RedBeard0531) +- Fajran Iman Rusadi (fajran) +- Brad Clements (bkc) +- Andrey Fedorov (andreyf) diff --git a/doc/faq.rst b/doc/faq.rst new file mode 100644 index 000000000..10982c24e --- /dev/null +++ b/doc/faq.rst @@ -0,0 +1,120 @@ +Frequently Asked Questions +========================== + +.. contents:: + +Is PyMongo thread-safe? +----------------------- +PyMongo is thread-safe and even provides built-in connection pooling +for threaded applications. See the documentation for +:class:`~pymongo.connection.Connection`, notably the `pool_size` +parameter. + +How can I use PyMongo with an asynchronous socket library like `twisted `_? +------------------------------------------------------------------------------------------------------ +Currently there is no great way to use PyMongo in conjunction with +asynchronous socket frameworks like `twisted +`_ or `tornado +`_. One way to get the same benefits those +frameworks provide using PyMongo is to write multi-threaded code and +use PyMongo's built in connection pooling. + +There is work in progress towards creating an `asynchronous Python +driver `_ for +MongoDB using the Twisted framework, this project is currently less +stable than PyMongo however. + +What does *OperationFailure* cursor id not valid at server mean? +--------------------------------------------------------------------------------------- +Cursors in MongoDB can timeout on the server if they've been open for +a long time without any operations being performed on them. This can +lead to an :class:`~pymongo.errors.OperationFailure` exception being +raised when attempting to iterate the cursor. + +How do I change the timeout value for cursors? +---------------------------------------------- +MongoDB doesn't support custom timeouts for cursors, but cursor +timeouts can be turned off entirely. Pass ``timeout=False`` to +:meth:`~pymongo.collection.Collection.find`. + +How can I store :mod:`decimal.Decimal` instances? +------------------------------------------------- +MongoDB only supports IEEE 754 floating points - the same as the +Python float type. The only way PyMongo could store Decimal instances +would be to convert them to this standard, so you'd really only be +storing floats anyway - we force users to do this conversion +explicitly so that they are aware that it is happening. + +I'm saving ``9.99`` but when I query my document contains ``9.9900000000000002`` - what's going on here? +-------------------------------------------------------------------------------------------------------- +The database representation is ``9.99`` as an IEEE floating point (which +is common to MongoDB and Python as well as most other modern +languages). The problem is that ``9.99`` cannot be represented exactly +with a double precision floating point - this is true in Python as +well:: + + >>> 9.99 + 9.9900000000000002 + +The result that you get when you save ``9.99`` with PyMongo is exactly the +same as the result you'd get saving it with the JavaScript shell or +any of the other languages (and as the data you're working with when +you type ``9.99`` into a Python program). + +Can you add attribute style access for documents? +------------------------------------------------- +This request has come up a number of times but we've decided not to +implement anything like this. The relevant `jira case +`_ has some information +about the decision, but here is a brief summary: + +1. This will pollute the attribute namespace for documents, so could + lead to subtle bugs / confusing errors when using a key with the + same name as a dictionary method. + +2. The only reason we even use SON objects instead of regular + dictionaries is to maintain key ordering, since the server + requires this for certain operations. So we're hesitant to + needlessly complicate SON (at some point it's hypothetically + possible we might want to revert back to using dictionaries alone, + without breaking backwards compatibility for everyone). + +3. It's easy (and Pythonic) for new users to deal with documents, + since they behave just like dictionaries. If we start changing + their behavior it adds a barrier to entry for new users - another + class to learn. + +What is the correct way to handle time zones with PyMongo? +---------------------------------------------------------- +Currently the correct way is to only save naive +:class:`~datetime.datetime` instances, and to save all dates as +UTC. Unfortunately, Python time zone handling is less than elegant so +it is quite difficult for the driver to do anything smarter than this. + +Something like :mod:`pytz` can be used to convert dates to localtime +after retrieving them from the database. + +How can I save a :mod:`datetime.date` instance? +----------------------------------------------- +PyMongo doesn't support saving :mod:`datetime.date` instances, since +there is no BSON type for dates without times. Rather than having the +driver enforce a convention for converting :mod:`datetime.date` +instances to :mod:`datetime.datetime` instances for you, any +conversion should be performed in your client code. + +How can I use PyMongo from a web framework like Django? +------------------------------------------------------- +.. todo:: move django docs here + +We've written a `short guide +`_ on using +Django and MongoDB. + +How can I use something like Python's :mod:`json` module to encode my documents to JSON? +---------------------------------------------------------------------------------------- +The :mod:`json` module won't work out of the box with all documents +from PyMongo as PyMongo supports some special types (like +:class:`~pymongo.objectid.ObjectId` and :class:`~pymongo.dbref.DBRef`) +that are not supported in JSON. We've added some utilities for working +with :mod:`json` and :mod:`simplejson` in the +:mod:`~pymongo.json_util` module. diff --git a/doc/index.rst b/doc/index.rst index 16706353c..31683b04b 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -1,37 +1,54 @@ PyMongo |release| Documentation =============================== -About ------ +Overview +-------- **PyMongo** is a Python distribution containing tools for working with `MongoDB `_. +:doc:`installation` + Instructions on how to get the distribution. + +:doc:`tutorial` + Start here for a quick overview. + +:doc:`faq` + Some questions that come up often. + +:doc:`api/index` + The complete API documentation, organized by module. + About This Documentation ------------------------ This documentation is generated using the `Sphinx `_ documentation generator. The source files for the documentation are located in the *doc/* directory of the -**PyMongo** distribution. To generate the docs locally do: +**PyMongo** distribution. To generate the docs locally run the +following command from the root directory of the **PyMongo** source: .. code-block:: bash $ python setup.py doc -In the root directory of the **PyMongo** source. +Contributing +------------ +**PyMongo** has a large :doc:`community ` and +contributions are always encouraged. Contributions can be as simple as +minor tweaks to this documentation. To contribute, fork the project on +`github `_ and send a +pull request. -Contributions (or fixes) to the documentation are highly encouraged! -To contribute, fork the project on `github -`_ and send a pull -request. - -Contents --------- +Full Contents Tree +------------------ .. toctree:: :maxdepth: 3 + installation tutorial + faq api/index + contributors Indices and tables ================== diff --git a/doc/installation.rst b/doc/installation.rst new file mode 100644 index 000000000..34427983e --- /dev/null +++ b/doc/installation.rst @@ -0,0 +1,38 @@ +Installing / Upgrading +====================== +.. highlight:: bash + +**PyMongo** is in the `Python Package Index +`_. To install PyMongo using +`setuptools `_ do:: + + $ easy_install pymongo + +To upgrade do:: + + $ easy_install -U pymongo + +If you'd rather install directly from the source (i.e. to stay on the +bleeding edge), check out the latest source from github and install +the driver from the resulting tree:: + + $ git clone git://github.com/mongodb/mongo-python-driver.git pymongo + $ cd pymongo/ + $ python setup.py install + +Installing Without the C Extension +---------------------------------- +By default, the driver attempts to build and install an optional C +extension (used for increasing performance) when it is installed. If +the extension fails to build the driver will be installed anyway but a +warning will be printed. + +.. todo:: move mod_wsgi docs here + +In `certain cases +`_, you +might wish to install the driver without the C extension, even if the +extension builds properly. This can be done using a command line +option to *setup.py*:: + + $ python setup.py --no_ext install diff --git a/doc/tutorial.rst b/doc/tutorial.rst index de1eca9ad..571c568ff 100644 --- a/doc/tutorial.rst +++ b/doc/tutorial.rst @@ -213,7 +213,56 @@ collection:: >>> posts.count() 3 -or just of those posts that match a specific query:: +or just of those documents that match a specific query:: >>> posts.find({"author": "Mike"}).count() 2 + +Range Queries +------------- +MongoDB supports many different types of `advanced queries +`_. As an +example, lets perform a query where we limit results to posts older +than a certain date, but also sort the results by author:: + + >>> d = datetime.datetime(2009, 11, 12, 12) + >>> for post in posts.find({"date": {"$lt": d}}).sort("author"): + ... post + ... + {u'date': datetime.datetime(2009, 11, 10, 10, 45), u'text': u'and pretty easy too!', u'_id': ObjectId('4afc34dee6fb1b16f2000002'), u'author': u'Eliot', u'title': u'MongoDB is fun'} + {u'date': datetime.datetime(2009, 11, 12, 11, 14), u'text': u'Another post!', u'_id': ObjectId('4afc34dee6fb1b16f2000001'), u'author': u'Mike', u'tags': [u'bulk', u'insert']} + +Here we use the special ``"$lt"`` operator to do a range query, and +also call :meth:`~pymongo.cursor.Cursor.sort` to sort the results +by author. + +Indexing +-------- +To make the above query fast we can add a compound index on +``"date"`` and ``"author"``. To start, lets use the +:meth:`~pymongo.cursor.Cursor.explain` method to get some information +about how the query is being performed without the index:: + + >>> posts.find({"date": {"$lt": d}}).sort("author").explain()["cursor"] + u'BasicCursor' + >>> posts.find({"date": {"$lt": d}}).sort("author").explain()["nscanned"] + 3.0 + +We can see that the query is using the *BasicCursor* and scanning over +all 3 documents in the collection. Now let's add a compound index and +look at the same information:: + + >>> from pymongo import ASCENDING, DESCENDING + >>> posts.create_index([("date", DESCENDING), ("author", ASCENDING)]) + u'date_-1_author_1' + >>> posts.find({"date": {"$lt": d}}).sort("author").explain()["cursor"] + u'BtreeCursor date_-1_author_1' + >>> posts.find({"date": {"$lt": d}}).sort("author").explain()["nscanned"] + 2.0 + +Now the query is using a *BtreeCursor* (the index) and only scanning +over the 2 matching documents. + +.. seealso:: + `Indexes `_ + MongoDB documentation on indexes.