Flask-PyMongo

MongoDB 是一个开源的数据库，它存储着灵活的类-JSON 的“文档”。与关系数据库中的数据行相反，它能够存储任何的数字，名称，或者复杂的层级结构。Python 开发者可以考虑把 MongoDB 作为一个持久化，可搜索的 Python 字典的“仓库”(实际上，这是如何用 PyMongo 来表示 MongoDB 中的“文档”)。

Flask-PyMongo 架起来 Flask 和 PyMongo 之间的桥梁，因此你能够使用 Flask 正常的机制去配置和连接 MongoDB。

快速入门

首先，安装 Flask-PyMongo:

$ pip install Flask-PyMongo

Flask-PyMongo 的各种依赖，比如，最新版本的 Flask（0.8或者以上）以及 PyMongo（2.4或者以上） ，也会为你安装的。Flask-PyMongo 是兼容 Python 2.6, 2.7, 和 3.3 版本并且通过测试。

接着，在你的代码中添加一个 PyMongo:

from flask import Flask
from flask.ext.pymongo import PyMongo

app = Flask(__name__)
mongo = PyMongo(app)

PyMongo 连接运行在本机上且端口为 27017 的 MongoDB 服务器，并且假设默认的数据库名为 app.name (换而言之，你可以使用传入到 Flask 中的任何数据库名)。这个数据库能够作为 db 属性被导入。

你可以在视图中直接使用 db :

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

Helpers

Flask-PyMongo 提供一些通用任务的现成方法:

Collection.find_one_or_404(*args, **kwargs)

Find and return a single document, or raise a 404 Not Found exception if no document matches the query spec. See find_one() for details.

@app.route('/user/<username>')
def user_profile(username):
    user = mongo.db.users.find_one_or_404({'_id': username})
    return render_template('user.html',
        user=user)

PyMongo.send_file(filename, base='fs', version=-1, cache_for=31536000)

Return an instance of the response_class containing the named file, and implement conditional GET semantics (using make_conditional()).

@app.route('/uploads/<path:filename>')
def get_upload(filename):
    return mongo.send_file(filename)

Parameters:

• filename (str) – the filename of the file to return
• base (str) – the base name of the GridFS collections to use
• version (bool) – if positive, return the Nth revision of the file identified by filename; if negative, return the Nth most recent revision. If no such version exists, return with HTTP status 404.
• cache_for (int) – number of seconds that browsers should be instructed to cache responses

PyMongo.save_file(filename, fileobj, base='fs', content_type=None)

Save the file-like object to GridFS using the given filename. Returns None.

@app.route('/uploads/<path:filename>', methods=['POST'])
def save_upload(filename):
    mongo.save_file(filename, request.files['file'])
    return redirect(url_for('get_upload', filename=filename))

Parameters:

• filename (str) – the filename of the file to return
• fileobj (file) – the file-like object to save
• base (str) – base the base name of the GridFS collections to use
• content_type (str) – the MIME content-type of the file. If None, the content-type is guessed from the filename using guess_type()

class flask_pymongo.BSONObjectIdConverter(map)

A simple converter for the RESTful URL routing system of Flask.

@app.route('/<ObjectId:task_id>')
def show_task(task_id):
    task = mongo.db.tasks.find_one_or_404(task_id)
    return render_template('task.html', task=task)

Valid object ID strings are converted into ObjectId objects; invalid strings result in a 404 error. The converter is automatically registered by the initialization of PyMongo with keyword ObjectId.

Configuration

PyMongo 直接支持如下的配置项:

MONGO_URI	一个 MongoDB 网址 用于其他配置项。
MONGO_HOST	你的 MongoDB 服务器的主机名或者 IP 地址。 默认：”localhost”。
MONGO_PORT	你的 MongoDB 服务器的端口。默认：27017。
MONGO_AUTO_START_REQUEST	为了禁用 PyMongo 2.2 的 “auto start request” 行为， 设置成 False。 (请见 MongoClient)。 默认：True。
MONGO_MAX_POOL_SIZE	(可选): PyMongo 连接池中保持空闲连接的最大数量。 默认：PyMongo 默认值。
MONGO_SOCKET_TIMEOUT_MS	(可选): (整型) 在超时前套接字允许一个发送或者接收的耗时(毫秒)。 默认: PyMongo 默认值。
MONGO_CONNECT_TIMEOUT_MS	(可选): (整型) 在超时前允许一个连接的耗时(毫秒)。 默认: PyMongo 默认值。
MONGO_DBNAME	可用于作为 db 属性的数据库名。默认： app.name。
MONGO_USERNAME	用于认证的用户名。默认：None。
MONGO_PASSWORD	用于认证的密码。默认：None。
MONGO_REPLICA_SET	设置成连接的备份集的名称； 这必须匹配到备份集的内部名，由 http://www.mongodb.org/display/DOCS/Replica+Set+Commands#ReplicaSetCommands-isMaster 命令)决定的。默认：None。
MONGO_READ_PREFERENCE	决定如何读取路由到备份集的成员。 必须是定义在 pymongo.read_preferences.ReadPreference 中的一个常量 或者一个字符串名称。
MONGO_DOCUMENT_CLASS	告诉 pymongo 返回定制的对象而不是默认的字典， 比如 bson.son.SON。 默认： dict。

