mongodb/mongo-python-driver
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

faq, installation and contributors list

Browse Source
This commit is contained in:
Mike Dirolf 2009-11-12 15:14:59 -05:00
parent 05ea42c6d4
commit f88c2167a5
6 changed files with 252 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
README.rst
View File

@ -70,44 +70,4 @@ Testing
=======
The easiest way to run the tests is to install `nose <http://somethingaboutorange.com/mrl/projects/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/

16
doc/contributors.rst Normal file
View File

@ -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)

120
doc/faq.rst Normal file
View File

@ -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 <http://twistedmatrix.com/>`_?
------------------------------------------------------------------------------------------------------
Currently there is no great way to use PyMongo in conjunction with
asynchronous socket frameworks like `twisted
<http://twistedmatrix.com/>`_ or `tornado
<http://www.tornadoweb.org/>`_. 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 <http://github.com/fiorix/mongo-async-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
<http://jira.mongodb.org/browse/PYTHON-35>`_ 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
<http://www.mongodb.org/display/DOCS/Django+and+MongoDB>`_ 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.

39
doc/index.rst
View File

@ -1,37 +1,54 @@
PyMongo |release| Documentation
===============================
About
-----
Overview
--------
**PyMongo** is a Python distribution containing tools for working with
`MongoDB <http://www.mongodb.org>`_.
: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
<http://sphinx.pocoo.org/>`_ 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 <contributors>` and
contributions are always encouraged. Contributions can be as simple as
minor tweaks to this documentation. To contribute, fork the project on
`github <http://github.com/mongodb/mongo-python-driver/>`_ and send a
pull request.
Contributions (or fixes) to the documentation are highly encouraged!
To contribute, fork the project on `github
<http://github.com/mongodb/mongo-python-driver/>`_ and send a pull
request.
Contents
--------
Full Contents Tree
------------------
.. toctree::
:maxdepth: 3
installation
tutorial
faq
api/index
contributors
Indices and tables
==================

38
doc/installation.rst Normal file
View File

@ -0,0 +1,38 @@
Installing / Upgrading
======================
.. highlight:: bash
**PyMongo** is in the `Python Package Index
<http://pypi.python.org/pypi/pymongo/>`_. To install PyMongo using
`setuptools <http://pypi.python.org/pypi/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
<http://www.mongodb.org/display/DOCS/PyMongo+and+mod_wsgi>`_, 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

51
doc/tutorial.rst
View File

@ -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
<http://www.mongodb.org/display/DOCS/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 <http://www.mongodb.org/display/DOCS/Indexes>`_
MongoDB documentation on indexes.