Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/marirs/quart-motor

Motor support for Quart applications
https://github.com/marirs/quart-motor

asyncio flask mongodb motor pymongo python3 quart quart-motor

Last synced: about 2 months ago
JSON representation

Motor support for Quart applications

Awesome Lists containing this project

README

        

Quart-Motor
=============
[![Build Status](https://travis-ci.org/marirs/quart-motor.svg?branch=master)](https://travis-ci.org/marirs/quart-motor)
[![codecov](https://codecov.io/gh/marirs/quart-motor/branch/master/graph/badge.svg)](https://codecov.io/gh/marirs/quart-motor)
[![GitHub license](https://img.shields.io/badge/license-BSD%203-brightgreen)](https://github.com/marirs/quart-motor/blob/master/LICENSE)
![PyPI - Downloads](https://img.shields.io/pypi/dd/Quart-Motor)

`MongoDB ` is an open source database that stores
flexible JSON-like "documents," which can have any number, name, or
hierarchy of fields within, instead of rows of data as in a relational
database. Python developers can think of MongoDB as a persistent, searchable
repository of Python dictionaries (and, in fact, this is how `PyMongo
` represents MongoDB documents).

Quart-Motor bridges Quart and Motor and provides some convenience
helpers.

Quickstart
----------

First, install Quart-Motor:

```bash
$ pip install Quart-Motor
```

Next, add a :class:`~quart_motor.Motor` to your code:

```python
from quart import Quart
from quart_motor import Motor

app = Quart(__name__)
app.config["MONGO_URI"] = "mongodb://localhost:27017/myDatabase"
mongo = Motor(app)
```
:class:`~quart_motor.Motor` connects to the MongoDB server running on
port 27017 on localhost, to the database named ``myDatabase``. This database
is exposed as the :attr:`~quart_motor.Motor.db` attribute.

You can use :attr:`~quart_motor.Motor.db` directly in views:

```python

@app.route("/")
def home_page():
online_users = mongo.db.users.find({"online": True})
return render_template("index.html",
online_users=online_users)
```

Compatibility
-------------

Quart-Motor depends on recent versions of Quart, Motor and PyMongo, where "recent"
is defined to mean "was released in the last 3 years". Quart-Motor *may*
work with older versions, but compatibility fixes for older versions will
not be accepted, and future changes may break compatibility in older
versions.

Quart-Motor is tested against `supported versions
`_ of MongoDB, 3.5+.

Quart-Motor works very well with
- `uvicorn` asgi
- `hypercorn` asgi

Quart-Motor is tested against `Python 3.7+` versions.

Helpers
-------

Quart-Motor provides helpers for some common tasks:

.. automethod:: quart_motor.wrappers.Collection.find_one_or_404

.. automethod:: quart_motor.Motor.send_file

.. automethod:: quart_motor.Motor.save_file

.. autoclass:: quart_motor.helpers.BSONObjectIdConverter

.. autoclass:: quart_motor.helpers.JSONEncoder

Configuration
-------------

You can configure Quart-Motor either by passing a `MongoDB URI
`_ to the
:class:`~quart_motor.Motor` constructor, or assigning it to the
``MONGO_URI`` `Quart configuration variable
`_

The :class:`~quart_motor.Motor` instnace also accepts these additional
customization options:

* ``json_options``, a :class:`~bson.json_util.JSONOptions` instance which
controls the JSON serialization of MongoDB objects when used with
:func:`~quart.json.jsonify`.

You may also pass additional keyword arguments to the ``Motor``
constructor. These are passed directly through to the underlying
:class:`~motor.motor_asyncio.AsyncIOMotorClient` object.

Note:

By default, Quart-Motor sets the ``connect`` keyword argument to
``False``, to prevent Motor from connecting immediately. Motor
itself `is not fork-safe
`_,
and delaying connection until the app is actually used is necessary to
avoid issues. If you wish to change this default behavior, pass
``connect=True`` as a keyword argument to ``Motor``.

You can create multiple ``Motor`` instances, to connect to multiple
databases or database servers:

```python

app = Quart(__name__)

# connect to MongoDB with the defaults
mongo1 = Motor(app, uri="mongodb://localhost:27017/databaseOne")

# connect to another MongoDB database on the same host
mongo2 = Motor(app, uri="mongodb://localhost:27017/databaseTwo")

# connect to another MongoDB server altogether
mongo3 = Motor(app, uri="mongodb://another.host:27017/databaseThree")
```
Each instance is independent of the others and shares no state.

API
===

Classes
-------

.. autoclass:: quart_motor.Motor
:members:

.. attribute:: cx

The :class:`~quart_motor.wrappers.AsyncIOMotorClient` connected to the
MongoDB server.

.. attribute:: db

The :class:`~quart_motor.wrappers.AsyncIOMotorDatabase` if the URI used
named a database, and ``None`` otherwise.

Wrappers
--------

Quart-Motor wraps Motor's :class:`~motor.motor_asyncio.AsyncIOMotorClient`,
:class:`~motor.motor_asyncio.AsyncIOMotorDatabase`, and
:class:`~motor.motor_asyncio.AsyncIOMotorCollection` classes, and overrides their
attribute and item accessors. Wrapping the Motor classes in this way lets
Quart-Motor add methods to ``AsyncIOMotorCollection`` while allowing user code to use
MongoDB-style dotted expressions.

```python

>>> type(mongo.cx)

>>> type(mongo.db)

>>> type(mongo.db.some_collection)

```
.. autoclass:: quart_motor.wrappers.AsyncIOMotorCollection(...)
:members:

History and Contributors
------------------------

Changes:

- 2.4.0: Unreleased

- Flask-PyMongo port as released of Flask-PyMongo.

Flask-PyMongo:

-

Contributors of Flask-PyMongo:

- `jeverling `
- `tang0th `
- `Fabrice Aneche `
- `Thor Adam `
- `Christoph Herr `
- `Mark Unsworth `
- `Kevin Funk `
- `Ben Jeffrey `
- `Emmanuel Valette `
- `David Awad `
- `Robson Roberto Souza Peixoto `
- `juliascript `
- `Henrik Blidh `
- `jobou `
- `Craig Davis `
- `ratson `
- `Abraham Toriz Cruz `
- `MinJae Kwon `
- `yarobob `
- `Andrew C. Hawkins `

Contributors of Quart-Motor

- `Sriram `
- `Kiran `