当 PyMongo 或者 init_app() 仅仅只有一个参数调用的时候 (the Flask 实例)，会假设配置值的前缀是 MONGO；能够用 config_prefix 来覆盖这个前缀。

这个技术能够用于连接多个数据库或者数据服务器:

app = Flask(__name__)

# connect to MongoDB with the defaults
mongo1 = PyMongo(app)

# connect to another MongoDB database on the same host
app.config['MONGO2_DBNAME'] = 'dbname_two'
mongo2 = PyMongo(app, config_prefix='MONGO2')

# connect to another MongoDB server altogether
app.config['MONGO3_HOST'] = 'another.host.example.com'
app.config['MONGO3_PORT'] = 27017
app.config['MONGO3_DBNAME'] = 'dbname_three'
mongo3 = PyMongo(app, config_prefix='MONGO3')

你应该需要注意一些自动配置的设置:

tz_aware:

Flask-PyMongo 一直使用通用时区的 datetime 对象。这是因为当建立连接的时候它设置 tz_aware 参数为 True。从 MongoDB 返回的 datetime 对象一直是 UTC。

safe:

Flask-PyMongo 默认地设置成 “safe” 模式，这会导致 save(), insert(), update(), 和 remove() 在返回前一直等待着服务器的应答。你可以在调用的时候通过传入 safe=False 参数到任何一个受影响的方法中来覆盖它。

API

常量

flask_pymongo.ASCENDING = 1

Ascending sort order.

flask_pymongo.DESCENDING = -1

Descending sort order.

类

class flask_pymongo.PyMongo(app=None, config_prefix='MONGO')

Automatically connects to MongoDB using parameters defined in Flask configuration.

cx

The automatically created Connection or ReplicaSetConnection object.

db

The automatically created Database object corresponding to the provided MONGO_DBNAME configuration parameter.

init_app(app, config_prefix='MONGO')

Initialize the app for use with this PyMongo. This is called automatically if app is passed to __init__().

The app is configured according to the configuration variables PREFIX_HOST, PREFIX_PORT, PREFIX_DBNAME, PREFIX_AUTO_START_REQUEST, PREFIX_REPLICA_SET, PREFIX_READ_PREFERENCE, PREFIX_USERNAME, PREFIX_PASSWORD, and PREFIX_URI where “PREFIX” defaults to “MONGO”. If PREFIX_URL is set, it is assumed to have all appropriate configurations, and the other keys are overwritten using their values as present in the URI.

Parameters:

• app (flask.Flask) – the application to configure for use with this PyMongo
• config_prefix (str) – determines the set of configuration variables used to configure this PyMongo

save_file(filename, fileobj, base='fs', content_type=None)

Save the file-like object to GridFS using the given filename. Returns None.

@app.route('/uploads/<path:filename>', methods=['POST'])
def save_upload(filename):
    mongo.save_file(filename, request.files['file'])
    return redirect(url_for('get_upload', filename=filename))

Parameters:

• filename (str) – the filename of the file to return
• fileobj (file) – the file-like object to save
• base (str) – base the base name of the GridFS collections to use
• content_type (str) – the MIME content-type of the file. If None, the content-type is guessed from the filename using guess_type()

send_file(filename, base='fs', version=-1, cache_for=31536000)

Return an instance of the response_class containing the named file, and implement conditional GET semantics (using make_conditional()).

@app.route('/uploads/<path:filename>')
def get_upload(filename):
    return mongo.send_file(filename)

Parameters:

• filename (str) – the filename of the file to return
• base (str) – the base name of the GridFS collections to use
• version (bool) – if positive, return the Nth revision of the file identified by filename; if negative, return the Nth most recent revision. If no such version exists, return with HTTP status 404.
• cache_for (int) – number of seconds that browsers should be instructed to cache responses

