docs: def replace_one(self, filter, replacement, upsert=False,
                      bypass_document_validation=False, collation=None):
          """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
          """
          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)