motor

Go to file

A. Jesse Jiryu Davis dcfbf2627e BUMP 0.1		2013-03-06 14:22:29 -05:00
doc	Ban deprecated 'slave_okay' and 'safe' kwargs everywhere	2013-03-06 13:27:28 -05:00
motor	BUMP 0.1	2013-03-06 14:22:29 -05:00
synchro	Fix up synchrotest a little more	2013-03-06 13:46:09 -05:00
test	Don't test GridFS with slave_okay	2013-03-06 13:52:14 -05:00
.gitignore	Update .gitignore	2013-02-25 11:42:10 -05:00
.travis.yml	Also test Python 3.2 in Travis, not just 3.3	2013-02-25 17:41:56 -05:00
CONTRIBUTING.rst	'python setup.py test' is now how to run the tests, not 'setup.py nosetests'	2013-01-23 17:03:31 -05:00
distribute_setup.py	Use distribute_setup if needed	2013-02-26 08:50:21 -05:00
LICENSE	Initial import from my fork of PyMongo	2013-01-15 14:07:09 -05:00
MANIFEST.in	Initial import from my fork of PyMongo	2013-01-15 14:07:09 -05:00
README.rst	A hack to run subset of test suite in Python 3	2013-03-05 14:54:34 -05:00
requirements.txt	Fix requirements.txt	2013-01-24 14:24:45 -05:00
setup.cfg	Run 2to3'ed tests under Python 3	2013-01-24 13:42:55 -05:00
setup.py	BUMP 0.1	2013-03-06 14:22:29 -05:00
tox.ini	We should test Py3.2 in tox, too	2013-03-04 11:44:17 -05:00

README.rst

=====
Motor
=====

.. image:: https://raw.github.com/mongodb/motor/master/doc/_static/motor.png

:Info: Motor is a full-featured, non-blocking MongoDB_ driver for Python
    Tornado_ applications.
:Author: A\. Jesse Jiryu Davis

.. image:: https://travis-ci.org/mongodb/motor.png
        :target: https://travis-ci.org/mongodb/motor

About
=====

Motor presents a Tornado_ callback-based API for non-blocking access to
MongoDB. The source is `on GitHub <https://github.com/mongodb/motor>`_ and the
docs are on ReadTheDocs_.

    "Motor uses a clever greenlet-based approach to fully support both
    synchronous and asynchronous interfaces from a single codebase. It's great
    to see companies like 10gen produce first-party asynchronous drivers for
    their products."

    --*Ben Darnell, Tornado maintainer*

Issues / Questions / Feedback
=============================

Any issues with, questions about, or feedback for Motor should be sent to the
mongodb-user list on Google Groups. For confirmed issues or feature requests,
open a case on `jira <http://jira.mongodb.org>`_ in the "MOTOR" project.

Installation
============

  $ pip install motor

Dependencies
============

Motor works in all the environments officially supported by Tornado_. It
requires:

* Unix, including Mac OS X. Microsoft Windows is not officially supported.
* PyMongo_
* Tornado_
* `Greenlet <http://pypi.python.org/pypi/greenlet>`_
* CPython 2.5, 2.6, 2.7, 3.2, or 3.3
* Although Motor works with PyPy 1.9, limitations with greenlets and PyPy's
  JIT compiler make PyPy applications that use Motor too slow to use. We
  eagerly await improvements in PyPy 2.0.

Additional dependencies are:

- (to generate documentation) sphinx_
- (to run tests) nose_

Documentation
=============

You will need sphinx_ installed to generate the documentation. Documentation
can be generated by running ``python setup.py doc``. Generated documentation
can be found in ``doc/build/html/``. You can read the current docs
at ReadTheDocs_.

Examples
========

See the `examples on ReadTheDocs <https://motor.readthedocs.org/en/latest/examples/index.html>`_
or `Chirp, a dumb Twitter clone <https://github.com/ajdavis/chirp>`_.

Testing
=======

The easiest way to run the tests is to install nose_ and run ``nosetests``
in the root of the distribution.

You can run all the tests in Python 3 with ``python setup.py nosetests``. Due
to a `nose bug`_, running a subset of the tests in Python 3 is complicated.
Build Motor and its tests with Python 3, then ``cd`` to the build directory and
run ``nosetests``::

  $ python3.3 setup.py build --test
  using 2to3
  including test modules
  running build
  running build_py
  creating build/lib/motor
  ...
  $ cd build/lib
  $ nosetests-3.3 test.test_motor_client

.. _PyMongo: http://pypi.python.org/pypi/pymongo/

.. _MongoDB: http://mongodb.org/

.. _Tornado: http://tornadoweb.org/

.. _ReadTheDocs: http://motor.readthedocs.org/

.. _sphinx: http://sphinx.pocoo.org/

.. _nose: http://somethingaboutorange.com/mrl/projects/nose/

.. _nose bug: https://github.com/nose-devs/nose/issues/556