"""An enum used with

BEFORE = False

"""Return the original document before it was updated/replaced, or

AFTER = True

"""A Mongo collection.

def __init__(self, database, name, create=False, codec_options=None,

read_preference=None, write_concern=None, read_concern=None,

session=None, **kwargs):

"""Get / create a Mongo collection.

super(Collection, self).__init__(

codec_options or database.codec_options,

read_preference or database.read_preference,

write_concern or database.write_concern,

read_concern or database.read_concern)

if not isinstance(name, string_type):

raise TypeError("name must be an instance "

"of %s" % (string_type.__name__,))

if not name or ".." in name:

raise InvalidName("collection names cannot be empty")

if "$" in name and not (name.startswith("oplog.$main") or

name.startswith("$cmd")):

raise InvalidName("collection names must not "

"contain '$': %r" % name)

if name[0] == "." or name[-1] == ".":

raise InvalidName("collection names must not start "

"or end with '.': %r" % name)

if "\x00" in name:

raise InvalidName("collection names must not contain the "

"null character")

collation = validate_collation_or_none(kwargs.pop('collation', None))

self.__database = database

self.__name = _unicode(name)

self.__full_name = _UJOIN % (self.__database.name, self.__name)

if create or kwargs or collation:

self.__create(kwargs, collation, session)

self.__write_response_codec_options = self.codec_options._replace(

unicode_decode_error_handler='replace',

document_class=dict)

def _socket_for_reads(self, session):

return self.__database.client._socket_for_reads(

self._read_preference_for(session), session)

def _socket_for_primary_reads(self, session):

read_pref = ((session and session._txn_read_preference())

or ReadPreference.PRIMARY)

return self.__database.client._socket_for_reads(

read_pref, session), read_pref

def _socket_for_writes(self, session):

return self.__database.client._socket_for_writes(session)

def _command(self, sock_info, command, slave_ok=False,

read_preference=None,

codec_options=None, check=True, allowable_errors=None,

read_concern=None,

write_concern=None,

collation=None,

session=None,

retryable_write=False):

"""Internal command helper.

with self.__database.client._tmp_session(session) as s:

return sock_info.command(

self.__database.name,

command,

slave_ok,

read_preference or self._read_preference_for(session),

codec_options or self.codec_options,

check,

allowable_errors,

read_concern=read_concern,

write_concern=write_concern,

parse_write_concern_error=True,

collation=collation,

session=s,

client=self.__database.client,

retryable_write=retryable_write)

def __create(self, options, collation, session):

"""Sends a create command with the given options.

cmd = SON([("create", self.__name)])

if options:

if "size" in options:

options["size"] = float(options["size"])

cmd.update(options)

with self._socket_for_writes(session) as sock_info:

self._command(

sock_info, cmd, read_preference=ReadPreference.PRIMARY,

write_concern=self._write_concern_for(session),

collation=collation, session=session)

def __getattr__(self, name):

"""Get a sub-collection of this collection by name.

if name.startswith('_'):

full_name = _UJOIN % (self.__name, name)

raise AttributeError(

"Collection has no attribute %r. To access the %s"

" collection, use database['%s']." % (

name, full_name, full_name))

return self.__getitem__(name)

def __getitem__(self, name):

return Collection(self.__database,

_UJOIN % (self.__name, name),

False,

self.codec_options,

self.read_preference,

self.write_concern,

self.read_concern)

def __repr__(self):

return "Collection(%r, %r)" % (self.__database, self.__name)

def __eq__(self, other):

if isinstance(other, Collection):

return (self.__database == other.database and

self.__name == other.name)

return NotImplemented

def __ne__(self, other):

return not self == other

@property

def full_name(self):

"""The full name of this :class:`Collection`.

return self.__full_name

@property

def name(self):

"""The name of this :class:`Collection`."""

return self.__name

@property

def database(self):

"""The :class:`~pymongo.database.Database` that this

return self.__database

def with_options(

self, codec_options=None, read_preference=None,

write_concern=None, read_concern=None):

"""Get a clone of this collection changing the specified settings.

