def validate_collection(self,
name_or_collection,
scandata=False,
full=False):
"""Validate a collection.
Returns a dict of validation info. Raises CollectionInvalid if
validation fails.
:Parameters:
- `name_or_collection`: A Collection object or the name of a
collection to validate.
- `scandata`: Do extra checks beyond checking the overall
structure of the collection.
- `full`: Have the server do a more thorough scan of the
collection. Use with `scandata` for a thorough scan
of the structure of the collection and the individual
documents.
"""
name = name_or_collection
if isinstance(name, Collection):
name = name.name
if not isinstance(name, string_type):
raise TypeError("name_or_collection must be an instance of "
"%s or Collection" % (string_type.__name__, ))
result = self.command("validate",
_unicode(name),
scandata=scandata,
full=full)
valid = True
# Pre 1.9 results
if "result" in result:
info = result["result"]
if info.find("exception") != -1 or info.find("corrupt") != -1:
raise CollectionInvalid("%s invalid: %s" % (name, info))
# Sharded results
elif "raw" in result:
for _, res in iteritems(result["raw"]):
if "result" in res:
info = res["result"]
if (info.find("exception") != -1
or info.find("corrupt") != -1):
raise CollectionInvalid("%s invalid: "
"%s" % (name, info))
elif not res.get("valid", False):
valid = False
break
# Post 1.9 non-sharded results.
elif not result.get("valid", False):
valid = False
if not valid:
raise CollectionInvalid("%s invalid: %r" % (name, result))
return result
async def validate_collection(self, name_or_collection: Union[str, Collection],
scandata: bool = False, full: bool = False) -> dict:
"""Validate a collection.
Returns a dict of validation info. Raises CollectionInvalid if
validation fails.
:Parameters:
- `name_or_collection`: A Collection object or the name of a
collection to validate.
- `scandata`: Do extra checks beyond checking the overall
structure of the collection.
- `full`: Have the server do a more thorough scan of the
collection. Use with `scandata` for a thorough scan
of the structure of the collection and the individual
documents.
"""
name = name_or_collection
if isinstance(name, Collection):
name = name.name
if not isinstance(name, str):
raise TypeError('name_or_collection must be an instance of str or Collection')
result = await self.command('validate', value=name, scandata=scandata, full=full)
valid = True
# Pre 1.9 results
if 'result' in result:
info = result['result']
if info.find('exception') != -1 or info.find('corrupt') != -1:
raise CollectionInvalid('{} invalid: {}'.format(name, info))
# Sharded results
elif 'raw' in result:
for res in result['raw'].values():
if 'result' in res:
info = res['result']
if (info.find('exception') != -1 or
info.find('corrupt') != -1):
raise CollectionInvalid('{} invalid: '
'{}'.format(name, info))
elif not res.get('valid', False):
valid = False
break
# Post 1.9 non-sharded results.
elif not result.get('valid', False):
valid = False
if not valid:
raise CollectionInvalid('{} invalid: {}'.format(name, result))
return result
def create_collection(self, name, codec_options=None,
read_preference=None, write_concern=None,
read_concern=None, **kwargs):
"""Create a new :class:`~pymongo.collection.Collection` in this
database.
Normally collection creation is automatic. This method should
only be used to specify options on
creation. :class:`~pymongo.errors.CollectionInvalid` will be
raised if the collection already exists.
Options should be passed as keyword arguments to this method. Supported
options vary with MongoDB release. Some examples include:
- "size": desired initial size for the collection (in
bytes). For capped collections this size is the max
size of the collection.
- "capped": if True, this is a capped collection
- "max": maximum number of objects if capped (optional)
See the MongoDB documentation for a full list of supported options by
server version.
:Parameters:
- `name`: the name of the collection to create
- `codec_options` (optional): An instance of
:class:`~bson.codec_options.CodecOptions`. If ``None`` (the
default) the :attr:`codec_options` of this :class:`Database` is
used.
- `read_preference` (optional): The read preference to use. If
``None`` (the default) the :attr:`read_preference` of this
:class:`Database` is used.
- `write_concern` (optional): An instance of
:class:`~pymongo.write_concern.WriteConcern`. If ``None`` (the
default) the :attr:`write_concern` of this :class:`Database` is
used.
- `read_concern` (optional): An instance of
:class:`~pymongo.read_concern.ReadConcern`. If ``None`` (the
default) the :attr:`read_concern` of this :class:`Database` is
used.
- `collation` (optional): An instance of
:class:`~pymongo.collation.Collation`.
- `**kwargs` (optional): additional keyword arguments will
be passed as options for the create collection command
.. versionchanged:: 3.4
Added the collation option.
.. versionchanged:: 3.0
Added the codec_options, read_preference, and write_concern options.
.. versionchanged:: 2.2
Removed deprecated argument: options
"""
if name in self.collection_names():
raise CollectionInvalid("collection %s already exists" % name)
return Collection(self, name, True, codec_options,
read_preference, write_concern,
read_concern, **kwargs)
def create_collection(self, name, **kwargs):
"""mongomock errors when kwargs are given, but we know it's safe to ignore them"""
self._ensure_valid_collection_name(name)
if name in self.list_collection_names():
raise CollectionInvalid("collection %s already exists" % name)
self._store.create_collection(name)
return self[name]
def validate_collection(self, name_or_collection):
"""Validate a collection.
Returns a string of validation info. Raises CollectionInvalid if
validation fails.
"""
name = name_or_collection
if isinstance(name, Collection):
name = name.name
if not isinstance(name, basestring):
raise TypeError("name_or_collection must be an instance of "
"(Collection, str, unicode)")
result = self.command("validate", unicode(name))
info = result["result"]
if info.find("exception") != -1 or info.find("corrupt") != -1:
raise CollectionInvalid("%s invalid: %s" % (name, info))
return info
def create_collection(self, name, options=None, **kwargs):
"""Create a new :class:`~pymongo.collection.Collection` in this
database.
Normally collection creation is automatic. This method should
only be used to specify options on
creation. :class:`~pymongo.errors.CollectionInvalid` will be
raised if the collection already exists.
Options should be passed as keyword arguments to this
method. Any of the following options are valid:
- "size": desired initial size for the collection (in
bytes). must be less than or equal to 10000000000. For
capped collections this size is the max size of the
collection.
- "capped": if True, this is a capped collection
- "max": maximum number of objects if capped (optional)
:Parameters:
- `name`: the name of the collection to create
- `options`: DEPRECATED options to use on the new collection
- `**kwargs` (optional): additional keyword arguments will
be passed as options for the create collection command
.. versionchanged:: 1.5
deprecating `options` in favor of kwargs
"""
opts = {"create": True}
if options is not None:
warnings.warn(
"the options argument to create_collection is "
"deprecated and will be removed. please use "
"kwargs instead.", DeprecationWarning)
opts.update(options)
opts.update(kwargs)
if name in self.collection_names():
raise CollectionInvalid("collection %s already exists" % name)
return Collection(self, name, **opts)
def create_collection(self,
name,
codec_options=None,
read_preference=None,
write_concern=None,
read_concern=None,
session=None,
**kwargs):
with self.__client._tmp_session(session) as s:
if name in self.collection_names(session=s):
raise CollectionInvalid("collection %s already exists" % name)
return SyncMongoCollection(self,
name,
True,
codec_options,
read_preference,
write_concern,
read_concern,
session=s,
**kwargs)
def create_collection(self, name, **kwargs):
"""Create a new :class:`~pymongo.collection.Collection` in this
database.
Normally collection creation is automatic. This method should
only be used to specify options on
creation. :class:`~pymongo.errors.CollectionInvalid` will be
raised if the collection already exists.
Options should be passed as keyword arguments to this method. Supported
options vary with MongoDB release. Some examples include:
- "size": desired initial size for the collection (in
bytes). For capped collections this size is the max
size of the collection.
- "capped": if True, this is a capped collection
- "max": maximum number of objects if capped (optional)
See the MongoDB documentation for a full list of supported options by
server version.
:Parameters:
- `name`: the name of the collection to create
- `**kwargs` (optional): additional keyword arguments will
be passed as options for the create collection command
.. versionchanged:: 2.2
Removed deprecated argument: options
.. versionchanged:: 1.5
deprecating `options` in favor of kwargs
"""
opts = {"create": True}
opts.update(kwargs)
if name in self.collection_names():
raise CollectionInvalid("collection %s already exists" % name)
return Collection(self, name, **opts)
def create_collection(self, name, options={}):
"""Create a new collection in this database.
Normally collection creation is automatic. This method should only if
you want to specify options on creation. CollectionInvalid is raised
if the collection already exists.
Options should be a dictionary, with any of the following options:
- "size": desired initial size for the collection (in bytes). must be
less than or equal to 10000000000. For capped collections this size
is the max size of the collection.
- "capped": if True, this is a capped collection
- "max": maximum number of objects if capped (optional)
:Parameters:
- `name`: the name of the collection to create
- `options` (optional): options to use on the new collection
"""
if name in self.collection_names():
raise CollectionInvalid("collection %s already exists" % name)
return Collection(self, name, options)
def validate_collection(self, name_or_collection,
scandata=False, full=False, session=None,
background=None):
"""Validate a collection.
Returns a dict of validation info. Raises CollectionInvalid if
validation fails.
See also the MongoDB documentation on the `validate command`_.
:Parameters:
- `name_or_collection`: A Collection object or the name of a
collection to validate.
- `scandata`: Do extra checks beyond checking the overall
structure of the collection.
- `full`: Have the server do a more thorough scan of the
collection. Use with `scandata` for a thorough scan
of the structure of the collection and the individual
documents.
- `session` (optional): a
:class:`~pymongo.client_session.ClientSession`.
- `background` (optional): A boolean flag that determines whether
the command runs in the background. Requires MongoDB 4.4+.
.. versionchanged:: 3.11
Added ``background`` parameter.
.. versionchanged:: 3.6
Added ``session`` parameter.
.. _validate command: https://docs.mongodb.com/manual/reference/command/validate/
"""
name = name_or_collection
if isinstance(name, Collection):
name = name.name
if not isinstance(name, str):
raise TypeError("name_or_collection must be an instance of str or "
"Collection")
cmd = SON([("validate", name),
("scandata", scandata),
("full", full)])
if background is not None:
cmd["background"] = background
result = self.command(cmd, session=session)
valid = True
# Pre 1.9 results
if "result" in result:
info = result["result"]
if info.find("exception") != -1 or info.find("corrupt") != -1:
raise CollectionInvalid("%s invalid: %s" % (name, info))
# Sharded results
elif "raw" in result:
for _, res in result["raw"].items():
if "result" in res:
info = res["result"]
if (info.find("exception") != -1 or
info.find("corrupt") != -1):
raise CollectionInvalid("%s invalid: "
"%s" % (name, info))
elif not res.get("valid", False):
valid = False
break
# Post 1.9 non-sharded results.
elif not result.get("valid", False):
valid = False
if not valid:
raise CollectionInvalid("%s invalid: %r" % (name, result))
return result
def validate_collection(self, name_or_collection,
scandata=False, full=False):
"""Validate a collection.
Returns a dict of validation info. Raises CollectionInvalid if
validation fails.
With MongoDB < 1.9 the result dict will include a `result` key
with a string value that represents the validation results. With
MongoDB >= 1.9 the `result` key no longer exists and the results
are split into individual fields in the result dict.
:Parameters:
`name_or_collection`: A Collection object or the name of a
collection to validate.
`scandata`: Do extra checks beyond checking the overall
structure of the collection.
`full`: Have the server do a more thorough scan of the
collection. Use with `scandata` for a thorough scan
of the structure of the collection and the individual
documents. Ignored in MongoDB versions before 1.9.
.. versionchanged:: 1.11
validate_collection previously returned a string.
.. versionadded:: 1.11
Added `scandata` and `full` options.
"""
name = name_or_collection
if isinstance(name, Collection):
name = name.name
if not isinstance(name, basestring):
raise TypeError("name_or_collection must be an instance of "
"(Collection, str, unicode)")
result = self.command("validate", unicode(name),
scandata=scandata, full=full)
valid = True
# Pre 1.9 results
if "result" in result:
info = result["result"]
if info.find("exception") != -1 or info.find("corrupt") != -1:
raise CollectionInvalid("%s invalid: %s" % (name, info))
# Sharded results
elif "raw" in result:
for repl, res in result["raw"].iteritems():
if "result" in res:
info = res["result"]
if (info.find("exception") != -1 or
info.find("corrupt") != -1):
raise CollectionInvalid("%s invalid: "
"%s" % (name, info))
elif not res.get("valid", False):
valid = False
break
# Post 1.9 non-sharded results.
elif not result.get("valid", False):
valid = False
if not valid:
raise CollectionInvalid("%s invalid: %r" % (name, result))
return result
def create_collection(self,
name,
codec_options=None,
read_preference=None,
write_concern=None,
read_concern=None,
session=None,
**kwargs):
"""Create a new :class:`~pymongo.collection.Collection` in this
database.
Normally collection creation is automatic. This method should
only be used to specify options on
creation. :class:`~pymongo.errors.CollectionInvalid` will be
raised if the collection already exists.
:Parameters:
- `name`: the name of the collection to create
- `codec_options` (optional): An instance of
:class:`~bson.codec_options.CodecOptions`. If ``None`` (the
default) the :attr:`codec_options` of this :class:`Database` is
used.
- `read_preference` (optional): The read preference to use. If
``None`` (the default) the :attr:`read_preference` of this
:class:`Database` is used.
- `write_concern` (optional): An instance of
:class:`~pymongo.write_concern.WriteConcern`. If ``None`` (the
default) the :attr:`write_concern` of this :class:`Database` is
used.
- `read_concern` (optional): An instance of
:class:`~pymongo.read_concern.ReadConcern`. If ``None`` (the
default) the :attr:`read_concern` of this :class:`Database` is
used.
- `collation` (optional): An instance of
:class:`~pymongo.collation.Collation`.
- `session` (optional): a
:class:`~pymongo.client_session.ClientSession`.
- `**kwargs` (optional): additional keyword arguments will
be passed as options for the `create collection command`_
All optional `create collection command`_ parameters should be passed
as keyword arguments to this method. Valid options include, but are not
limited to:
- ``size``: desired initial size for the collection (in
bytes). For capped collections this size is the max
size of the collection.
- ``capped``: if True, this is a capped collection
- ``max``: maximum number of objects if capped (optional)
- ``timeseries``: a document specifying configuration options for
timeseries collections
- ``expireAfterSeconds``: the number of seconds after which a
document in a timeseries collection expires
.. versionchanged:: 3.11
This method is now supported inside multi-document transactions
with MongoDB 4.4+.
.. versionchanged:: 3.6
Added ``session`` parameter.
.. versionchanged:: 3.4
Added the collation option.
.. versionchanged:: 3.0
Added the codec_options, read_preference, and write_concern options.
.. _create collection command:
https://docs.mongodb.com/manual/reference/command/create
"""
with self.__client._tmp_session(session) as s:
# Skip this check in a transaction where listCollections is not
# supported.
if ((not s or not s.in_transaction)
and name in self.list_collection_names(
filter={"name": name}, session=s)):
raise CollectionInvalid("collection %s already exists" % name)
return Collection(self,
name,
True,
codec_options,
read_preference,
write_concern,
read_concern,
session=s,
**kwargs)
def create_collection(
self,
name: str,
codec_options: Optional[CodecOptions] = None,
read_preference: Optional[_ServerMode] = None,
write_concern: Optional["WriteConcern"] = None,
read_concern: Optional["ReadConcern"] = None,
session: Optional["ClientSession"] = None,
**kwargs: Any,
) -> Collection[_DocumentType]:
"""Create a new :class:`~pymongo.collection.Collection` in this
database.
Normally collection creation is automatic. This method should
only be used to specify options on
creation. :class:`~pymongo.errors.CollectionInvalid` will be
raised if the collection already exists.
:Parameters:
- `name`: the name of the collection to create
- `codec_options` (optional): An instance of
:class:`~bson.codec_options.CodecOptions`. If ``None`` (the
default) the :attr:`codec_options` of this :class:`Database` is
used.
- `read_preference` (optional): The read preference to use. If
``None`` (the default) the :attr:`read_preference` of this
:class:`Database` is used.
- `write_concern` (optional): An instance of
:class:`~pymongo.write_concern.WriteConcern`. If ``None`` (the
default) the :attr:`write_concern` of this :class:`Database` is
used.
- `read_concern` (optional): An instance of
:class:`~pymongo.read_concern.ReadConcern`. If ``None`` (the
default) the :attr:`read_concern` of this :class:`Database` is
used.
- `collation` (optional): An instance of
:class:`~pymongo.collation.Collation`.
- `session` (optional): a
:class:`~pymongo.client_session.ClientSession`.
- `**kwargs` (optional): additional keyword arguments will
be passed as options for the `create collection command`_
All optional `create collection command`_ parameters should be passed
as keyword arguments to this method. Valid options include, but are not
limited to:
- ``size`` (int): desired initial size for the collection (in
bytes). For capped collections this size is the max
size of the collection.
- ``capped`` (bool): if True, this is a capped collection
- ``max`` (int): maximum number of objects if capped (optional)
- ``timeseries`` (dict): a document specifying configuration options for
timeseries collections
- ``expireAfterSeconds`` (int): the number of seconds after which a
document in a timeseries collection expires
- ``validator`` (dict): a document specifying validation rules or expressions
for the collection
- ``validationLevel`` (str): how strictly to apply the
validation rules to existing documents during an update. The default level
is "strict"
- ``validationAction`` (str): whether to "error" on invalid documents
(the default) or just "warn" about the violations but allow invalid
documents to be inserted
- ``indexOptionDefaults`` (dict): a document specifying a default configuration
for indexes when creating a collection
- ``viewOn`` (str): the name of the source collection or view from which
to create the view
- ``pipeline`` (list): a list of aggregation pipeline stages
- ``comment`` (str): a user-provided comment to attach to this command.
This option is only supported on MongoDB >= 4.4.
.. versionchanged:: 3.11
This method is now supported inside multi-document transactions
with MongoDB 4.4+.
.. versionchanged:: 3.6
Added ``session`` parameter.
.. versionchanged:: 3.4
Added the collation option.
.. versionchanged:: 3.0
Added the codec_options, read_preference, and write_concern options.
.. _create collection command:
https://docs.mongodb.com/manual/reference/command/create
"""
with self.__client._tmp_session(session) as s:
# Skip this check in a transaction where listCollections is not
# supported.
if (not s or not s.in_transaction
) and name in self.list_collection_names(filter={"name": name},
session=s):
raise CollectionInvalid("collection %s already exists" % name)
return Collection(
self,
name,
True,
codec_options,
read_preference,
write_concern,
read_concern,
session=s,
**kwargs,
)
