txmongo package¶
Submodules¶
txmongo.collection module¶
-
class
txmongo.collection.
Collection
(database, name, write_concern=None, codec_options=None)[source]¶ Bases:
object
Creates new
Collection
objectParameters: - database – the
Database
instance to get collection from - name – the name of the collection to get
- write_concern – An instance of
WriteConcern
. IfNone
,database.write_concern
is used. - codec_options – An instance of
CodecOptions
. IfNone
,database.codec_options
is used.
-
codec_options
¶ Read only access to the
CodecOptions
of this instance.Use
coll.with_options(codec_options=CodecOptions(...))
to change codec options.
-
count
(filter=None, **kwargs)[source]¶ Get the number of documents in this collection.
Parameters: - filter – argument is a query document that selects which documents to count in the collection.
- hint – (keyword only)
hint
instance specifying index to use. - limit (int) – (keyword only) The maximum number of documents to count.
- skip (int) – (keyword only) The number of matching documents to skip before returning results.
Returns: a
Deferred
that called back with a number of documents matching the criteria.
-
database
¶ The
Database
that thisCollection
is a part of.
-
find
(filter=None, projection=None, skip=0, limit=0, sort=None, **kwargs)[source]¶ Find documents in a collection.
Ordering, indexing hints and other query parameters can be set with sort argument. See
txmongo.filter
for details.Parameters: - filter – MongoDB query document. To return all documents in a collection,
omit this parameter or pass an empty document (
{}
). You can pass{"key": "value"}
to select documents havingkey
field equal to"value"
or use any of MongoDB’s query selectors. - projection – a list of field names that should be returned for each document
in the result set or a dict specifying field names to include or
exclude. If projection is a list
_id
fields will always be returned. Use a dict form to exclude fields:projection={"_id": False}
. - skip – the number of documents to omit from the start of the result set.
- limit – the maximum number of documents to return. All documents are returned when limit is zero.
- sort – query filter. You can specify ordering, indexing hints and other query
parameters with this argument. See
txmongo.filter
for details.
Returns: an instance of
Deferred
that called back with a list with all documents found.- filter – MongoDB query document. To return all documents in a collection,
omit this parameter or pass an empty document (
-
find_one
(filter=None, projection=None, **kwargs)[source]¶ Get a single document from the collection.
All arguments to
find()
are also valid forfind_one()
, although limit will be ignored.Returns: a Deferred
that called back with single document orNone
if no matching documents is found.
-
find_one_and_replace
(filter, replacement, projection=None, sort=None, upsert=False, return_document=ReturnDocument.BEFORE)[source]¶
-
find_one_and_update
(filter, update, projection=None, sort=None, upsert=False, return_document=ReturnDocument.BEFORE)[source]¶
-
find_with_cursor
(filter=None, projection=None, skip=0, limit=0, sort=None, batch_size=0, **kwargs)[source]¶ Find documents in a collection and return them in one batch at a time.
Arguments are the same as for
find()
.Returns: an instance of Deferred
that fires with tuple of(docs, dfr)
, wheredocs
is a partial result, returned by MongoDB in a first batch anddfr
is aDeferred
that fires with next(docs, dfr)
. Last result will be([], None)
. You can iterate over the result set with code like that:@defer.inlineCallbacks def query(): docs, dfr = yield coll.find(query, cursor=True) while docs: for doc in docs: do_something(doc) docs, dfr = yield dfr
-
full_name
¶ Full name of this
Collection
, i.e. db_name.collection_name
-
insert
(docs, safe=None, flags=0, **kwargs)[source]¶ Insert a document(s) into this collection.
Please consider using new-style
insert_one()
orinsert_many()
methods instead.If document doesn’t have
"_id"
field,insert()
will generate newObjectId
and set it to"_id"
field of the document.Parameters: - docs – Document or a list of documents to insert into a collection.
- safe –
True
orFalse
forces usage of respectively acknowledged or unacknowledged Write Concern. IfNone
,write_concern
is used. - flags – If zero (default), inserting will stop after the first error
encountered. When
flags
set totxmongo.protocol.INSERT_CONTINUE_ON_ERROR
, MongoDB will try to insert all documents passed even if inserting some of them will fail (for example, because of duplicate_id
). Not thatinsert()
won’t raise any errors when this flag is used.
Returns: Deferred
that fires with single_id
field or a list of_id
fields of inserted documents.
-
insert_many
(documents, ordered=True)[source]¶ Insert an iterable of documents into collection
Parameters: - documents – An iterable of documents to insert (
list
,tuple
, …) - ordered – If
True
(the default) documents will be inserted on the server serially, in the order provided. If an error occurs, all remaining inserts are aborted. IfFalse
, documents will be inserted on the server in arbitrary order, possibly in parallel, and all document inserts will be attempted.
Returns: Deferred
that called back withpymongo.results.InsertManyResult
- documents – An iterable of documents to insert (
-
insert_one
(document)[source]¶ Insert a single document into collection
Parameters: document – Document to insert Returns: Deferred
that called back withpymongo.results.InsertOneResult
-
name
¶ Name of this
Collection
(without database name).
-
options
()[source]¶ Get the options set on this collection.
Returns: Deferred
that called back with dictionary of options and their values or with empty dict if collection doesn’t exist.
-
replace_one
(filter, replacement, upsert=False)[source]¶ Replace a single document matching the filter.
Raises: - ValueError – if update document is empty
- ValueError – if update document has fields that starts with $ sign.
This method only allows replacing document completely. Use
update_one()
for modifying existing document.
Parameters: - filter – A query that matches the document to replace.
- replacement – The new document to replace with.
- upsert – If
True
, perform an insert if no documents match the filter.
Returns: deferred instance of
pymongo.results.UpdateResult
.
-
update
(spec, document, upsert=False, multi=False, safe=None, flags=0, **kwargs)[source]¶ Update document(s) in this collection
Please consider using new-style
update_one()
,update_many()
andreplace_one()
methods instead.Raises: TypeError – if spec or document are not instances of dict or upsert is not an instance of bool.
Parameters: - spec – query document that selects documents to be updated
- document – update document to be used for updating or upserting. See MongoDB Update docs for the format of this document and allowed operators.
- upsert – perform an upsert if
True
- multi – update all documents that match spec, rather than just the first
matching document. The default value is
False
. - safe –
True
orFalse
forces usage of respectively acknowledged or unacknowledged Write Concern. IfNone
,write_concern
is used.
Returns: Deferred
that is called back when request is sent to MongoDB or confirmed by MongoDB (depending on selected Write Concern).
-
update_many
(filter, update, upsert=False)[source]¶ Update one or more documents that match the filter.
Raises: - ValueError – if update document is empty.
- ValueError – if update document has fields that don’t start with $ sign.
This method only allows modification of document (with $set,
$inc, etc.), not replacing it. For replacing use
replace_one()
instead.
Parameters: - filter – A query that matches the documents to update.
- update –
update document to be used for updating or upserting. See MongoDB Update docs for allowed operators.
- upsert – If
True
, perform an insert if no documents match the filter.
Returns: deferred instance of
pymongo.results.UpdateResult
.
-
update_one
(filter, update, upsert=False)[source]¶ Update a single document matching the filter.
Raises: - ValueError – if update document is empty.
- ValueError – if update document has any fields that don’t start with $ sign.
This method only allows modification of document (with $set,
$inc, etc.), not replacing it. For replacing use
replace_one()
instead.
Parameters: - filter – A query that matches the document to update.
- update –
update document to be used for updating or upserting. See MongoDB Update docs for allowed operators.
- upsert – If
True
, perform an insert if no documents match the filter.
Returns: deferred instance of
pymongo.results.UpdateResult
.
-
with_options
(*, write_concern=None, codec_options=None)[source]¶ Get a clone of collection changing the specified settings.
Parameters: - write_concern – (keyword only)
new
WriteConcern
to use. - codec_options – (keyword only)
new
CodecOptions
to use.
- write_concern – (keyword only)
new
-
write_concern
¶ Read only access to the
WriteConcern
of this instance.Use
coll.with_options(write_concern=WriteConcern(...))
to change the Write Concern.
- database – the
txmongo.connection module¶
-
class
txmongo.connection.
ConnectionPool
(uri='mongodb://127.0.0.1:27017', pool_size=1, ssl_context_factory=None, ping_interval=10, ping_timeout=10, **kwargs)[source]¶ Bases:
object
-
codec_options
¶
-
uri
¶
-
write_concern
¶
-
-
class
txmongo.connection.
MongoConnection
(host='127.0.0.1', port=27017, pool_size=1, **kwargs)[source]¶
-
txmongo.connection.
MongoConnectionPool
¶ alias of
txmongo.connection.MongoConnection
-
txmongo.connection.
lazyMongoConnection
¶ alias of
txmongo.connection.MongoConnection
-
txmongo.connection.
lazyMongoConnectionPool
¶ alias of
txmongo.connection.MongoConnection
txmongo.database module¶
-
class
txmongo.database.
Database
(factory, database_name, write_concern=None, codec_options=None)[source]¶ Bases:
object
-
authenticate
(name, password, mechanism='DEFAULT')[source]¶ Send an authentication command for this database. mostly stolen from pymongo
-
codec_options
¶
-
command
(command, value=1, check=True, allowable_errors=None, codec_options=DEFAULT_CODEC_OPTIONS)[source]¶
-
connection
¶
-
name
¶
-
write_concern
¶
-
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
-
txmongo.filter.
TEXT
(keys)[source]¶ Text-based index https://docs.mongodb.com/manual/core/index-text/
-
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 twisted.internet.error.ConnectionDone: Connection was closed cleanly.>)[source]¶ Called when the connection is shut down.
Clear any circular references here, and any external references to this Protocol. The connection has been closed.
@type reason: L{twisted.python.failure.Failure}
-
connectionMade
()[source]¶ Called when a connection is made.
This may be considered the initializer of the protocol, because it is called when the connection is completed. For clients, this is called once the connection to the server has been established; for servers, this is called after an accept() call stops blocking and a socket has been received. If you need to send any greeting or initial message, do it here.
-
max_wire_version
= None¶
-
min_wire_version
= None¶
-
-
class
txmongo.protocol.
MongoServerProtocol
[source]¶ Bases:
twisted.internet.protocol.Protocol
-
dataReceived
(data)[source]¶ Called whenever data is received.
Use this method to translate to a higher-level message. Usually, some callback will be made upon the receipt of each complete protocol message.
- @param data: a string of indeterminate length. Please keep in mind
- that you will probably need to buffer some data, as partial (or multiple) protocol messages may be received! I recommend that unit tests for protocols call through to this method with differing chunk sizes, down to one byte at a time.
-
-
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