'Replace a single document matching the filter.
>>> for doc in db.test.find({}):
...     print(doc)
{u\'x\': 1, u\'_id\': ObjectId(\'54f4c5befba5220aa4d6dee7\')}
>>> result = db.test.replace_one({\'x\': 1}, {\'y\': 1})
>>> result.matched_count
1
>>> result.modified_count
1
>>> for doc in db.test.find({}):
...     print(doc)
{u\'y\': 1, u\'_id\': ObjectId(\'54f4c5befba5220aa4d6dee7\')}
The *upsert* option can be used to insert a new document if a matching
document does not exist.
>>> result = db.test.replace_one({\'x\': 1}, {\'x\': 1}, True)
>>> result.matched_count
0
>>> result.modified_count
0
>>> result.upserted_id
ObjectId(\'54f11e5c8891e756a6e1abd4\')
>>> db.test.find_one({\'x\': 1})
{u\'x\': 1, u\'_id\': ObjectId(\'54f11e5c8891e756a6e1abd4\')}
:Parameters:
- `filter`: A query that matches the document to replace.
- `replacement`: The new document.
- `upsert` (optional): If ``True``, perform an insert if no documents
match the filter.
- `bypass_document_validation`: (optional) If ``True``, allows the
write to opt-out of document level validation. Default is
``False``.
- `collation` (optional): An instance of
:class:`~pymongo.collation.Collation`. This option is only supported
on MongoDB 3.4 and above.
:Returns:
- An instance of :class:`~pymongo.results.UpdateResult`.
.. note:: `bypass_document_validation` requires server version
**>= 3.2**
.. versionchanged:: 3.4
Added the `collation` option.
.. versionchanged:: 3.2
Added bypass_document_validation support
.. versionadded:: 3.0'

def replace_one(self, filter, replacement, upsert=False, bypass_document_validation=False, collation=None):

    common.validate_is_mapping('filter', filter)
    common.validate_ok_for_replace(replacement)
    with self._socket_for_writes() as sock_info:
        result = self._update(sock_info, filter, replacement, upsert, bypass_doc_val=bypass_document_validation, collation=collation)
    return UpdateResult(result, self.write_concern.acknowledged)