class flask_pymongo.wrappers.Collection(database, name, create=False, **kwargs)

Custom sub-class of pymongo.collection.Collection which adds Flask-specific helper methods.

find_one_or_404(*args, **kwargs)

Find and return a single document, or raise a 404 Not Found exception if no document matches the query spec. See find_one() for details.

@app.route('/user/<username>')
def user_profile(username):
    user = mongo.db.users.find_one_or_404({'_id': username})
    return render_template('user.html',
        user=user)

封装

These classes exist solely in order to make expressions such as mongo.db.foo.bar evaluate to a Collection instance instead of a pymongo.collection.Collection instance. They are documented here solely for completeness.

class flask_pymongo.wrappers.MongoClient(host=None, port=None, max_pool_size=100, document_class=<type 'dict'>, tz_aware=False, _connect=True, **kwargs)

Returns instances of flask_pymongo.wrappers.Database instead of pymongo.database.Database when accessed with dot notation.

class flask_pymongo.wrappers.MongoReplicaSetClient(hosts_or_uri=None, max_pool_size=100, document_class=<type 'dict'>, tz_aware=False, _connect=True, **kwargs)

Returns instances of flask_pymongo.wrappers.Database instead of pymongo.database.Database when accessed with dot notation.

class flask_pymongo.wrappers.Database(connection, name)

Returns instances of flask_pymongo.wrappers.Collection instead of pymongo.collection.Collection when accessed with dot notation.

历史和贡献

更新: - 0.4.0: October 19, 2015

• Flask-Pymongo is now compatible with pymongo 3.0+: #63.

• 0.3.1: April 9, 2015
  • Flask-PyMongo is now tested against Python 2.6, 2.7, 3.3, and 3.4.
  • Flask-PyMongo installation now no longer depends on nose.
  • #58 Update requirements for PyMongo 3.x (Emmanuel Valette).
  • #43 Ensure error is raised when URI database name is parsed as ‘None’ (Ben Jeffrey).
  • #50 Fix a bug in read preference handling (Kevin Funk).
  • #46 Cannot use multiple replicaset instances which run on different ports (Mark Unsworth).
  • #30 ConfiguationError with MONGO_READ_PREFERENCE (Mark Unsworth).
• 0.3.0: July 4, 2013
  • This is a minor version bump which introduces backwards breaking changes! Please read these change notes carefully.
  • Removed read preference constants from Flask-PyMongo; to set a read preference, use the string name or import contants directly from pymongo.read_preferences.ReadPreference.
  • #22 (partial) Add support for MONGO_SOCKET_TIMEOUT_MS and MONGO_CONNECT_TIMEOUT_MS options (ultrabug).
  • #27 (partial) Make Flask-PyMongo compatible with Python 3 (Vizzy).
• 0.2.1: December 22, 2012
  • #19 Added MONGO_DOCUMENT_CLASS config option (jeverling).
• 0.2.0: December 15, 2012
  • This is a minor version bump which may introduce backwards breaking changes! Please read these change notes carefully.
  • #17 Now using PyMongo 2.4’s MongoClient and MongoReplicaSetClient objects instead of Connection and ReplicaSetConnection classes (tang0th).
  • #17 Now requiring at least PyMongo version 2.4 (tang0th).
  • #17 The wrapper class flask_pymongo.wrappers.Connection is renamed to flask_pymongo.wrappers.MongoClient (tang0th).
  • #17 The wrapper class flask_pymongo.wrappers.ReplicaSetConnection is renamed to flask_pymongo.wrappers.MongoReplicaSetClient (tang0th).
  • #18 MONGO_AUTO_START_REQUEST now defaults to False when connecting using a URI.
• 0.1.4: December 15, 2012
  • #15 Added support for MONGO_MAX_POOL_SIZE (Fabrice Aneche)
• 0.1.3: September 22, 2012
  • Added support for configuration from MongoDB URI.
• 0.1.2: June 18, 2012
  • Updated wiki example application
  • #14 Added examples and docs to PyPI package.
• 0.1.1: May 26, 2012
  • Added support for PyMongo 2.2’s “auto start request” feature, by way of the MONGO_AUTO_START_REQUEST configuration flag.
  • #13 Added BSONObjectIdConverter (Christoph Herr)
  • #12 Corrected documentation typo (Thor Adam)
• 0.1: December 21, 2011
  • Initial Release

贡献者:

• jeverling
• tang0th
• Fabrice Aneche
• Thor Adam
• Christoph Herr
• Mark Unsworth
• Kevin Funk
• Ben Jeffrey
• Emmanuel Valette