Package: umongo
μMongo: sync/async ODMμMongo is a Python MongoDB ODM. It inception comes from two needs:
the lack of async ODM and the difficulty to do document (un)serialization
with existing ODMs.From this point, μMongo made a few design choices:Stay close to the standards MongoDB driver to keep the same API when possible:
usefind({"field":"value"})like usual but retrieve your data nicely OO wrapped !Work with multiple drivers (PyMongo,TxMongo,motor_asyncioandmongomockfor the moment)Tight integration withMarshmallowserialization library to easily
dump and load your data with the outside worldi18n integration to localize validation error messagesFree software: MIT licenseTest with 90%+ coverage ;-)µMongo requires MongoDB 4.2+ and Python 3.7+.Quick exampleimportdatetimeasdtfrompymongoimportMongoClientfromumongoimportDocument,fields,validatefromumongo.frameworksimportPyMongoInstancedb=MongoClient().testinstance=PyMongoInstance(db)@instance.registerclassUser(Document):email=fields.EmailField(required=True,unique=True)birthday=fields.DateTimeField(validate=validate.Range(min=dt.datetime(1900,1,1)))friends=fields.ListField(fields.ReferenceField("User"))classMeta:collection_name="user"# Make sure that unique indexes are createdUser.ensure_indexes()goku=User(email='goku@sayen.com',birthday=dt.datetime(1984,11,20))goku.commit()vegeta=User(email='vegeta@over9000.com',friends=[goku])vegeta.commit()vegeta.friends# <object umongo.data_objects.List([<object umongo.dal.pymongo.PyMongoReference(document=User, pk=ObjectId('5717568613adf27be6363f78'))>])>vegeta.dump()# {id': '570ddb311d41c89cabceeddc', 'email': 'vegeta@over9000.com', friends': ['570ddb2a1d41c89cabceeddb']}User.find_one({"email":'goku@sayen.com'})# <object Document __main__.User({'id': ObjectId('570ddb2a1d41c89cabceeddb'), 'friends': <object umongo.data_objects.List([])>,#                                 'email': 'goku@sayen.com', 'birthday': datetime.datetime(1984, 11, 20, 0, 0)})>Get it now:$ pip install umongo           # This installs umongo with pymongo
$ pip install my-mongo-driver  # Other MongoDB drivers must be installed manuallyOr to get it along with the MongoDB driver you’re planing to use:$ pip install umongo[motor]
$ pip install umongo[txmongo]
$ pip install umongo[mongomock]History3.1.0 (2021-12-23)Features:Add fields list toDocumentandEmbeddedDocument.__dir__()(see #367).Bug fixes:Test database by comparing toNone, not casting toboolto prevent
an exception raised by pymongo >= 4 (see #366).3.0.1 (2021-10-16)Bug fixes:Fix ListField.insert: triggerset_modified, deserialize using inner field
(see #364).3.0.0 (2021-01-11)Features:Fix internationalization of generated marshmallow fields for container fields
(DictField, ListField, NestedField) (see #329).Don’t pass field metadata as kwargs (deprecated in marshmallow 3.10.0) but asmetadataargument (see #328).Bug fixes:Fix IO validation ofNonefor references, lists and embedded documents
(see #330).Add_dict_io_validateto propagate IO validation throughDictField(see #335).Other changes:Backwards-incompatible: Require marshmallow>=3.10.0 (see #328).3.0.0b14 (2020-12-08)Features:ProvideInstancesubclasses for each framework to help users migrating
a database from umongo 2 to umongo 3 (see #319).Backwards-incompatible: Postpone embedded document resolution inEmbeddedFieldto allow passing an embedded document as string before its
registration. Unknown embedded document errors inEmbeddedFieldare now
detected at runtime, not registration time. Also, indexes are now collected
on first use rather than upon registration and should be accesses throughDocument.indexescached property rather thanDocument.opts.indexes.
(see #322)Backwards-incompatible: MakeBaseSchemaordered. This fixes querying on
embedded documents. MakeBaseMarshmallowSchemaordered as well.
(see #323)Backwards-incompatible: MakeRemoveMissingSchemaopt-out. By default,
generated pure marshmallow schemas now skip missing values fromDocumentinstances rather that returningNone. This can be changed by settingMA_BASE_SCHEMA_CLS. (see #325)3.0.0b13 (2020-11-23)Bug fixes:Fix a bug introduced in 3.0.0b12 preventing instance initialization with DB
as parameter as ininstance = PyMongoInstance(db). (see #318)3.0.0b12 (2020-11-16)Features:Backwards-incompatible: ReworkInstance: mergeBaseInstance,InstanceandLazyLoaderInstanceinto a single abstractInstanceclass. Removetemplatesargument fromInstance. RenameInstance.inittoInstance.set_db. Don’t republish concrete framework
instances inumongotop module. (see #314)Addsessioncontext manager toPyMongoInstanceandMotorAsyncIOInstance. This allows to use session related features
(causally consistent reads, transactions) from umongo. (see #315)3.0.0b11 (2020-11-06)Features:Backwards-incompatible: Allow setting arbitrary attributes onDocumentandEmbeddedDocumentinstances. This change is part of a refactor meant
to simplify set / get / delete operations on document objets and (marginally)
improve performance. (see #272)Use structured information provided withDuplicateKeyErrorrather than
parse the error message string (see #309).Addreplaceargument tocommitmethod to force writing the whole
document rather than updating (see #310).Other changes:Support Python 3.9 (see #311).Backwards-incompatible: Drop motor<2.0.0 support (see #312).Backwards-incompatible: Drop MongoDB<4.2 support (see #313).3.0.0b10 (2020-10-12)Features:Allow passingDocumentandEmbeddedDocumentin queries. (see #303)3.0.0b9 (2020-10-05)Features:Add support for motor 2.2 (see #294). (Picked from 2.3.0.)Backwards-incompatible: AddExposeMissingcontext manager to returnmissingrather thanNonewhen dumping. ReplaceFromUmongoSchemawithRemoveMissingSchema. This schema removes missing fields when dumping
by usingExposeMissinginternally. Make this feature opt-in by requiring
the user to specifyRemoveMissingSchemaasMA_BASE_SCHEMA_CLS.
(see #261)Backwards-incompatible: Removemongo_worldparameter fromSchema.as_marshmallow_schema. Schemas generated by this method are meant
to (de)serialize umongo objects, notdictstraight from database.
(see #299)Backwards-incompatible: Removeumongo.Schema. Schemas should inherit
fromumongo.abstract.BaseSchema. ExposeRemoveMissingSchemaasumongo.RemoveMissingSchema. (see #301)Other changes:Backwards-incompatible: Drop Python 3.6 support (see #298).3.0.0b8 (2020-07-22)Features:LetDocumentinherit fromEmbeddedDocument(see #266).AddMixinDocumentallowingDocumentandEmbeddedDocumentto
inherit fields and pre/post methods from mixin objects (see #278).Backwards-incompatible: Removeas_attributeargument ofBaseInstance.registermethod. Documents can not be accessed by name as
instance attributes anymore. (see #290)Bug fixes:Fix passingNoneto a field with_required_validatemethod
(see #289).3.0.0b7 (2020-05-08)Features:Backwards-incompatible: Revert broken feature introduced in 3.0.0b6
allowing to get fields from mixin classes (see #273).Backwards-incompatible: Removeallow_inheritanceoption. AnyDocumentorEmbeddedDocumentmay be subclassed (see #270).Backwards-incompatible:FieldraisesDocumentDefinitionErrorrather
thanRuntimeErrorwhen passedmissingkwarg andDocument.commitraisesNotCreatedErrorwhen passedconditionsfor a document that is
not in database (see #275).3.0.0b6 (2020-05-04)Features:Backwards-incompatible:abstractinEmbeddedDocumentbehaves
consistently withDocument. The_cls/clsfield is only added
on concrete embedded documents subclassing concrete embedded documents. AndEmbeddedFieldonly accepts concrete embedded documents. (see #86)DocumentandEmbeddedDocumentmay inherits from mixin classes. The
mixin class should appear first (leftmost) in the bases:class MyDocument(MyMixin, Document). (see #188)Other changes:Backwards-incompatible: marshmallow imports throughout the code are done asimport marshmallow as ma. For convenience,missingandValidationErrorcan still be imported asumongo.missingandumongo.ValidationError.3.0.0b5 (2020-04-30)Features:Backwards-incompatible: AddMA_BASE_SCHEMA_CLSclass attribute toDocumentandEmbeddedDocumentto specify a base class to use inas_marshmallow_schema. Drop thecheck_unknown_fields,paramsandmetaattributes ofas_marshmallow_schema. Makemongo_worldkwarg-only. The same effect can be achieved using base schema classes.
This incidentally fixes brokenas_marshmallow_schemacache feature.
(see #263)Backwards-incompatible: AddTxMongoDocument.find_with_cursorand
drop support for upstream deprecatedfind(cursor=True). (see #259).Other changes:Backwards-incompatible: Require txmongo>=19.2.0 (see #259).3.0.0b4 (2020-04-27)Features:Backwards-incompatible: Remove partial load feature (see #256).Backwards-incompatible: AddDocument.pk_fieldand removeBaseDataProxy.*_by_mongo_namemethods(see #257).Backwards-incompatible: Raise AlreadyCreatedError when modifying pk of
created document (see #258).3.0.0b3 (2020-04-26)Features:Backwards-incompatible: ReplaceReferenceErrorwithNoneReferenceError. Review the list of exceptions importable from
rootumongomodule. (see #251)Bug fixes:Don’t modify data when callingset_by_mongo_nameon a field that was not
loaded in a partial load. (see #253)Other changes:Backwards-incompatible: Drop Python 3.5 support (see #248).3.0.0b2 (2020-04-18)Features:Use fields for keys/values in DictField (see #245).Bug fixes:Fix BaseField.__repr__ (see #247).3.0.0b1 (2020-03-29)Features:Support marshmallow 3 (see #154).All field parameters beginning with"marshmallow_"are passed to the
marshmallow schema, rather than only a given list of known parameters.
(see #228)Other changes:Backwards-incompatible: Drop support for marshmallow 2. See marshmallow
upgrading guide for a comprehensive list of changes. (see #154)Backwards-incompatible:StrictDateTimeFieldis removed as marshmallow
now providesNaiveDateTimeFieldandAwareDateTimeField. (see #154)Backwards-incompatible:defaultshall now be provided in deserialized
form. (see #154)2.3.0 (2020-09-06)Features:Add support for motor 2.2 (see #294).2.2.0 (2019-12-18)Bug fixes:Fixfind/find_one: passfilteras first positional argument
(see #215).Other changes:Support Python 3.8 (see #210).2.1.1 (2019-10-04)Bug fixes:FixObjectIdbonus field: catchTypeErrorwhen deserializing
(see #207).2.1.0 (2019-06-19)Features:Add support for motor 2.+ by adding acount_documentsclass method to theMotorAsyncIODocumentclass.count_documentsattempts to transparently
use the correct motor call signature depending on which version of the
driver is installed. Note that the behavior of the cursor object returned byMotorAsyncIODocument.findstrictly adheres to the interface provided by
the underlying driver.2.0.5 (2019-06-13)Bug fixes:EnsureReferenceandGenericReferencefields round-trip (see #200).2.0.4 (2019-05-28)Bug fixes:Include modifiedBaseDataObjectinBaseDataProxy.get_modified_fieldsandBaseDataProxy.get_modified_fields_by_mongo_name(see #195).Always return a boolean inList.is_modified(see #195).List: callset_modifiedwhen deleting an element using thedelbuiltin (see #195).2.0.3 (2019-04-10)Bug fixes:Fix millisecond overflow when milliseconds round to 1s inStrictDateTimeField(see #189).2.0.2 (2019-04-10)Bug fixes:Fix millisecond overflow when milliseconds round to 1s inDateTimeFieldandLocalDateTimeField(see #189).2.0.1 (2019-03-25)Bug fixes:Fix deserialization ofEmbeddedDocumentcontaining fields overriding_deserialize_from_mongo(see #186).2.0.0 (2019-03-18)Features:Backwards-incompatible:missingattribute is no longer used in umongo
fields, onlydefaultis used.marshmallow_missingandmarshmallow_defaultattribute can be used to overwrite the value to use
in the pure marshmallow field returned byas_marshmallow_fieldmethod
(see #36 and #107).Backwards-incompatible:as_marshmallow_fielddoes not passload_from,dump_toandattributeto the pure marshmallow field
anymore. It only passesvalidate,required,allow_none,dump_only,load_onlyanderror_messages, as well asdefaultandmissingvalues inferred from umongo’sdefault. Parameters
prefixed withmarshmallow_in the umongo field are passed to the pure
marshmallow field and override their non-prefixed counterpart. (see #170)Backwards-incompatible:DictFieldandListFielddon’t default to
emptyDict/List. To keep old behaviour, passdict/listas
default. (see #105)Backwards-incompatible: Serialize emptyDict/Listas empty rather
than missing (see #105).Round datetimes to millisecond precision inDateTimeField,LocalDateTimeFieldandStrictDateTimeFieldto keep consistency
between object and database representation (see #172 and #175).AddDateField(see #178).Bug fixes:Fix passing a default value to aDictField/ListFieldas a raw Pythondict/list(see #78).Thedefaultparameter of a Field is deserialized and validated (see #174).Other changes:Support Python 3.7 (see #181).Backwards-incompatible: Drop Python 3.4 support (see #176) and only use
async/await coroutine style in asyncio framework (see #179).1.2.0 (2019-02-08)AddSchemacache toas_marshmallow_schema(see #165).AddDecimalField. This field only works on MongoDB 3.4+. (see #162)1.1.0 (2019-01-14)Fix bug when filtering by id in a Document subclass find query (see #145).Fix __getattr__ to allow copying and deepcopying Document and EmbeddedDocument
(see #157).Add Document.clone() method (see #158).1.0.0 (2018-11-29)RaiseUnknownFieldInDBErrorwhen an unknown field is found in database
and not usingBaseNonStrictDataProxy(see #121)Fix (non fatal) crash in garbage collector when usingWrappedCursorwith
mongomockDepend on pymongo 3.7+ (see #149)Passas_marshmallow_schema paramsto nested schemas. Since this change, every
field’sas_marshmallow_schemamethod should expect unknown**kwargs(see #101).Pass params to container field inListField.as_marshmallow_schema(see #150)Addmetakwarg toas_marshmallow_schemato pass adictof attributes
for the schema’sMetaclass (see #151)0.15.0 (2017-08-15)Addstrictoption to (Embedded)DocumentOpts to allow loading of document
with unknown fields from mongo (see #115)Fix fields serialization/deserialization when allow_none is True (see #69)Fix ReferenceFild assignment from another ReferenceField (see #110)Fix deletion of field proxied by a property (see #109)Fix StrictDateTime bonus field: _deserialize does not accept datetime.datetime
instances (see #106)Add force_reload param to Reference.fetch (see #96)0.14.0 (2017-03-03)Fix bug in mashmallow tag handling (see #90)Fix allow none in DataProxy.set (see #89)Support motor 1.1 (see #87)0.13.0 (2017-01-02)Fix deserialization error with nested EmbeddedDocuments (see #84, #67)Addabstractandallow_inheritanceoptions to EmbeddedDocumentRemove buggyas_marshmallow_schema’s parametermissing_accessor(see #73, #74)0.12.0 (2016-11-11)ReplaceDocument.opts.childrenbyoffspringand fix grand child
inheritance issue (see #66)Fix dependency since release of motor 1.0 with breaking API0.11.0 (2016-11-02)data_objectsDictandListinherit builtinsdictandlistDocument&EmbeddedDocument store fields passed during initialization
as modified (see #50)Required field inside embedded document are handled correctly (see #61)Document support marshmallow’s pre/post processors0.10.0 (2016-09-29)Add pre/post update/insert/delete hooks (see #22)Provide Umongo to Marshmallow schema/field conversion with
schema.as_marshmallow_schema() and field.as_marshmallow_field() (see #34)List and Dict inherit from collections’s UserList and UserDict instead
of builtins types (needed due to metaprogramming conflict otherwise)DeleteError and UpdateError returns the driver result object instead
of the raw error dict (except for motor which only has raw error dict)0.9.0 (2016-06-11)Queries can now be expressed with the document’s fields name instead of the
name in databaseEmbeddedDocumentalso need to be registered by and instance before use0.8.1 (2016-05-19)ReplaceDocument.createdbyis_created(see #14)0.8.0 (2016-05-18)Heavy rewrite of the project, lost of API breakageDocuments are now first defined as templates then implemented
inside an InstanceDALs has been replaced by frameworks implementations of BuilderFix__getitem__for Pymongo.Cursor wrapperAddconditionsargument to Document.commitAddcountmethod to txmongo0.7.8 (2016-4-28)Fix setup.py style preventing release of version 0.7.70.7.7 (2016-4-28)Fix await error with Reference.fetchPymongo is now only installed with extra flavours of umongo0.7.6 (2016-4-28)Use extras_require to install driver along with umongo0.7.5 (2016-4-23)Fixing await (Python >= 3.5) support for motor-asyncio0.7.4 (2016-4-21)Fix missing package in setup.py0.7.3 (2016-4-21)Fix setup.py style preventing from release0.7.2 (2016-4-21)Fix crash when generating indexes on EmbeddedDocument0.7.1 (2016-4-21)Fix setup.py not to install tests packagePass status to Beta0.7.0 (2016-4-21)Add i18n supportAdd MongoMock supportDocumentation has been a lot extended0.6.1 (2016-4-13)Add<dal>_lazy_loaderto configure Document’s lazy_collection0.6.0 (2016-4-12)Heavy improvements everywhere !0.1.0 (2016-1-22)First release on PyPI.