return Collection(self.__database,

self.__name,

False,

codec_options or self.codec_options,

read_preference or self.read_preference,

write_concern or self.write_concern,

read_concern or self.read_concern)

def initialize_unordered_bulk_op(self, bypass_document_validation=False):

"""**DEPRECATED** - Initialize an unordered batch of write operations.

warnings.warn("initialize_unordered_bulk_op is deprecated",

DeprecationWarning, stacklevel=2)

return BulkOperationBuilder(self, False, bypass_document_validation)

def initialize_ordered_bulk_op(self, bypass_document_validation=False):

"""**DEPRECATED** - Initialize an ordered batch of write operations.

warnings.warn("initialize_ordered_bulk_op is deprecated",

DeprecationWarning, stacklevel=2)

return BulkOperationBuilder(self, True, bypass_document_validation)

def bulk_write(self, requests, ordered=True,

bypass_document_validation=False, session=None):

"""Send a batch of write operations to the server.

common.validate_list("requests", requests)

blk = _Bulk(self, ordered, bypass_document_validation)

for request in requests:

try:

request._add_to_bulk(blk)

except AttributeError:

raise TypeError("%r is not a valid request" % (request,))

write_concern = self._write_concern_for(session)

bulk_api_result = blk.execute(write_concern, session)

if bulk_api_result is not None:

return BulkWriteResult(bulk_api_result, True)

return BulkWriteResult({}, False)

def _legacy_write(self, sock_info, name, cmd, op_id,

bypass_doc_val, func, *args):

"""Internal legacy unacknowledged write helper."""

# Cannot have both unacknowledged write and bypass document validation.

if bypass_doc_val and sock_info.max_wire_version >= 4:

raise OperationFailure("Cannot set bypass_document_validation with"

" unacknowledged write concern")

listeners = self.database.client._event_listeners

publish = listeners.enabled_for_commands

if publish:

start = datetime.datetime.now()

args = args + (sock_info.compression_context,)

rqst_id, msg, max_size = func(*args)

if publish:

duration = datetime.datetime.now() - start

listeners.publish_command_start(

cmd, self.__database.name, rqst_id, sock_info.address, op_id)

start = datetime.datetime.now()

try:

result = sock_info.legacy_write(rqst_id, msg, max_size, False)

except Exception as exc:

if publish:

dur = (datetime.datetime.now() - start) + duration

if isinstance(exc, OperationFailure):

details = exc.details

# Succeed if GLE was successful and this is a write error.

if details.get("ok") and "n" in details:

reply = message._convert_write_result(

name, cmd, details)

listeners.publish_command_success(

dur, reply, name, rqst_id, sock_info.address, op_id)

raise

else:

details = message._convert_exception(exc)

listeners.publish_command_failure(

dur, details, name, rqst_id, sock_info.address, op_id)

raise

if publish:

if result is not None:

reply = message._convert_write_result(name, cmd, result)

else:

# Comply with APM spec.

reply = {'ok': 1}

duration = (datetime.datetime.now() - start) + duration

listeners.publish_command_success(

duration, reply, name, rqst_id, sock_info.address, op_id)

return result

def _insert_one(

self, doc, ordered,

check_keys, manipulate, write_concern, op_id, bypass_doc_val,

session):

"""Internal helper for inserting a single document."""

if manipulate:

doc = self.__database._apply_incoming_manipulators(doc, self)

if not isinstance(doc, RawBSONDocument) and '_id' not in doc:

doc['_id'] = ObjectId()

doc = self.__database._apply_incoming_copying_manipulators(doc,

self)

write_concern = write_concern or self.write_concern

acknowledged = write_concern.acknowledged

command = SON([('insert', self.name),

('ordered', ordered),

('documents', [doc])])

if not write_concern.is_server_default:

command['writeConcern'] = write_concern.document

def _insert_command(session, sock_info, retryable_write):

if not sock_info.op_msg_enabled and not acknowledged:

# Legacy OP_INSERT.

return self._legacy_write(

sock_info, 'insert', command, op_id,

bypass_doc_val, message.insert, self.__full_name,

[doc], check_keys, False, write_concern.document, False,

self.__write_response_codec_options)

if bypass_doc_val and sock_info.max_wire_version >= 4:

command['bypassDocumentValidation'] = True

result = sock_info.command(

self.__database.name,

command,

write_concern=write_concern,

codec_options=self.__write_response_codec_options,

check_keys=check_keys,

session=session,

client=self.__database.client,

retryable_write=retryable_write)

_check_write_command_response(result)

self.__database.client._retryable_write(

acknowledged, _insert_command, session)

if not isinstance(doc, RawBSONDocument):

return doc.get('_id')

def _insert(self, docs, ordered=True, check_keys=True,

manipulate=False, write_concern=None, op_id=None,

bypass_doc_val=False, session=None):

"""Internal insert helper."""

if isinstance(docs, abc.Mapping):

return self._insert_one(

docs, ordered, check_keys, manipulate, write_concern, op_id,

bypass_doc_val, session)

ids = []

if manipulate:

def gen():

"""Generator that applies SON manipulators to each document

