Flask PyMongo 中文文檔 · Flask 擴展文檔匯總

# Flask-PyMongo [MongoDB](http://www.mongodb.org/) 是一個開源的數據庫，它存儲著靈活的類-JSON 的“文檔”。與關系數據庫中的數據行相反，它能夠存儲任何的數字，名稱，或者復雜的層級結構。Python 開發者可以考慮把 MongoDB 作為一個持久化，可搜索的 Python 字典的“倉庫”(實際上，這是如何用 [PyMongo](http://api.mongodb.org/python/current/) 來表示 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`](#flask_pymongo.PyMongo "flask_pymongo.PyMongo"): ``` from flask import Flask from flask.ext.pymongo import PyMongo app = Flask(__name__) mongo = PyMongo(app) ``` [`PyMongo`](#flask_pymongo.PyMongo "flask_pymongo.PyMongo") 連接運行在本機上且端口為 27017 的 MongoDB 服務器，并且假設默認的數據庫名為 `app.name` (換而言之，你可以使用傳入到 `Flask` 中的任何數據庫名)。這個數據庫能夠作為 [`db`](#flask_pymongo.PyMongo.db "flask_pymongo.PyMongo.db") 屬性被導入。你可以在視圖中直接使用 [`db`](#flask_pymongo.PyMongo.db "flask_pymongo.PyMongo.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()`](http://api.mongodb.org/python/current/api/pymongo/collection.html#pymongo.collection.Collection.find_one "(in PyMongo v3.1.1)") 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_](http://docs.python.org/library/functions.html#str "(in Python v2.7)")) – the filename of the file to return * **base** ([_str_](http://docs.python.org/library/functions.html#str "(in Python v2.7)")) – the base name of the GridFS collections to use * **version** ([_bool_](http://docs.python.org/library/functions.html#bool "(in Python v2.7)")) – 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_](http://docs.python.org/library/functions.html#int "(in Python v2.7)")) – 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_](http://docs.python.org/library/functions.html#str "(in Python v2.7)")) – the filename of the file to return * **fileobj** ([_file_](http://docs.python.org/library/functions.html#file "(in Python v2.7)")) – the file-like object to save * **base** ([_str_](http://docs.python.org/library/functions.html#str "(in Python v2.7)")) – base the base name of the GridFS collections to use * **content_type** ([_str_](http://docs.python.org/library/functions.html#str "(in Python v2.7)")) – the MIME content-type of the file. If `None`, the content-type is guessed from the filename using [`guess_type()`](http://docs.python.org/library/mimetypes.html#mimetypes.guess_type "(in Python v2.7)") `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`](http://api.mongodb.org/python/current/api/bson/objectid.html#bson.objectid.ObjectId "(in PyMongo v3.1.1)") objects; invalid strings result in a 404 error. The converter is automatically registered by the initialization of [`PyMongo`](#flask_pymongo.PyMongo "flask_pymongo.PyMongo") with keyword `ObjectId`. ## Configuration [`PyMongo`](#flask_pymongo.PyMongo "flask_pymongo.PyMongo") 直接支持如下的配置項: | | | | --- | --- | | `MONGO_URI` | 一個 [MongoDB 網址](http://www.mongodb.org/display/DOCS/Connections#Connections-StandardConnectionStringFormat) 用于其他配置項。 | | `MONGO_HOST` | 你的 MongoDB 服務器的主機名或者 IP 地址。默認：”localhost”。 | | `MONGO_PORT` | 你的 MongoDB 服務器的端口。默認：27017。 | | `MONGO_AUTO_START_REQUEST` | 為了禁用 PyMongo 2.2 的 “auto start request” 行為，設置成 `False`。 (請見 [`MongoClient`](http://api.mongodb.org/python/current/api/pymongo/mongo_client.html#pymongo.mongo_client.MongoClient "(in PyMongo v3.1.1)"))。默認：`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](http://www.mongodb.org/display/DOCS/Replica+Set+Commands#ReplicaSetCommands-isMaster) 命令)決定的。默認：`None`。 | | `MONGO_READ_PREFERENCE` | 決定如何讀取路由到備份集的成員。必須是定義在 [`pymongo.read_preferences.ReadPreference`](http://api.mongodb.org/python/current/api/pymongo/read_preferences.html#pymongo.read_preferences.ReadPreference "(in PyMongo v3.1.1)") 中的一個常量或者一個字符串名稱。 | | `MONGO_DOCUMENT_CLASS` | 告訴 pymongo 返回定制的對象而不是默認的字典，比如 `bson.son.SON`。默認： `dict`。 | 當 [`PyMongo`](#flask_pymongo.PyMongo "flask_pymongo.PyMongo") 或者 [`init_app()`](#flask_pymongo.PyMongo.init_app "flask_pymongo.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`](http://docs.python.org/library/datetime.html#datetime.datetime "(in Python v2.7)") 對象。這是因為當建立連接的時候它設置 `tz_aware` 參數為 `True`。從 MongoDB 返回的 [`datetime`](http://docs.python.org/library/datetime.html#datetime.datetime "(in Python v2.7)") 對象一直是 UTC。 `safe`: Flask-PyMongo 默認地設置成 “safe” 模式，這會導致 [`save()`](http://api.mongodb.org/python/current/api/pymongo/collection.html#pymongo.collection.Collection.save "(in PyMongo v3.1.1)"), [`insert()`](http://api.mongodb.org/python/current/api/pymongo/collection.html#pymongo.collection.Collection.insert "(in PyMongo v3.1.1)"), [`update()`](http://api.mongodb.org/python/current/api/pymongo/collection.html#pymongo.collection.Collection.update "(in PyMongo v3.1.1)"), 和 [`remove()`](http://api.mongodb.org/python/current/api/pymongo/collection.html#pymongo.collection.Collection.remove "(in PyMongo v3.1.1)") 在返回前一直等待著服務器的應答。你可以在調用的時候通過傳入 `safe=False` 參數到任何一個受影響的方法中來覆蓋它。