.. image:: https://img.shields.io/pypi/v/umongo.svg :target: https://pypi.python.org/pypi/umongo :alt: Latest version
.. image:: https://img.shields.io/pypi/pyversions/umongo.svg :target: https://pypi.org/project/umongo/ :alt: Python versions
.. image:: https://img.shields.io/badge/marshmallow-3-blue.svg :target: https://marshmallow.readthedocs.io/en/latest/upgrading.html :alt: marshmallow 3 only
.. image:: https://img.shields.io/pypi/l/umongo.svg :target: https://umongo.readthedocs.io/en/latest/license.html :alt: License
.. image:: https://dev.azure.com/lafrech/umongo/_apis/build/status/Scille.umongo?branchName=master :target: https://dev.azure.com/lafrech/umongo/_build/latest?definitionId=1&branchName=master :alt: Build status
.. image:: https://readthedocs.org/projects/umongo/badge/ :target: http://umongo.readthedocs.io/ :alt: Documentation
μ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:
find({"field": "value"}) like usual but retrieve your data nicely OO wrapped !.. _PyMongo: https://api.mongodb.org/python/current/ .. _TxMongo: https://txmongo.readthedocs.org/en/latest/ .. _motor_asyncio: https://motor.readthedocs.org/en/stable/ .. _mongomock: https://github.com/vmalloc/mongomock .. _Marshmallow: http://marshmallow.readthedocs.org
µMongo requires MongoDB 4.2+ and Python 3.7+.
Quick example
.. code-block:: python
import datetime as dt
from pymongo import MongoClient
from umongo import Document, fields, validate
from umongo.frameworks import PyMongoInstance
db = MongoClient().test
instance = PyMongoInstance(db)
@instance.register
class User(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"))
class Meta:
collection_name = "user"
# Make sure that unique indexes are created
User.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 manually
Or 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]
Features:
Document and EmbeddedDocument.__dir__()
(see #367).Bug fixes:
None, not casting to bool to prevent
an exception raised by pymongo >= 4 (see #366).Bug fixes:
set_modified, deserialize using inner field
(see #364).Features:
metadata argument (see #328).Bug fixes:
None for references, lists and embedded documents
(see #330)._dict_io_validate to propagate IO validation through DictField
(see #335).Other changes:
Features:
Instance subclasses for each framework to help users migrating
a database from umongo 2 to umongo 3 (see #319).EmbeddedField to allow passing an embedded document as string before its
registration. Unknown embedded document errors in EmbeddedField are now
detected at runtime, not registration time. Also, indexes are now collected
on first use rather than upon registration and should be accesses through
Document.indexes cached property rather than Document.opts.indexes.
(see #322)BaseSchema ordered. This fixes querying on
embedded documents. Make BaseMarshmallowSchema ordered as well.
(see #323)RemoveMissingSchema opt-out. By default,
generated pure marshmallow schemas now skip missing values from Document
instances rather that returning None. This can be changed by setting
MA_BASE_SCHEMA_CLS. (see #325)Bug fixes:
instance = PyMongoInstance(db). (see #318)Features:
Instance: merge BaseInstance,
Instance and LazyLoaderInstance into a single abstract Instance
class. Remove templates argument from Instance. Rename
Instance.init to Instance.set_db. Don't republish concrete framework
instances in umongo top module. (see #314)session context manager to PyMongoInstance and
MotorAsyncIOInstance. This allows to use session related features
(causally consistent reads, transactions) from umongo. (see #315)Features:
Document
and EmbeddedDocument instances. This change is part of a refactor meant
to simplify set / get / delete operations on document objets and (marginally)
improve performance. (see #272)DuplicateKeyError rather than
parse the error message string (see #309).replace argument to commit method to force writing the whole
document rather than updating (see #310).Other changes:
Features:
Document and EmbeddedDocument in queries. (see #303)Features:
ExposeMissing context manager to return
missing rather than None when dumping. Replace FromUmongoSchema
with RemoveMissingSchema. This schema removes missing fields when dumping
by using ExposeMissing internally. Make this feature opt-in by requiring
the user to specify RemoveMissingSchema as MA_BASE_SCHEMA_CLS.
(see #261)mongo_world parameter from
Schema.as_marshmallow_schema. Schemas generated by this method are meant
to (de)serialize umongo objects, not dict straight from database.
(see #299)umongo.Schema. Schemas should inherit
from umongo.abstract.BaseSchema. Expose RemoveMissingSchema as
umongo.RemoveMissingSchema. (see #301)Other changes:
Features:
Let Document inherit from EmbeddedDocument (see #266).
Add MixinDocument allowing Document and EmbeddedDocument to
inherit fields and pre/post methods from mixin objects (see #278).
Backwards-incompatible: Remove as_attribute argument of
BaseInstance.register method. Documents can not be accessed by name as
instance attributes anymore. (see #290)
Bug fixes:
None to a field with _required_validate method
(see #289).Features:
Backwards-incompatible: Revert broken feature introduced in 3.0.0b6 allowing to get fields from mixin classes (see #273).
Backwards-incompatible: Remove allow_inheritance option. Any
Document or EmbeddedDocument may be subclassed (see #270).
Backwards-incompatible: Field raises DocumentDefinitionError rather
than RuntimeError when passed missing kwarg and Document.commit
raises NotCreatedError when passed conditions for a document that is
not in database (see #275).
Features:
Backwards-incompatible: abstract in EmbeddedDocument behaves
consistently with Document. The _cls / cls field is only added
on concrete embedded documents subclassing concrete embedded documents. And
EmbeddedField only accepts concrete embedded documents. (see #86)
Document and EmbeddedDocument may inherits from mixin classes. The
mixin class should appear first (leftmost) in the bases:
class MyDocument(MyMixin, Document). (see #188)
Other changes:
import marshmallow as ma. For convenience, missing and
ValidationError can still be imported as umongo.missing and
umongo.ValidationError.Features:
MA_BASE_SCHEMA_CLS class attribute to
Document and EmbeddedDocument to specify a base class to use in
as_marshmallow_schema. Drop the check_unknown_fields, params and
meta attributes of as_marshmallow_schema. Make mongo_world
kwarg-only. The same effect can be achieved using base schema classes.
This incidentally fixes broken as_marshmallow_schema cache feature.
(see #263)TxMongoDocument.find_with_cursor and
drop support for upstream deprecated find(cursor=True). (see #259).Other changes:
Features:
Document.pk_field and remove
BaseDataProxy.*_by_mongo_name methods (see #257).Features:
ReferenceError with
NoneReferenceError. Review the list of exceptions importable from
root umongo module. (see #251)Bug fixes:
set_by_mongo_name on a field that was not
loaded in a partial load. (see #253)Other changes:
Features:
Bug fixes:
Features:
"marshmallow_" are passed to the
marshmallow schema, rather than only a given list of known parameters.
(see #228)Other changes:
StrictDateTimeField is removed as marshmallow
now provides NaiveDateTimeField and AwareDateTimeField. (see #154)default shall now be provided in deserialized
form. (see #154)Features:
Bug fixes:
find/find_one: pass filter as first positional argument
(see #215).Other changes:
Bug fixes:
ObjectId bonus field: catch TypeError when deserializing
(see #207).Features:
count_documents class method to the
MotorAsyncIODocument class. count_documents attempts 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 by
MotorAsyncIODocument.find strictly adheres to the interface provided by
the underlying driver.Bug fixes:
Reference and GenericReference fields round-trip (see #200).Bug fixes:
BaseDataObject in BaseDataProxy.get_modified_fields
and BaseDataProxy.get_modified_fields_by_mongo_name (see #195).List.is_modified (see #195).List: call set_modified when deleting an element using the del
builtin (see #195).Bug fixes:
StrictDateTimeField (see #189).Bug fixes:
DateTimeField
and LocalDateTimeField (see #189).Bug fixes:
EmbeddedDocument containing fields overriding
_deserialize_from_mongo (see #186).Features:
missing attribute is no longer used in umongo
fields, only default is used. marshmallow_missing and
marshmallow_default attribute can be used to overwrite the value to use
in the pure marshmallow field returned by as_marshmallow_field method
(see #36 and #107).as_marshmallow_field does not pass
load_from, dump_to and attribute to the pure marshmallow field
anymore. It only passes validate, required, allow_none,
dump_only, load_only and error_messages, as well as default
and missing values inferred from umongo's default. Parameters
prefixed with marshmallow_ in the umongo field are passed to the pure
marshmallow field and override their non-prefixed counterpart. (see #170)DictField and ListField don't default to
empty Dict/List. To keep old behaviour, pass dict/list as
default. (see #105)Dict/List as empty rather
than missing (see #105).DateTimeField,
LocalDateTimeField and StrictDateTimeField to keep consistency
between object and database representation (see #172 and #175).DateField (see #178).Bug fixes:
DictField/ListField as a raw Python
dict/list (see #78).default parameter of a Field is deserialized and validated (see #174).Other changes:
Schema cache to as_marshmallow_schema (see #165).DecimalField. This field only works on MongoDB 3.4+. (see #162)UnknownFieldInDBError when an unknown field is found in database
and not using BaseNonStrictDataProxy (see #121)WrappedCursor with
mongomockas_marshmallow_schema params to nested schemas. Since this change, every
field's as_marshmallow_schema method should expect unknown **kwargs (see #101).ListField.as_marshmallow_schema (see #150)meta kwarg to as_marshmallow_schema to pass a dict of attributes
for the schema's Meta class (see #151)strict option to (Embedded)DocumentOpts to allow loading of document
with unknown fields from mongo (see #115)abstract and allow_inheritance options to EmbeddedDocumentas_marshmallow_schema's parameter missing_accessor (see #73, #74)Document.opts.children by offspring and fix grand child
inheritance issue (see #66)Dict and List inherit builtins dict and listEmbeddedDocument also need to be registered by and instance before useDocument.created by is_created (see #14)__getitem__ for Pymongo.Cursor wrapperconditions argument to Document.commitcount method to txmongo<dal>_lazy_loader to configure Document's lazy_collectionFAQs
sync/async MongoDB ODM, yes.
We found that umongo demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.