_db = self.__database

for doc in docs:

# Apply user-configured SON manipulators. This order of

# operations is required for backwards compatibility,

# see PYTHON-709.

doc = _db._apply_incoming_manipulators(doc, self)

if not (isinstance(doc, RawBSONDocument) or '_id' in doc):

doc['_id'] = ObjectId()

doc = _db._apply_incoming_copying_manipulators(doc, self)

ids.append(doc['_id'])

yield doc

else:

def gen():

"""Generator that only tracks existing _ids."""

for doc in docs:

# Don't inflate RawBSONDocument by touching fields.

if not isinstance(doc, RawBSONDocument):

ids.append(doc.get('_id'))

yield doc

write_concern = write_concern or self._write_concern_for(session)

blk = _Bulk(self, ordered, bypass_doc_val)

blk.ops = [(message._INSERT, doc) for doc in gen()]

try:

blk.execute(write_concern, session=session)

except BulkWriteError as bwe:

_raise_last_error(bwe.details)

return ids

def insert_one(self, document, bypass_document_validation=False,

session=None):

"""Insert a single document.

common.validate_is_document_type("document", document)

if not (isinstance(document, RawBSONDocument) or "_id" in document):

document["_id"] = ObjectId()

write_concern = self._write_concern_for(session)

return InsertOneResult(

self._insert(document,

write_concern=write_concern,

bypass_doc_val=bypass_document_validation,

session=session),

write_concern.acknowledged)

def insert_many(self, documents, ordered=True,

bypass_document_validation=False, session=None):

"""Insert an iterable of documents.

if not isinstance(documents, abc.Iterable) or not documents:

raise TypeError("documents must be a non-empty list")

inserted_ids = []

def gen():

"""A generator that validates documents and handles _ids."""

for document in documents:

common.validate_is_document_type("document", document)

if not isinstance(document, RawBSONDocument):

if "_id" not in document:

document["_id"] = ObjectId()

inserted_ids.append(document["_id"])

yield (message._INSERT, document)

write_concern = self._write_concern_for(session)

blk = _Bulk(self, ordered, bypass_document_validation)

blk.ops = [doc for doc in gen()]

blk.execute(write_concern, session=session)

return InsertManyResult(inserted_ids, write_concern.acknowledged)

def _update(self, sock_info, criteria, document, upsert=False,

check_keys=True, multi=False, manipulate=False,

write_concern=None, op_id=None, ordered=True,

bypass_doc_val=False, collation=None, array_filters=None,

session=None, retryable_write=False):

"""Internal update / replace helper."""

common.validate_boolean("upsert", upsert)

if manipulate:

document = self.__database._fix_incoming(document, self)

collation = validate_collation_or_none(collation)

write_concern = write_concern or self.write_concern

acknowledged = write_concern.acknowledged

