Welcome to TxMongo’s documentation!¶
What is TxMongo¶
TxMongo is a pure-Python Twisted MongoDB client library that implements:
- Asynchronous client driver to MongoDB
Quick Usage Example¶
from OpenSSL import SSL
from txmongo.connection import ConnectionPool
from twisted.internet import defer, reactor, ssl
class ServerTLSContext(ssl.DefaultOpenSSLContextFactory):
def __init__(self, *args, **kw):
kw['sslmethod'] = SSL.TLSv1_METHOD
ssl.DefaultOpenSSLContextFactory.__init__(self, *args, **kw)
@defer.inlineCallbacks
def example():
tls_ctx = ServerTLSContext(privateKeyFileName='./mongodb.key', certificateFileName='./mongodb.crt')
mongodb_uri = "mongodb://localhost:27017"
mongo = yield ConnectionPool(mongodb_uri, ssl_context_factory=tls_ctx)
foo = mongo.foo # `foo` database
test = foo.test # `test` collection
# fetch some documents
docs = yield test.find(limit=10)
for doc in docs:
print doc
if __name__ == '__main__':
example().addCallback(lambda ign: reactor.stop())
reactor.run()
User’s Guide¶
txmongo package¶
Submodules¶
txmongo.collection module¶
-
class
txmongo.collection.
Collection
(database, name)[source]¶ Bases:
object
-
find_with_cursor
(spec=None, skip=0, limit=0, fields=None, filter=None, **kwargs)[source]¶ find method that uses the cursor to only return a block of results at a time. Arguments are the same as with find() returns deferred that results in a tuple: (docs, deferred) where docs are the current page of results and deferred results in the next tuple. When the cursor is exhausted, it will return the tuple ([], None)
-
txmongo.connection module¶
-
class
txmongo.connection.
ConnectionPool
(uri='mongodb://127.0.0.1:27017', pool_size=1, ssl_context_factory=None)[source]¶ Bases:
object
-
uri
¶
-
-
txmongo.connection.
MongoConnectionPool
¶ alias of
MongoConnection
-
txmongo.connection.
lazyMongoConnection
¶ alias of
MongoConnection
-
txmongo.connection.
lazyMongoConnectionPool
¶ alias of
MongoConnection
txmongo.database module¶
txmongo.dbref module¶
Tools for manipulating DBRefs (references to MongoDB documents).
-
class
txmongo.dbref.
DBRef
(collection, id, database=None)[source]¶ Bases:
object
A reference to a document stored in a Mongo database.
-
as_doc
()[source]¶ Get the SON document representation of this DBRef.
Generally not needed by application developers
-
collection
¶ Get the name of this DBRef’s collection as unicode.
-
database
¶ Get the name of this DBRef’s database.
Returns None if this DBRef doesn’t specify a database.
New in version 1.1.1.
-
id
¶ Get this DBRef’s _id.
-
txmongo.filter module¶
-
txmongo.filter.
GEO2D
(keys)[source]¶ Two-dimensional geospatial index http://www.mongodb.org/display/DOCS/Geospatial+Indexing
-
txmongo.filter.
GEO2DSPHERE
(keys)[source]¶ Two-dimensional geospatial index http://www.mongodb.org/display/DOCS/Geospatial+Indexing
-
txmongo.filter.
GEOHAYSTACK
(keys)[source]¶ Bucket-based geospatial index http://www.mongodb.org/display/DOCS/Geospatial+Haystack+Indexing
-
class
txmongo.filter.
explain
[source]¶ Bases:
txmongo.filter._QueryFilter
Returns an explain plan for the query.
txmongo.gridfs module¶
txmongo.protocol module¶
Low level connection to Mongo.
This module contains the wire protocol implementation for txmongo. The various constants from the protocol are available as constants.
This implementation requires pymongo so that as much of the implementation can be shared. This includes BSON encoding and decoding as well as Exception types, when applicable.
-
class
txmongo.protocol.
Delete
[source]¶ Bases:
txmongo.protocol.Delete
-
class
txmongo.protocol.
Getmore
[source]¶ Bases:
txmongo.protocol.Getmore
-
class
txmongo.protocol.
Insert
[source]¶ Bases:
txmongo.protocol.Insert
-
class
txmongo.protocol.
KillCursors
[source]¶ Bases:
txmongo.protocol.KillCursors
-
class
txmongo.protocol.
MongoProtocol
[source]¶ Bases:
txmongo.protocol.MongoServerProtocol
,txmongo.protocol.MongoClientProtocol
-
connectionLost
(reason=<twisted.python.failure.Failure <class 'twisted.internet.error.ConnectionDone'>>)[source]¶
-
max_wire_version
= None¶
-
min_wire_version
= None¶
-
-
class
txmongo.protocol.
Msg
(len, request_id, response_to, opcode, message)¶ Bases:
tuple
-
len
¶ Alias for field number 0
-
message
¶ Alias for field number 4
-
opcode
¶ Alias for field number 3
-
request_id
¶ Alias for field number 1
-
response_to
¶ Alias for field number 2
-
-
class
txmongo.protocol.
Query
[source]¶ Bases:
txmongo.protocol.Query
-
class
txmongo.protocol.
Reply
[source]¶ Bases:
txmongo.protocol.Reply
-
class
txmongo.protocol.
Update
[source]¶ Bases:
txmongo.protocol.Update
Module contents¶
txmongo._gridfs package¶
Submodules¶
txmongo._gridfs.errors module¶
Exceptions raised by the gridfs
package
-
exception
txmongo._gridfs.errors.
CorruptGridFile
[source]¶ Bases:
txmongo._gridfs.errors.GridFSError
Raised when a file in
GridFS
is malformed.
-
exception
txmongo._gridfs.errors.
GridFSError
[source]¶ Bases:
exceptions.Exception
Base class for all GridFS exceptions.
New in version 1.5.
-
exception
txmongo._gridfs.errors.
NoFile
[source]¶ Bases:
txmongo._gridfs.errors.GridFSError
Raised when trying to read from a non-existent file.
New in version 1.6.
-
exception
txmongo._gridfs.errors.
UnsupportedAPI
[source]¶ Bases:
txmongo._gridfs.errors.GridFSError
Raised when trying to use the old GridFS API.
In version 1.6 of the PyMongo distribution there were backwards incompatible changes to the GridFS API. Upgrading shouldn’t be difficult, but the old API is no longer supported (with no deprecation period). This exception will be raised when attempting to use unsupported constructs from the old API.
New in version 1.6.
txmongo._gridfs.grid_file module¶
Tools for representing files stored in GridFS.
-
class
txmongo._gridfs.grid_file.
GridFile
(*args, **kwargs)[source]¶ Bases:
object
No longer supported.
Changed in version 1.6: The GridFile class is no longer supported.
-
class
txmongo._gridfs.grid_file.
GridIn
(root_collection, **kwargs)[source]¶ Bases:
object
Class to write data to GridFS.
-
chunk_size
¶ Chunk size for this file.
This attribute is read-only.
-
close
(*args, **kwargs)[source]¶ Flush the file and close it.
A closed file cannot be written any more. Calling
close()
more than once is allowed.
-
closed
¶ Is this file closed?
-
content_type
¶ Mime-type for this file.
This attribute can only be set before
close()
has been called.
-
length
¶ Length (in bytes) of this file.
This attribute is read-only and can only be read after
close()
has been called.
-
md5
¶ MD5 of the contents of this file (generated on the server).
This attribute is read-only and can only be read after
close()
has been called.
-
upload_date
¶ Date that this file was uploaded.
This attribute is read-only and can only be read after
close()
has been called.
-
write
(*args, **kwargs)[source]¶ Write data to the file. There is no return value.
data can be either a string of bytes or a file-like object (implementing
read()
).Due to buffering, the data may not actually be written to the database until the
close()
method is called. RaisesValueError
if this file is already closed. RaisesTypeError
if data is not an instance ofstr
or a file-like object.Parameters: - data: string of bytes or file-like object to be written to the file
-
-
class
txmongo._gridfs.grid_file.
GridOut
(root_collection, doc)[source]¶ Bases:
object
Class to read data out of GridFS.
-
aliases
¶ List of aliases for this file.
This attribute is read-only.
-
chunk_size
¶ Chunk size for this file.
This attribute is read-only.
-
content_type
¶ Mime-type for this file.
This attribute is read-only.
-
length
¶ Length (in bytes) of this file.
This attribute is read-only.
-
md5
¶ MD5 of the contents of this file (generated on the server).
This attribute is read-only.
-
metadata
¶ Metadata attached to this file.
This attribute is read-only.
-
name
¶ Name of this file.
This attribute is read-only.
-
read
(*args, **kwargs)[source]¶ Read at most size bytes from the file (less if there isn’t enough data).
The bytes are returned as an instance of
str
. If size is negative or omitted all data is read.Parameters: - size (optional): the number of bytes to read
-
seek
(pos, whence=0)[source]¶ Set the current position of this file.
Parameters: - pos: the position (or offset if using relative positioning) to seek to
- whence (optional): where to seek
from.
os.SEEK_SET
(0
) for absolute file positioning,os.SEEK_CUR
(1
) to seek relative to the current position,os.SEEK_END
(2
) to seek relative to the file’s end.
-
upload_date
¶ Date that this file was first uploaded.
This attribute is read-only.
-
Module contents¶
GridFS is a specification for storing large objects in Mongo.
The gridfs
package is an implementation of GridFS on top of
pymongo
, exposing a file-like interface.
-
class
txmongo._gridfs.
GridFS
(database, collection='fs')[source]¶ Bases:
object
An instance of GridFS on top of a single Database.
-
delete
(file_id)[source]¶ Delete a file from GridFS by
"_id"
.Removes all data belonging to the file with
"_id"
: file_id.Warning
Any processes/threads reading from the file while this method is executing will likely see an invalid/corrupt file. Care should be taken to avoid concurrent reads to a file while it is being deleted.
Parameters: - file_id:
"_id"
of the file to delete
New in version 1.6.
- file_id:
-
get
(*args, **kwargs)[source]¶ Get a file from GridFS by
"_id"
.Returns an instance of
GridOut
, which provides a file-like interface for reading.Parameters: - file_id:
"_id"
of the file to get
New in version 1.6.
- file_id:
-
get_last_version
(filename)[source]¶ Get a file from GridFS by
"filename"
.Returns the most recently uploaded file in GridFS with the name filename as an instance of
GridOut
. RaisesNoFile
if no such file exists.An index on
{filename: 1, uploadDate: -1}
will automatically be created when this method is called the first time.Parameters: - filename:
"filename"
of the file to get
New in version 1.6.
- filename:
-
list
()[source]¶ List the names of all files stored in this instance of
GridFS
.Changed in version 1.6: Removed the collection argument.
-
new_file
(**kwargs)[source]¶ Create a new file in GridFS.
Returns a new
GridIn
instance to which data can be written. Any keyword arguments will be passed through toGridIn()
.Parameters: - **kwargs (optional): keyword arguments for file creation
New in version 1.6.
-
open
(*args, **kwargs)[source]¶ No longer supported.
Changed in version 1.6: The open method is no longer supported.
-
put
(*args, **kwargs)[source]¶ Put data in GridFS as a new file.
Equivalent to doing:
>>> f = new_file(**kwargs) >>> try: >>> f.write(data) >>> finally: >>> f.close()
data can be either an instance of
str
or a file-like object providing aread()
method. Any keyword arguments will be passed through to the created file - seeGridIn()
for possible arguments. Returns the"_id"
of the created file.Parameters: - data: data to be written as a file.
- **kwargs (optional): keyword arguments for file creation
New in version 1.6.
-
Meta¶
Changelog¶
Release 15.0 (2015-05-04)¶
This is the first release using the Twisted versioning method.
API Changes¶
collections.index_information
now mirrors PyMongo’s method.getrequestid
is nowget_request_id
Features¶
- Add support for 2dsphere indexes, see http://docs.mongodb.org/manual/tutorial/build-a-2dsphere-index/
- PEP8 across files as we work through them.
- Authentication reimplemented for ConnectionPool support with multiple DBs.
- Add support for MongoDB 3.0
Bugfixes¶
- Fixed failing tests due to changes in Python in 2.6
- Fixed limit not being respected, which should help performance.
- Find now closes MongoDB cursors.
- Fixed ‘hint’ filter to correctly serialize with double dollar signs.
Improved Documentation¶
- Added, updated and reworked documentation using Sphinx.
- The documentation is now hosted on https://txmongo.readthedocs.org/.
Release 0.6 (2015-01-23)¶
This is the last release in this version scheme, we’ll be switching to the Twisted version scheme in the next release.
API Changes¶
- TxMongo: None
Features¶
- Added SSL support using Twisted SSLContext factory
- Added “find with cursor” like pymongo
- Test coverage is now measured. We’re currently at around 78%.
Bugfixes¶
- Fixed import in database.py
Status and History¶
TxMongo was created by Alexandre Fiori who developed it during the years 2009-2010. From 2010 and onwards mainly bug fixes were added, as Alexandre entered maintance mode with many contributions being made by others. Development picked back up in 2014 by Bret Curtis with Alexandre’s consent and was migrated to Twisted where it is a first-party Twisted library. TxMongo can be found here:
https://github.com/twisted/txmongo
The MongoDB client library functionality is in active use. It is stable and works very well.
Contributions¶
How to Contribute¶
Head over to: https://github.com/twisted/TxMongo and submit your bugs or feature requests. If you wish to contribute code, just fork it, make a branch and send us a pull request. We’ll review it, and push back if necessary.
TxMongo generally follows the coding and documentation standards of the Twisted project.
Contributors¶
- 10gen, Inc
- Alexandre Fiori
- Alexey Palazhchenko (AlekSi)
- Amplidata
- Andre Ferraz
- Bret Curtis
- Carl D’Halluin (Amplidata)
- Christian Hergert
- Dave Peticolas
- Gleicon Moraes
- Ilya Skriblovsky
- Jonathan Stoppani
- Mark L
- Mike Dirolf (mdirolf)
- Renzo Sanchez-Silva (rnz0)
- Runar Petursson
- Silas Sewell
- Stiletto
- Toby Padilla
- Tryggvi Björgvinsson
- Vanderson Mota (chunda)
- flanked
- renzo
- shylent