mongodol.util#
Util functions
Functions
|
Make sure mongo guarantees the unicity of |
|
Computes a "flat" dict from a nested one. |
|
Derive |
|
Get a pymongo.collection.Collection object for a mongo collection, flexibly. |
|
Whether |
|
Make a |
Make a |
|
Make a default |
|
|
Normalize projection specification to be an explicit list of flattened dict of {path.to.key: True/False,. |
|
Flatten and merge two mongo projection dicts, OR-ing every field against a forced default of |
Exceptions
Raised when a key was expected to be unique, but wasn't (i.e. cursor has more than one match). |
|
Raised when a unique index was required on some fields, but there is none. |
- exception mongodol.util.KeyNotUniqueError[source]#
Bases:
RuntimeErrorRaised when a key was expected to be unique, but wasn’t (i.e. cursor has more than one match)
- exception mongodol.util.MissingUniqueIndexError[source]#
Bases:
RuntimeErrorRaised when a unique index was required on some fields, but there is none.
- mongodol.util.ensure_unique_index(collection, key_fields, *, create=True)[source]#
Make sure mongo guarantees the unicity of
key_fieldsincollection.This is the alternative to checking, on every
s[key], that the cursor has a single match (KeyNotUniqueError): let the database enforce it, and then use a reader that doesn’t check (e.g.MongoCollectionFirstDocReader).- Parameters:
create (
bool) – If True (default), create the unique index if it’s missing (this raises a pymongoDuplicateKeyErrorif the existing docs already violate it). If False, raiseMissingUniqueIndexErrorinstead of creating it.
>>> class FakeCollection: ... indexes = {} ... def index_information(self): ... return self.indexes ... def create_index(self, keys, unique=False): ... self.indexes['_'.join(map(str, keys))] = {'key': keys, 'unique': unique} >>> c = FakeCollection() >>> ensure_unique_index(c, 's', create=False) Traceback (most recent call last): ... mongodol.util.MissingUniqueIndexError: No unique index on ('s',) >>> ensure_unique_index(c, 's') >>> has_unique_index(c, 's') True
- mongodol.util.flatten_dict_items(d, prefix='')[source]#
Computes a “flat” dict from a nested one. A flat dict’s keys are the dot-paths of the input dict.
- Parameters:
d (
Mapping) – a nested dictprefix – A string to prepend on all the paths
- Returns:
A flat dict
>>> d = {'a': { ... 'a': '2a', ... 'c': {'a': 'aca', 'u': 4} ... }, ... 'c': 3 ... } >>> dict(flatten_dict_items(d)) {'a.a': '2a', 'a.c.a': 'aca', 'a.c.u': 4, 'c': 3}
- mongodol.util.get_key_value_specs(key_fields, data_fields)[source]#
Derive
key_projection(and, whendata_fieldsis None or a non-dict iterable,items_projection) fromkey_fields/data_fields.Note
when
data_fieldsis already a dict,items_projectionis never assigned, so this branch raisesUnboundLocalErroron thereturnbelow.
- mongodol.util.get_mongo_collection_pymongo_obj(obj=None, client_factory=<function mk_dflt_client>)[source]#
Get a pymongo.collection.Collection object for a mongo collection, flexibly.
get_mongo_collection_pymongo_obj() # gives you a default mongo collection (mongodol/mongodol_test) get_mongo_collection_pymongo_obj('database_name/collection_name') # does the obvious (with default host) get_mongo_collection_pymongo_obj(... an object that has an _mgc attribute...) # return the _mgc attribute get_mongo_collection_pymongo_obj(obj) # else, asserts pymongo.collection.Collection and returns it>>> from mongodol.util import get_mongo_collection_pymongo_obj >>> c = get_mongo_collection_pymongo_obj() >>> c.name, c.database.name ('mongodol_test', 'mongodol')
An object with an
_mgcattribute (such as a mongodol store) has that attribute returned directly:>>> from mongodol.tests import util >>> mgc = util.populated_pymongo_collection([]) >>> store = type('Store', (), {'_mgc': mgc})() >>> get_mongo_collection_pymongo_obj(store) is mgc True
- mongodol.util.has_unique_index(collection, key_fields)[source]#
Whether
collectionhas a unique index on exactlykey_fields(a field name or a sequence of them), i.e. whether mongo itself guarantees key unicity.Only uses
collection.index_information(), so any object with that method works.>>> class FakeCollection: ... def index_information(self): ... return {'_id_': {'key': [('_id', 1)], 'unique': True}, ... 's_1': {'key': [('s', 1)]}} >>> has_unique_index(FakeCollection(), '_id') True >>> has_unique_index(FakeCollection(), 's') # an index, but not a unique one False
- Return type:
- mongodol.util.mk_client(*args, **kwargs)[source]#
Make a
pymongo.MongoClient, keeping pymongo 3’s UUID codec unless told otherwise.>>> mk_client(connect=False).codec_options.uuid_representation 3 >>> mk_client(connect=False, uuidRepresentation="standard").codec_options.uuid_representation 4
A connection string (or a lower-cased option) that names a
uuidRepresentationis left to say it.
- mongodol.util.mk_dflt_mgc()[source]#
Make a default
pymongo.collection.Collection, connecting with default client args to the default test database and collection.>>> from mongodol.util import mk_dflt_mgc >>> c = mk_dflt_mgc() >>> c.name, c.database.name ('mongodol_test', 'mongodol')
- mongodol.util.normalize_projection(projection)[source]#
Normalize projection specification to be an explicit list of flattened dict of {path.to.key: True/False,… (or None if projection is None to start with).
This is used to be able to have a consistent specification of mongo projections.
If projection is None, the output will None as well:
>>> assert normalize_projection(None) is None
If projection is a dict, the dict will be “flattened” to use “dot-paths” instead of nested dicts:
>>> normalize_projection({'name': {'first': True, 'last': False}, 'age': True}) {'name.first': True, 'name.last': False, 'age': True}
If projection is not a dict, it will make the “equivalent” dict version of the projection. One difference with mongodb’s projection language: Here, if you don’t specify that you want “_id”, it will explicitly specify that you DO NOT want that field (because mongodb will otherwise assume that you do!)
>>> normalize_projection(['name.first', 'age']) {'name.first': True, 'age': True, '_id': False}
But if you actually want that “_id”, just say so:
>>> normalize_projection(['name.first', 'age', '_id']) {'name.first': True, 'age': True, '_id': True}
Also, if you specify a string, it will think of this as a tuple containing just that string:
>>> normalize_projection('name.last') {'name.last': True, '_id': False}
The empty projection is the one exception to “
_idis set to False unless named”: it means “only_id” (what pymongo 3 sent it as; pymongo 4 would send nothing, i.e. whole documents):>>> normalize_projection(()) {'_id': True}
- mongodol.util.projection_union(projection_1, projection_2, already_flattened=False)[source]#
Flatten and merge two mongo projection dicts, OR-ing every field against a forced default of
True– so a field appearing in only one of the two dicts (or with aFalsevalue) still comes outTrueunless both dicts agree it’sFalse.>>> d = {'a': { ... 'a': True, ... 'c': {'a': True, 'u': True} ... }, ... 'b': True, ... 'c': False ... } >>> dd = {'b': True, 'c': True, 'x': True, 'y': False} >>> assert projection_union(d, dd) == ( ... {'a.a': True, 'a.c.a': True, 'a.c.u': True, 'b': True, 'c': True, 'x': True, 'y': True} ... )