======================
μMongo: sync/async ODM
======================
.. 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:
- Stay close to the standards MongoDB driver to keep the same API when possible:
use ``find({"field": "value"})`` like usual but retrieve your data nicely OO wrapped !
- Work with multiple drivers (PyMongo_, TxMongo_, motor_asyncio_ and mongomock_ for the moment)
- Tight integration with Marshmallow_ serialization library to easily
dump and load your data with the outside world
- i18n integration to localize validation error messages
- Free software: MIT license
- Test with 90%+ coverage ;-)
.. _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]
=======
History
=======
3.1.0 (2021-12-23)
------------------
Features:
* Add fields list to ``Document`` and ``EmbeddedDocument.__dir__()``
(see #367).
Bug fixes:
* Test database by comparing to ``None``, not casting to ``bool`` to prevent
an exception raised by pymongo >= 4 (see #366).
3.0.1 (2021-10-16)
------------------
Bug fixes:
* Fix ListField.insert: trigger ``set_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 as
``metadata`` argument (see #328).
Bug fixes:
* Fix IO validation of `None` for references, lists and embedded documents
(see #330).
* Add `_dict_io_validate` to propagate IO validation through `DictField`
(see #335).
Other changes:
* *Backwards-incompatible*: Require marshmallow>=3.10.0 (see #328).
3.0.0b14 (2020-12-08)
---------------------
Features:
* Provide ``Instance`` subclasses for each framework to help users migrating
a database from umongo 2 to umongo 3 (see #319).
* *Backwards-incompatible*: Postpone embedded document resolution in
``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)
* *Backwards-incompatible*: Make ``BaseSchema`` ordered. This fixes querying on
embedded documents. Make ``BaseMarshmallowSchema`` ordered as well.
(see #323)
* *Backwards-incompatible*: Make ``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)
3.0.0b13 (2020-11-23)
---------------------
Bug fixes:
* Fix a bug introduced in 3.0.0b12 preventing instance initialization with DB
as parameter as in ``instance = PyMongoInstance(db)``. (see #318)
3.0.0b12 (2020-11-16)
---------------------
Features:
* *Backwards-incompatible*: Rework ``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)
* Add ``session`` context manager to ``PyMongoInstance`` and
``MotorAsyncIOInstance``. 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 on ``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)
* Use structured information provided with ``DuplicateKeyError`` rather than
parse the error message string (see #309).
* Add ``replace`` argument to ``commit`` method 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 passing ``Document`` and ``EmbeddedDocument`` in 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*: Add ``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)
* *Backwards-incompatible*: Remove ``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)
* *Backwards-incompatible*: Remove ``umongo.Schema``. Schemas should inherit
from ``umongo.abstract.BaseSchema``. Expose ``RemoveMissingSchema`` as
``umongo.RemoveMissingSchema``. (see #301)
Other changes:
* *Backwards-incompatible*: Drop Python 3.6 support (see #298).
3.0.0b8 (2020-07-22)
--------------------
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:
* Fix passing ``None`` to a field with ``_required_validate`` method
(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*: 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).
3.0.0b6 (2020-05-04)
--------------------
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:
* *Backwards-incompatible*: marshmallow imports throughout the code are done as
``import marshmallow as ma``. For convenience, ``missing`` and
``ValidationError`` can still be imported as ``umongo.missing`` and
``umongo.ValidationError``.
3.0.0b5 (2020-04-30)
--------------------
Features:
* *Backwards-incompatible*: Add ``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)
* *Backwards-incompatible*: Add ``TxMongoDocument.find_with_cursor`` and
drop support for upstream deprecated ``find(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*: Add ``Document.pk_field`` and remove
``BaseDataProxy.*_by_mongo_name methods`` (see #257).
* *Backwards-incompatible*: Raise AlreadyCreatedError when modifying pk of
created document (see #258).
3.0.0b3 (2020-04-26)
--------------------
Features:
* *Backwards-incompatible*: Replace ``ReferenceError`` with
``NoneReferenceError``. Review the list of exceptions importable from
root ``umongo`` module. (see #251)
Bug fixes:
* Don't modify data when calling ``set_by_mongo_name`` on 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*: ``StrictDateTimeField`` is removed as marshmallow
now provides ``NaiveDateTimeField`` and ``AwareDateTimeField``. (see #154)
* *Backwards-incompatible*: ``default`` shall 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:
* Fix ``find``/``find_one``: pass ``filter`` as first positional argument
(see #215).
Other changes:
* Support Python 3.8 (see #210).
2.1.1 (2019-10-04)
------------------
Bug fixes:
* Fix ``ObjectId`` bonus field: catch ``TypeError`` when deserializing
(see #207).
2.1.0 (2019-06-19)
------------------
Features:
* Add support for motor 2.+ by adding a ``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.
2.0.5 (2019-06-13)
------------------
Bug fixes:
* Ensure ``Reference`` and ``GenericReference`` fields round-trip (see #200).
2.0.4 (2019-05-28)
------------------
Bug fixes:
* Include modified ``BaseDataObject`` in ``BaseDataProxy.get_modified_fields``
and ``BaseDataProxy.get_modified_fields_by_mongo_name`` (see #195).
* Always return a boolean in ``List.is_modified`` (see #195).
* ``List``: call ``set_modified`` when deleting an element using the ``del``
builtin (see #195).
2.0.3 (2019-04-10)
------------------
Bug fixes:
* Fix millisecond overflow when milliseconds round to 1s in
``StrictDateTimeField`` (see #189).
2.0.2 (2019-04-10)
------------------
Bug fixes:
* Fix millisecond overflow when milliseconds round to 1s in ``DateTimeField``
and ``LocalDateTimeField`` (see #189).
2.0.1 (2019-03-25)
------------------
Bug fixes:
* Fix deserialization of ``EmbeddedDocument`` containing fields overriding
``_deserialize_from_mongo`` (see #186).
2.0.0 (2019-03-18)
------------------
Features:
* *Backwards-incompatible*: ``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).
* *Backwards-incompatible*: ``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)
* *Backwards-incompatible*: ``DictField`` and ``ListField`` don't default to
empty ``Dict``/``List``. To keep old behaviour, pass ``dict``/``list`` as
default. (see #105)
* *Backwards-incompatible*: Serialize empty ``Dict``/``List`` as empty rather
than missing (see #105).
* Round datetimes to millisecond precision in ``DateTimeField``,
``LocalDateTimeField`` and ``StrictDateTimeField`` to keep consistency
between object and database representation (see #172 and #175).
* Add ``DateField`` (see #178).
Bug fixes:
* Fix passing a default value to a ``DictField``/``ListField`` as a raw Python
``dict``/``list`` (see #78).
* The ``default`` parameter 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)
------------------
* Add ``Schema`` cache to ``as_marshmallow_schema`` (see #165).
* Add ``DecimalField``. 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)
------------------
* Raise ``UnknownFieldInDBError`` when an unknown field is found in database
and not using ``BaseNonStrictDataProxy`` (see #121)
* Fix (non fatal) crash in garbage collector when using ``WrappedCursor`` with
mongomock
* Depend on pymongo 3.7+ (see #149)
* Pass ``as_marshmallow_schema params`` to nested schemas. Since this change, every
field's ``as_marshmallow_schema`` method should expect unknown ``**kwargs`` (see #101).
* Pass params to container field in ``ListField.as_marshmallow_schema`` (see #150)
* Add ``meta`` kwarg to ``as_marshmallow_schema`` to pass a ``dict`` of attributes
for the schema's ``Meta`` class (see #151)
0.15.0 (2017-08-15)
-------------------
* Add `strict` option 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)
* Add ``abstract`` and ``allow_inheritance`` options to EmbeddedDocument
* Remove buggy ``as_marshmallow_schema``'s parameter ``missing_accessor`` (see #73, #74)
0.12.0 (2016-11-11)
-------------------
* Replace ``Document.opts.children`` by ``offspring`` and fix grand child
inheritance issue (see #66)
* Fix dependency since release of motor 1.0 with breaking API
0.11.0 (2016-11-02)
-------------------
* data_objects ``Dict`` and ``List`` inherit builtins ``dict`` and ``list``
* Document&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 processors
0.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 database
* ``EmbeddedDocument`` also need to be registered by and instance before use
0.8.1 (2016-05-19)
------------------
* Replace ``Document.created`` by ``is_created`` (see #14)
0.8.0 (2016-05-18)
------------------
* Heavy rewrite of the project, lost of API breakage
* Documents are now first defined as templates then implemented
inside an Instance
* DALs has been replaced by frameworks implementations of Builder
* Fix ``__getitem__`` for Pymongo.Cursor wrapper
* Add ``conditions`` argument to Document.commit
* Add ``count`` method to txmongo
0.7.8 (2016-4-28)
-----------------
* Fix setup.py style preventing release of version 0.7.7
0.7.7 (2016-4-28)
-----------------
* Fix await error with Reference.fetch
* Pymongo is now only installed with extra flavours of umongo
0.7.6 (2016-4-28)
-----------------
* Use extras_require to install driver along with umongo
0.7.5 (2016-4-23)
-----------------
* Fixing await (Python >= 3.5) support for motor-asyncio
0.7.4 (2016-4-21)
-----------------
* Fix missing package in setup.py
0.7.3 (2016-4-21)
-----------------
* Fix setup.py style preventing from release
0.7.2 (2016-4-21)
-----------------
* Fix crash when generating indexes on EmbeddedDocument
0.7.1 (2016-4-21)
-----------------
* Fix setup.py not to install tests package
* Pass status to Beta
0.7.0 (2016-4-21)
-----------------
* Add i18n support
* Add MongoMock support
* Documentation has been a lot extended
0.6.1 (2016-4-13)
-----------------
* Add ``<dal>_lazy_loader`` to configure Document's lazy_collection
0.6.0 (2016-4-12)
-----------------
* Heavy improvements everywhere !
0.1.0 (2016-1-22)
-----------------
* First release on PyPI.
Raw data
{
"_id": null,
"home_page": "https://github.com/touilleMan/umongo",
"name": "umongo",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "umongo mongodb pymongo txmongo motor mongomock asyncio twisted",
"author": "Emmanuel Leblond, J\u00e9r\u00f4me Lafr\u00e9choux",
"author_email": "jerome@jolimont.fr",
"download_url": "https://files.pythonhosted.org/packages/b5/5d/bf978380cd25d837c8def3e1841b4f4f997037be52c9de81792fcee96dac/umongo-3.1.0.tar.gz",
"platform": "",
"description": "======================\n\u03bcMongo: sync/async ODM\n======================\n\n.. image:: https://img.shields.io/pypi/v/umongo.svg\n :target: https://pypi.python.org/pypi/umongo\n :alt: Latest version\n\n.. image:: https://img.shields.io/pypi/pyversions/umongo.svg\n :target: https://pypi.org/project/umongo/\n :alt: Python versions\n\n.. image:: https://img.shields.io/badge/marshmallow-3-blue.svg\n :target: https://marshmallow.readthedocs.io/en/latest/upgrading.html\n :alt: marshmallow 3 only\n\n.. image:: https://img.shields.io/pypi/l/umongo.svg\n :target: https://umongo.readthedocs.io/en/latest/license.html\n :alt: License\n\n.. image:: https://dev.azure.com/lafrech/umongo/_apis/build/status/Scille.umongo?branchName=master\n :target: https://dev.azure.com/lafrech/umongo/_build/latest?definitionId=1&branchName=master\n :alt: Build status\n\n.. image:: https://readthedocs.org/projects/umongo/badge/\n :target: http://umongo.readthedocs.io/\n :alt: Documentation\n\n\u03bcMongo is a Python MongoDB ODM. It inception comes from two needs:\nthe lack of async ODM and the difficulty to do document (un)serialization\nwith existing ODMs.\n\nFrom this point, \u03bcMongo made a few design choices:\n\n- Stay close to the standards MongoDB driver to keep the same API when possible:\n use ``find({\"field\": \"value\"})`` like usual but retrieve your data nicely OO wrapped !\n- Work with multiple drivers (PyMongo_, TxMongo_, motor_asyncio_ and mongomock_ for the moment)\n- Tight integration with Marshmallow_ serialization library to easily\n dump and load your data with the outside world\n- i18n integration to localize validation error messages\n- Free software: MIT license\n- Test with 90%+ coverage ;-)\n\n.. _PyMongo: https://api.mongodb.org/python/current/\n.. _TxMongo: https://txmongo.readthedocs.org/en/latest/\n.. _motor_asyncio: https://motor.readthedocs.org/en/stable/\n.. _mongomock: https://github.com/vmalloc/mongomock\n.. _Marshmallow: http://marshmallow.readthedocs.org\n\n\u00b5Mongo requires MongoDB 4.2+ and Python 3.7+.\n\nQuick example\n\n.. code-block:: python\n\n import datetime as dt\n from pymongo import MongoClient\n from umongo import Document, fields, validate\n from umongo.frameworks import PyMongoInstance\n\n db = MongoClient().test\n instance = PyMongoInstance(db)\n\n @instance.register\n class User(Document):\n email = fields.EmailField(required=True, unique=True)\n birthday = fields.DateTimeField(validate=validate.Range(min=dt.datetime(1900, 1, 1)))\n friends = fields.ListField(fields.ReferenceField(\"User\"))\n\n class Meta:\n collection_name = \"user\"\n\n # Make sure that unique indexes are created\n User.ensure_indexes()\n\n goku = User(email='goku@sayen.com', birthday=dt.datetime(1984, 11, 20))\n goku.commit()\n vegeta = User(email='vegeta@over9000.com', friends=[goku])\n vegeta.commit()\n\n vegeta.friends\n # <object umongo.data_objects.List([<object umongo.dal.pymongo.PyMongoReference(document=User, pk=ObjectId('5717568613adf27be6363f78'))>])>\n vegeta.dump()\n # {id': '570ddb311d41c89cabceeddc', 'email': 'vegeta@over9000.com', friends': ['570ddb2a1d41c89cabceeddb']}\n User.find_one({\"email\": 'goku@sayen.com'})\n # <object Document __main__.User({'id': ObjectId('570ddb2a1d41c89cabceeddb'), 'friends': <object umongo.data_objects.List([])>,\n # 'email': 'goku@sayen.com', 'birthday': datetime.datetime(1984, 11, 20, 0, 0)})>\n\nGet it now::\n\n $ pip install umongo # This installs umongo with pymongo\n $ pip install my-mongo-driver # Other MongoDB drivers must be installed manually\n\nOr to get it along with the MongoDB driver you're planing to use::\n\n $ pip install umongo[motor]\n $ pip install umongo[txmongo]\n $ pip install umongo[mongomock]\n\n\n=======\nHistory\n=======\n\n3.1.0 (2021-12-23)\n------------------\n\nFeatures:\n\n* Add fields list to ``Document`` and ``EmbeddedDocument.__dir__()``\n (see #367).\n\nBug fixes:\n\n* Test database by comparing to ``None``, not casting to ``bool`` to prevent\n an exception raised by pymongo >= 4 (see #366).\n\n3.0.1 (2021-10-16)\n------------------\n\nBug fixes:\n\n* Fix ListField.insert: trigger ``set_modified``, deserialize using inner field\n (see #364).\n\n3.0.0 (2021-01-11)\n------------------\n\nFeatures:\n\n* Fix internationalization of generated marshmallow fields for container fields\n (DictField, ListField, NestedField) (see #329).\n* Don't pass field metadata as kwargs (deprecated in marshmallow 3.10.0) but as\n ``metadata`` argument (see #328).\n\nBug fixes:\n\n* Fix IO validation of `None` for references, lists and embedded documents\n (see #330).\n* Add `_dict_io_validate` to propagate IO validation through `DictField`\n (see #335).\n\nOther changes:\n\n* *Backwards-incompatible*: Require marshmallow>=3.10.0 (see #328).\n\n3.0.0b14 (2020-12-08)\n---------------------\n\nFeatures:\n\n* Provide ``Instance`` subclasses for each framework to help users migrating\n a database from umongo 2 to umongo 3 (see #319).\n* *Backwards-incompatible*: Postpone embedded document resolution in\n ``EmbeddedField`` to allow passing an embedded document as string before its\n registration. Unknown embedded document errors in ``EmbeddedField`` are now\n detected at runtime, not registration time. Also, indexes are now collected\n on first use rather than upon registration and should be accesses through\n ``Document.indexes`` cached property rather than ``Document.opts.indexes``.\n (see #322)\n* *Backwards-incompatible*: Make ``BaseSchema`` ordered. This fixes querying on\n embedded documents. Make ``BaseMarshmallowSchema`` ordered as well.\n (see #323)\n* *Backwards-incompatible*: Make ``RemoveMissingSchema`` opt-out. By default,\n generated pure marshmallow schemas now skip missing values from ``Document``\n instances rather that returning ``None``. This can be changed by setting\n ``MA_BASE_SCHEMA_CLS``. (see #325)\n\n3.0.0b13 (2020-11-23)\n---------------------\n\nBug fixes:\n\n* Fix a bug introduced in 3.0.0b12 preventing instance initialization with DB\n as parameter as in ``instance = PyMongoInstance(db)``. (see #318)\n\n3.0.0b12 (2020-11-16)\n---------------------\n\nFeatures:\n\n* *Backwards-incompatible*: Rework ``Instance``: merge ``BaseInstance``,\n ``Instance`` and ``LazyLoaderInstance`` into a single abstract ``Instance``\n class. Remove ``templates`` argument from ``Instance``. Rename\n ``Instance.init`` to ``Instance.set_db``. Don't republish concrete framework\n instances in ``umongo`` top module. (see #314)\n* Add ``session`` context manager to ``PyMongoInstance`` and\n ``MotorAsyncIOInstance``. This allows to use session related features\n (causally consistent reads, transactions) from umongo. (see #315)\n\n3.0.0b11 (2020-11-06)\n---------------------\n\nFeatures:\n\n* *Backwards-incompatible*: Allow setting arbitrary attributes on ``Document``\n and ``EmbeddedDocument`` instances. This change is part of a refactor meant\n to simplify set / get / delete operations on document objets and (marginally)\n improve performance. (see #272)\n* Use structured information provided with ``DuplicateKeyError`` rather than\n parse the error message string (see #309).\n* Add ``replace`` argument to ``commit`` method to force writing the whole\n document rather than updating (see #310).\n\nOther changes:\n\n* Support Python 3.9 (see #311).\n* *Backwards-incompatible*: Drop motor<2.0.0 support (see #312).\n* *Backwards-incompatible*: Drop MongoDB<4.2 support (see #313).\n\n3.0.0b10 (2020-10-12)\n---------------------\n\nFeatures:\n\n* Allow passing ``Document`` and ``EmbeddedDocument`` in queries. (see #303)\n\n3.0.0b9 (2020-10-05)\n--------------------\n\nFeatures:\n\n* Add support for motor 2.2 (see #294). (Picked from 2.3.0.)\n* *Backwards-incompatible*: Add ``ExposeMissing`` context manager to return\n ``missing`` rather than ``None`` when dumping. Replace ``FromUmongoSchema``\n with ``RemoveMissingSchema``. This schema removes missing fields when dumping\n by using ``ExposeMissing`` internally. Make this feature opt-in by requiring\n the user to specify ``RemoveMissingSchema`` as ``MA_BASE_SCHEMA_CLS``.\n (see #261)\n* *Backwards-incompatible*: Remove ``mongo_world`` parameter from\n ``Schema.as_marshmallow_schema``. Schemas generated by this method are meant\n to (de)serialize umongo objects, not ``dict`` straight from database.\n (see #299)\n* *Backwards-incompatible*: Remove ``umongo.Schema``. Schemas should inherit\n from ``umongo.abstract.BaseSchema``. Expose ``RemoveMissingSchema`` as\n ``umongo.RemoveMissingSchema``. (see #301)\n\nOther changes:\n\n* *Backwards-incompatible*: Drop Python 3.6 support (see #298).\n\n\n3.0.0b8 (2020-07-22)\n--------------------\n\nFeatures:\n\n* Let ``Document`` inherit from ``EmbeddedDocument`` (see #266).\n\n* Add ``MixinDocument`` allowing ``Document``\u00a0and ``EmbeddedDocument`` to\n inherit fields and pre/post methods from mixin objects (see #278).\n\n* *Backwards-incompatible*: Remove ``as_attribute`` argument of\n ``BaseInstance.register`` method. Documents can not be accessed by name as\n instance attributes anymore. (see #290)\n\nBug fixes:\n\n* Fix passing ``None`` to a field with ``_required_validate`` method\n (see #289).\n\n3.0.0b7 (2020-05-08)\n--------------------\n\nFeatures:\n\n* *Backwards-incompatible*: Revert broken feature introduced in 3.0.0b6\n allowing to get fields from mixin classes (see #273).\n\n* *Backwards-incompatible*: Remove ``allow_inheritance`` option. Any\n ``Document`` or ``EmbeddedDocument`` may be subclassed (see #270).\n\n* *Backwards-incompatible*: ``Field`` raises ``DocumentDefinitionError`` rather\n than ``RuntimeError`` when passed ``missing`` kwarg and ``Document.commit``\n raises ``NotCreatedError`` when passed ``conditions`` for a document that is\n not in database (see #275).\n\n3.0.0b6 (2020-05-04)\n--------------------\n\nFeatures:\n\n* *Backwards-incompatible*: ``abstract``\u00a0in ``EmbeddedDocument`` behaves\n consistently with ``Document``. The ``_cls`` / ``cls`` field is only added\n on concrete embedded documents subclassing concrete embedded documents. And\n ``EmbeddedField`` only accepts concrete embedded documents. (see #86)\n\n* ``Document`` and ``EmbeddedDocument`` may inherits from mixin classes. The\n mixin class should appear first (leftmost) in the bases:\n ``class MyDocument(MyMixin, Document)``. (see #188)\n\nOther changes:\n\n* *Backwards-incompatible*: marshmallow imports throughout the code are done as\n ``import marshmallow as ma``. For convenience, ``missing`` and\n ``ValidationError`` can still be imported as ``umongo.missing`` and\n ``umongo.ValidationError``.\n\n3.0.0b5 (2020-04-30)\n--------------------\n\nFeatures:\n\n* *Backwards-incompatible*: Add ``MA_BASE_SCHEMA_CLS`` class attribute to\n ``Document`` and ``EmbeddedDocument`` to specify a base class to use in\n ``as_marshmallow_schema``. Drop the ``check_unknown_fields``, ``params`` and\n ``meta``\u00a0attributes of ``as_marshmallow_schema``. Make ``mongo_world``\n kwarg-only. The same effect can be achieved using base schema classes.\n This incidentally fixes broken ``as_marshmallow_schema`` cache feature.\n (see #263)\n* *Backwards-incompatible*: Add ``TxMongoDocument.find_with_cursor`` and\n drop support for upstream deprecated ``find(cursor=True)``. (see #259).\n\nOther changes:\n\n* *Backwards-incompatible*: Require txmongo>=19.2.0 (see #259).\n\n3.0.0b4 (2020-04-27)\n--------------------\n\nFeatures:\n\n* *Backwards-incompatible*: Remove partial load feature (see #256).\n* *Backwards-incompatible*: Add ``Document.pk_field`` and remove\n ``BaseDataProxy.*_by_mongo_name methods`` (see #257).\n* *Backwards-incompatible*: Raise AlreadyCreatedError when modifying pk of\n created document (see #258).\n\n3.0.0b3 (2020-04-26)\n--------------------\n\nFeatures:\n\n* *Backwards-incompatible*: Replace ``ReferenceError`` with\n ``NoneReferenceError``. Review the list of exceptions importable from\n root ``umongo`` module. (see #251)\n\nBug fixes:\n\n* Don't modify data when calling ``set_by_mongo_name`` on a field that was not\n loaded in a partial load. (see #253)\n\nOther changes:\n\n* *Backwards-incompatible*: Drop Python 3.5 support (see #248).\n\n3.0.0b2 (2020-04-18)\n--------------------\n\nFeatures:\n\n* Use fields for keys/values in DictField (see #245).\n\nBug fixes:\n\n* Fix BaseField.__repr__ (see #247).\n\n3.0.0b1 (2020-03-29)\n--------------------\n\nFeatures:\n\n* Support marshmallow 3 (see #154).\n* All field parameters beginning with ``\"marshmallow_\"`` are passed to the\n marshmallow schema, rather than only a given list of known parameters.\n (see #228)\n\nOther changes:\n\n* *Backwards-incompatible*: Drop support for marshmallow 2. See marshmallow\n upgrading guide for a comprehensive list of changes. (see #154)\n* *Backwards-incompatible*: ``StrictDateTimeField`` is removed as marshmallow\n now provides ``NaiveDateTimeField``\u00a0and ``AwareDateTimeField``. (see #154)\n* *Backwards-incompatible*: ``default`` shall now be provided in deserialized\n form. (see #154)\n\n2.3.0 (2020-09-06)\n------------------\n\nFeatures:\n\n* Add support for motor 2.2 (see #294).\n\n2.2.0 (2019-12-18)\n------------------\n\nBug fixes:\n\n* Fix ``find``/``find_one``: pass ``filter`` as first positional argument\n (see #215).\n\nOther changes:\n\n* Support Python 3.8 (see #210).\n\n2.1.1 (2019-10-04)\n------------------\n\nBug fixes:\n\n* Fix ``ObjectId`` bonus field: catch ``TypeError`` when deserializing\n (see #207).\n\n2.1.0 (2019-06-19)\n------------------\n\nFeatures:\n\n* Add support for motor 2.+ by adding a ``count_documents`` class method to the\n ``MotorAsyncIODocument`` class. ``count_documents`` attempts to transparently\n use the correct motor call signature depending on which version of the\n driver is installed. Note that the behavior of the cursor object returned by\n ``MotorAsyncIODocument.find`` strictly adheres to the interface provided by\n the underlying driver.\n\n2.0.5 (2019-06-13)\n------------------\n\nBug fixes:\n\n* Ensure ``Reference`` and ``GenericReference`` fields round-trip (see #200).\n\n2.0.4 (2019-05-28)\n------------------\n\nBug fixes:\n\n* Include modified ``BaseDataObject`` in ``BaseDataProxy.get_modified_fields``\n and ``BaseDataProxy.get_modified_fields_by_mongo_name`` (see #195).\n* Always return a boolean in ``List.is_modified`` (see #195).\n* ``List``: call ``set_modified`` when deleting an element using the ``del``\n builtin (see #195).\n\n2.0.3 (2019-04-10)\n------------------\n\nBug fixes:\n\n* Fix millisecond overflow when milliseconds round to 1s in\n ``StrictDateTimeField`` (see #189).\n\n2.0.2 (2019-04-10)\n------------------\n\nBug fixes:\n\n* Fix millisecond overflow when milliseconds round to 1s in ``DateTimeField``\n and ``LocalDateTimeField`` (see #189).\n\n2.0.1 (2019-03-25)\n------------------\n\nBug fixes:\n\n* Fix deserialization of ``EmbeddedDocument`` containing fields overriding\n ``_deserialize_from_mongo`` (see #186).\n\n2.0.0 (2019-03-18)\n------------------\n\nFeatures:\n\n* *Backwards-incompatible*: ``missing`` attribute is no longer used in umongo\n fields, only ``default`` is used. ``marshmallow_missing`` and\n ``marshmallow_default`` attribute can be used to overwrite the value to use\n in the pure marshmallow field returned by ``as_marshmallow_field`` method\n (see #36 and #107).\n* *Backwards-incompatible*: ``as_marshmallow_field`` does not pass\n ``load_from``, ``dump_to`` and ``attribute`` to the pure marshmallow field\n anymore. It only passes ``validate``, ``required``, ``allow_none``,\n ``dump_only``, ``load_only`` and ``error_messages``, as well as ``default``\n and ``missing`` values inferred from umongo's ``default``. Parameters\n prefixed with ``marshmallow_`` in the umongo field are passed to the pure\n marshmallow field and override their non-prefixed counterpart. (see #170)\n* *Backwards-incompatible*: ``DictField`` and ``ListField`` don't default to\n empty ``Dict``/``List``. To keep old behaviour, pass ``dict``/``list`` as\n default. (see #105)\n* *Backwards-incompatible*: Serialize empty ``Dict``/``List`` as empty rather\n than missing (see #105).\n* Round datetimes to millisecond precision in ``DateTimeField``,\n ``LocalDateTimeField`` and ``StrictDateTimeField`` to keep consistency\n between object and database representation (see #172 and #175).\n* Add ``DateField`` (see #178).\n\nBug fixes:\n\n* Fix passing a default value to a ``DictField``/``ListField`` as a raw Python\n ``dict``/``list`` (see #78).\n* The ``default`` parameter of a Field is deserialized and validated (see #174).\n\nOther changes:\n\n* Support Python 3.7 (see #181).\n* *Backwards-incompatible*: Drop Python 3.4 support (see #176) and only use\n async/await coroutine style in asyncio framework (see #179).\n\n1.2.0 (2019-02-08)\n------------------\n\n* Add ``Schema`` cache to ``as_marshmallow_schema`` (see #165).\n* Add ``DecimalField``. This field only works on MongoDB 3.4+. (see #162)\n\n1.1.0 (2019-01-14)\n------------------\n\n* Fix bug when filtering by id in a Document subclass find query (see #145).\n* Fix __getattr__ to allow copying and deepcopying Document and EmbeddedDocument\n (see #157).\n* Add Document.clone() method (see #158).\n\n1.0.0 (2018-11-29)\n------------------\n* Raise ``UnknownFieldInDBError`` when an unknown field is found in database\n and not using ``BaseNonStrictDataProxy`` (see #121)\n* Fix (non fatal) crash in garbage collector when using ``WrappedCursor`` with\n mongomock\n* Depend on pymongo 3.7+ (see #149)\n* Pass ``as_marshmallow_schema params`` to nested schemas. Since this change, every\n field's ``as_marshmallow_schema`` method should expect unknown ``**kwargs`` (see #101).\n* Pass params to container field in ``ListField.as_marshmallow_schema`` (see #150)\n* Add ``meta`` kwarg to ``as_marshmallow_schema`` to pass a ``dict`` of attributes\n for the schema's ``Meta`` class (see #151)\n\n0.15.0 (2017-08-15)\n-------------------\n* Add `strict` option to (Embedded)DocumentOpts to allow loading of document\n with unknown fields from mongo (see #115)\n* Fix fields serialization/deserialization when allow_none is True (see #69)\n* Fix ReferenceFild assignment from another ReferenceField (see #110)\n* Fix deletion of field proxied by a property (see #109)\n* Fix StrictDateTime bonus field: _deserialize does not accept datetime.datetime\n instances (see #106)\n* Add force_reload param to Reference.fetch (see #96)\n\n0.14.0 (2017-03-03)\n-------------------\n* Fix bug in mashmallow tag handling (see #90)\n* Fix allow none in DataProxy.set (see #89)\n* Support motor 1.1 (see #87)\n\n0.13.0 (2017-01-02)\n-------------------\n\n* Fix deserialization error with nested EmbeddedDocuments (see #84, #67)\n* Add ``abstract`` and ``allow_inheritance`` options to EmbeddedDocument\n* Remove buggy ``as_marshmallow_schema``'s parameter ``missing_accessor`` (see #73, #74)\n\n0.12.0 (2016-11-11)\n-------------------\n\n* Replace ``Document.opts.children`` by ``offspring`` and fix grand child\n inheritance issue (see #66)\n* Fix dependency since release of motor 1.0 with breaking API\n\n0.11.0 (2016-11-02)\n-------------------\n\n* data_objects ``Dict`` and ``List`` inherit builtins ``dict`` and ``list``\n* Document&EmbeddedDocument store fields passed during initialization\n as modified (see #50)\n* Required field inside embedded document are handled correctly (see #61)\n* Document support marshmallow's pre/post processors\n\n0.10.0 (2016-09-29)\n-------------------\n\n* Add pre/post update/insert/delete hooks (see #22)\n* Provide Umongo to Marshmallow schema/field conversion with\n schema.as_marshmallow_schema() and field.as_marshmallow_field() (see #34)\n* List and Dict inherit from collections's UserList and UserDict instead\n of builtins types (needed due to metaprogramming conflict otherwise)\n* DeleteError and UpdateError returns the driver result object instead\n of the raw error dict (except for motor which only has raw error dict)\n\n0.9.0 (2016-06-11)\n------------------\n\n* Queries can now be expressed with the document's fields name instead of the\n name in database\n* ``EmbeddedDocument`` also need to be registered by and instance before use\n\n0.8.1 (2016-05-19)\n------------------\n\n* Replace ``Document.created`` by ``is_created`` (see #14)\n\n0.8.0 (2016-05-18)\n------------------\n\n* Heavy rewrite of the project, lost of API breakage\n* Documents are now first defined as templates then implemented\n inside an Instance\n* DALs has been replaced by frameworks implementations of Builder\n* Fix ``__getitem__`` for Pymongo.Cursor wrapper\n* Add ``conditions`` argument to Document.commit\n* Add ``count`` method to txmongo\n\n0.7.8 (2016-4-28)\n-----------------\n\n* Fix setup.py style preventing release of version 0.7.7\n\n0.7.7 (2016-4-28)\n-----------------\n\n* Fix await error with Reference.fetch\n* Pymongo is now only installed with extra flavours of umongo\n\n0.7.6 (2016-4-28)\n-----------------\n\n* Use extras_require to install driver along with umongo\n\n0.7.5 (2016-4-23)\n-----------------\n\n* Fixing await (Python >= 3.5) support for motor-asyncio\n\n0.7.4 (2016-4-21)\n-----------------\n\n* Fix missing package in setup.py\n\n0.7.3 (2016-4-21)\n-----------------\n\n* Fix setup.py style preventing from release\n\n0.7.2 (2016-4-21)\n-----------------\n\n* Fix crash when generating indexes on EmbeddedDocument\n\n0.7.1 (2016-4-21)\n-----------------\n\n* Fix setup.py not to install tests package\n* Pass status to Beta\n\n0.7.0 (2016-4-21)\n-----------------\n\n* Add i18n support\n* Add MongoMock support\n* Documentation has been a lot extended\n\n0.6.1 (2016-4-13)\n-----------------\n\n* Add ``<dal>_lazy_loader`` to configure Document's lazy_collection\n\n0.6.0 (2016-4-12)\n-----------------\n\n* Heavy improvements everywhere !\n\n0.1.0 (2016-1-22)\n-----------------\n\n* First release on PyPI.\n\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "sync/async MongoDB ODM, yes.",
"version": "3.1.0",
"split_keywords": [
"umongo",
"mongodb",
"pymongo",
"txmongo",
"motor",
"mongomock",
"asyncio",
"twisted"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "9e696950ac843a82d9bc2ea4c479c2ca",
"sha256": "f6913027651ae673d71aaf54285f9ebf1e49a3f57662e526d029ba72e1a3fcd5"
},
"downloads": -1,
"filename": "umongo-3.1.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "9e696950ac843a82d9bc2ea4c479c2ca",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 50545,
"upload_time": "2021-12-23T08:52:40",
"upload_time_iso_8601": "2021-12-23T08:52:40.287982Z",
"url": "https://files.pythonhosted.org/packages/a9/01/d120ee849d86f4e4360cd66f05ab7672fcf7f0549bd88cc8ab092b962949/umongo-3.1.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "028652a4b586acd7558d3a9e77d1b686",
"sha256": "20c72f09edae931285c22c1928862af35b90ec639a4dac2dbf015aaaac00e931"
},
"downloads": -1,
"filename": "umongo-3.1.0.tar.gz",
"has_sig": false,
"md5_digest": "028652a4b586acd7558d3a9e77d1b686",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 100345,
"upload_time": "2021-12-23T08:52:42",
"upload_time_iso_8601": "2021-12-23T08:52:42.436914Z",
"url": "https://files.pythonhosted.org/packages/b5/5d/bf978380cd25d837c8def3e1841b4f4f997037be52c9de81792fcee96dac/umongo-3.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-12-23 08:52:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "touilleMan",
"github_project": "umongo",
"lcname": "umongo"
}
JSON