update_doc = SON([('q', criteria),

('u', document),

('multi', multi),

('upsert', upsert)])

if collation is not None:

if sock_info.max_wire_version < 5:

raise ConfigurationError(

'Must be connected to MongoDB 3.4+ to use collations.')

elif not acknowledged:

raise ConfigurationError(

'Collation is unsupported for unacknowledged writes.')

else:

update_doc['collation'] = collation

if array_filters is not None:

if sock_info.max_wire_version < 6:

raise ConfigurationError(

'Must be connected to MongoDB 3.6+ to use array_filters.')

elif not acknowledged:

raise ConfigurationError(

'arrayFilters is unsupported for unacknowledged writes.')

else:

update_doc['arrayFilters'] = array_filters

command = SON([('update', self.name),

('ordered', ordered),

('updates', [update_doc])])

if not write_concern.is_server_default:

command['writeConcern'] = write_concern.document

if not sock_info.op_msg_enabled and not acknowledged:

# Legacy OP_UPDATE.

return self._legacy_write(

sock_info, 'update', command, op_id,

bypass_doc_val, message.update, self.__full_name, upsert,

multi, criteria, document, False, write_concern.document,

check_keys, self.__write_response_codec_options)

# Update command.

if bypass_doc_val and sock_info.max_wire_version >= 4:

command['bypassDocumentValidation'] = True

# The command result has to be published for APM unmodified

# so we make a shallow copy here before adding updatedExisting.

result = sock_info.command(

self.__database.name,

command,

write_concern=write_concern,

codec_options=self.__write_response_codec_options,

session=session,

client=self.__database.client,

retryable_write=retryable_write).copy()

_check_write_command_response(result)

# Add the updatedExisting field for compatibility.

if result.get('n') and 'upserted' not in result:

result['updatedExisting'] = True

else:

result['updatedExisting'] = False

# MongoDB >= 2.6.0 returns the upsert _id in an array

# element. Break it out for backward compatibility.

if 'upserted' in result:

result['upserted'] = result['upserted'][0]['_id']

if not acknowledged:

return None

return result

def _update_retryable(

self, criteria, document, upsert=False,

check_keys=True, multi=False, manipulate=False,

write_concern=None, op_id=None, ordered=True,

bypass_doc_val=False, collation=None, array_filters=None,

session=None):

"""Internal update / replace helper."""

def _update(session, sock_info, retryable_write):

return self._update(

sock_info, criteria, document, upsert=upsert,

check_keys=check_keys, multi=multi, manipulate=manipulate,

write_concern=write_concern, op_id=op_id, ordered=ordered,

bypass_doc_val=bypass_doc_val, collation=collation,

array_filters=array_filters, session=session,

retryable_write=retryable_write)

return self.__database.client._retryable_write(

(write_concern or self.write_concern).acknowledged and not multi,

_update, session)

def replace_one(self, filter, replacement, upsert=False,

bypass_document_validation=False, collation=None,

session=None):

"""Replace a single document matching the filter.

common.validate_is_mapping("filter", filter)

common.validate_ok_for_replace(replacement)

write_concern = self._write_concern_for(session)

return UpdateResult(

self._update_retryable(

filter, replacement, upsert,

write_concern=write_concern,

bypass_doc_val=bypass_document_validation,

collation=collation, session=session),

write_concern.acknowledged)

def update_one(self, filter, update, upsert=False,

bypass_document_validation=False,

collation=None, array_filters=None, session=None):

"""Update a single document matching the filter.

common.validate_is_mapping("filter", filter)

common.validate_ok_for_update(update)

common.validate_list_or_none('array_filters', array_filters)

write_concern = self._write_concern_for(session)

return UpdateResult(

self._update_retryable(

filter, update, upsert, check_keys=False,

write_concern=write_concern,

bypass_doc_val=bypass_document_validation,

collation=collation, array_filters=array_filters,

session=session),

write_concern.acknowledged)

def update_many(self, filter, update, upsert=False, array_filters=None,

bypass_document_validation=False, collation=None,