Skip to content

Commit fa21035

Browse files
abhinand-cabhinand-c
committed
Merge remote-tracking branch 'origin/feat/async' into test
# Conflicts: # docs/requirements.txt
2 parents 689ae95 + 68816ac commit fa21035

28 files changed

+2685
-1934
lines changed

‎README.rst‎

Lines changed: 141 additions & 96 deletions
Original file line numberDiff line numberDiff line change
@@ -1,155 +1,200 @@
11
===========
22
MongoEngine
33
===========
4-
:Info: MongoEngine is an ORM-like layer on top of PyMongo.
4+
5+
:Info: MongoEngine is an Object-Document Mapper (ODM) for MongoDB.
56
:Repository: https://github.com/MongoEngine/mongoengine
67
:Author: Harry Marr (http://github.com/hmarr)
78
:Maintainer: Bastien Gerard (http://github.com/bagerard)
89

910
.. image:: https://github.com/MongoEngine/mongoengine/actions/workflows/github-actions.yml/badge.svg?branch=master
10-
:target: https://github.com/MongoEngine/mongoengine/actions
11+
:target: https://github.com/MongoEngine/mongoengine/actions
1112

1213
.. image:: https://coveralls.io/repos/github/MongoEngine/mongoengine/badge.svg?branch=master
13-
:target: https://coveralls.io/github/MongoEngine/mongoengine?branch=master
14+
:target: https://coveralls.io/github/MongoEngine/mongoengine?branch=master
1415

1516
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
16-
:target: https://github.com/ambv/black
17+
:target: https://github.com/psf/black
1718

1819
.. image:: https://pepy.tech/badge/mongoengine/month
19-
:target: https://pepy.tech/project/mongoengine
20+
:target: https://pepy.tech/project/mongoengine
2021

2122
.. image:: https://img.shields.io/pypi/v/mongoengine.svg
22-
:target: https://pypi.python.org/pypi/mongoengine
23-
23+
:target: https://pypi.python.org/pypi/mongoengine
2424

2525
.. image:: https://readthedocs.org/projects/mongoengine-odm/badge/?version=latest
26-
:target: https://readthedocs.org/projects/mongoengine-odm/builds/
26+
:target: https://mongoengine-odm.readthedocs.io/
27+
2728

2829
About
2930
=====
30-
MongoEngine is a Python Object-Document Mapper for working with MongoDB.
31-
Documentation is available at https://mongoengine-odm.readthedocs.io - there
32-
is currently a `tutorial <https://mongoengine-odm.readthedocs.io/tutorial.html>`_,
33-
a `user guide <https://mongoengine-odm.readthedocs.io/guide/index.html>`_, and
34-
an `API reference <https://mongoengine-odm.readthedocs.io/apireference.html>`_.
31+
32+
MongoEngine is a Python Object-Document Mapper (ODM) that provides a high-level,
33+
Pythonic API for working with MongoDB. It builds on top of PyMongo and offers
34+
schema enforcement, validation, inheritance, and both synchronous and
35+
asynchronous query APIs.
36+
37+
Documentation is available at:
38+
https://mongoengine-odm.readthedocs.io
39+
40+
Including:
41+
42+
- Tutorial
43+
- User Guide
44+
- API Reference
45+
3546

3647
Supported MongoDB Versions
3748
==========================
38-
MongoEngine is currently tested against MongoDB v4.4, v5.0, v6.0, v7.0 and
39-
v8.0. Future versions should be supported as well, but aren't actively tested
40-
at the moment. Make sure to open an issue or submit a pull request if you
41-
experience any problems with a more recent MongoDB versions.
49+
50+
MongoEngine is tested against the following MongoDB versions:
51+
52+
- MongoDB 4.2
53+
- MongoDB 4.4
54+
- MongoDB 5.0
55+
- MongoDB 6.0
56+
- MongoDB 7.0
57+
- MongoDB 8.0
58+
59+
Newer MongoDB versions are expected to work. Please report issues if encountered.
60+
4261

4362
Installation
4463
============
45-
We recommend the use of `virtualenv <https://virtualenv.pypa.io/>`_ and of
46-
`pip <https://pip.pypa.io/>`_. You can then use ``python -m pip install -U mongoengine``.
47-
You may also have `setuptools <http://peak.telecommunity.com/DevCenter/setuptools>`_
48-
and thus you can use ``easy_install -U mongoengine``. Another option is
49-
`pipenv <https://docs.pipenv.org/>`_. You can then use ``pipenv install mongoengine``
50-
to both create the virtual environment and install the package. Otherwise, you can
51-
download the source from `GitHub <https://github.com/MongoEngine/mongoengine>`_ and
52-
run ``python setup.py install``.
5364

54-
The support for Python2 was dropped with MongoEngine 0.20.0
65+
We recommend using ``virtualenv`` and ``pip``:
66+
67+
.. code-block:: shell
68+
69+
python -m pip install -U mongoengine
70+
71+
Alternatively:
72+
73+
.. code-block:: shell
74+
75+
pip install mongoengine
76+
77+
Python 3.8+ is required. Python 2 support was dropped in MongoEngine 0.20.0.
78+
5579

5680
Dependencies
5781
============
58-
All of the dependencies can easily be installed via `python -m pip <https://pip.pypa.io/>`_.
59-
At the very least, you'll need these two packages to use MongoEngine:
6082

61-
- pymongo>=3.12
83+
Core dependency:
6284

63-
If you utilize a ``DateTimeField``, you might also use a more flexible date parser:
85+
- pymongo >= 3.12
6486

65-
- dateutil>=2.1.0
87+
Optional dependencies:
6688

67-
If you need to use an ``ImageField`` or ``ImageGridFsProxy``:
89+
- python-dateutil (for DateTimeField parsing)
90+
- Pillow (for ImageField / GridFS)
91+
- blinker (for signals)
6892

69-
- Pillow>=7.0.0
7093

71-
If you need to use signals:
94+
Synchronous Usage
95+
=================
7296

73-
- blinker>=1.3
97+
A simple synchronous example:
7498

75-
Examples
76-
========
77-
Some simple examples of what MongoEngine code looks like:
99+
.. code-block:: python
78100
79-
.. code :: python
80101
import datetime
81-
from mongoengine import *
102+
from mongoengine import (
103+
connect,
104+
Document,
105+
StringField,
106+
DateTimeField,
107+
ListField,
108+
)
82109
83-
connect('mydb')
110+
connect("mydb")
84111
85112
class BlogPost(Document):
86113
title = StringField(required=True, max_length=200)
87-
posted = DateTimeField(default=lambda: datetime.datetime.now(datetime.timezone.utc))
114+
posted = DateTimeField(default=datetime.datetime.utcnow)
88115
tags = ListField(StringField(max_length=50))
89-
meta = {'allow_inheritance': True}
90-
91-
class TextPost(BlogPost):
92-
content = StringField(required=True)
93-
94-
class LinkPost(BlogPost):
95-
url = StringField(required=True)
96-
97-
# Create a text-based post
98-
>>> post1 = TextPost(title='Using MongoEngine', content='See the tutorial')
99-
>>> post1.tags = ['mongodb', 'mongoengine']
100-
>>> post1.save()
101-
102-
# Create a link-based post
103-
>>> post2 = LinkPost(title='MongoEngine Docs', url='hmarr.com/mongoengine')
104-
>>> post2.tags = ['mongoengine', 'documentation']
105-
>>> post2.save()
106-
107-
# Iterate over all posts using the BlogPost superclass
108-
>>> for post in BlogPost.objects:
109-
... print('===', post.title, '===')
110-
... if isinstance(post, TextPost):
111-
... print(post.content)
112-
... elif isinstance(post, LinkPost):
113-
... print('Link:', post.url)
114-
...
115-
116-
# Count all blog posts and its subtypes
117-
>>> BlogPost.objects.count()
118-
2
119-
>>> TextPost.objects.count()
120-
1
121-
>>> LinkPost.objects.count()
122-
1
123-
124-
# Count tagged posts
125-
>>> BlogPost.objects(tags='mongoengine').count()
126-
2
127-
>>> BlogPost.objects(tags='mongodb').count()
128-
1
116+
117+
post = BlogPost(
118+
title="Using MongoEngine",
119+
tags=["mongodb", "mongoengine"],
120+
)
121+
post.save()
122+
123+
count = BlogPost.objects(tags="mongoengine").count()
124+
print(count)
125+
126+
127+
Async Usage
128+
===========
129+
130+
MongoEngine provides a **fully supported asyncio-native API**.
131+
The async API mirrors the synchronous API and uses ``.aobjects`` along with
132+
``await`` for all I/O operations.
133+
134+
Async support is **first-class** and designed for modern Python applications.
135+
136+
.. code-block:: python
137+
138+
import asyncio
139+
from mongoengine import (
140+
Document,
141+
StringField,
142+
async_connect,
143+
)
144+
145+
async_connect("mydb")
146+
147+
class User(Document):
148+
name = StringField(required=True)
149+
150+
async def main():
151+
# Create
152+
alice = await User.aobjects.create(name="Alice")
153+
154+
# Query
155+
first = await User.aobjects.first()
156+
assert first == alice
157+
158+
# Update
159+
await User.aobjects(name="Alice").update(set__name="Alicia")
160+
161+
# Delete
162+
await User.aobjects(name="Alicia").delete()
163+
164+
asyncio.run(main())
165+
166+
129167
130168
Tests
131169
=====
132-
To run the test suite, ensure you are running a local instance of MongoDB on
133-
the standard port and have ``pytest`` installed. Then, run ``pytest tests/``.
134170

135-
To run the test suite on every supported Python and PyMongo version, you can
136-
use ``tox``. You'll need to make sure you have each supported Python version
137-
installed in your environment and then:
171+
To run the test suite locally:
172+
173+
.. code-block:: shell
174+
175+
pytest tests/
176+
177+
To run against all supported Python and MongoDB versions:
138178

139179
.. code-block:: shell
140180
141-
# Install tox
142-
$ python -m pip install tox
143-
# Run the test suites
144-
$ tox
181+
python -m pip install tox
182+
tox
183+
145184
146185
Community
147186
=========
148-
- `MongoEngine Users mailing list
149-
<http://groups.google.com/group/mongoengine-users>`_
150-
- `MongoEngine Developers mailing list
151-
<http://groups.google.com/group/mongoengine-dev>`_
187+
188+
- MongoEngine Users mailing list:
189+
http://groups.google.com/group/mongoengine-users
190+
- MongoEngine Developers mailing list:
191+
http://groups.google.com/group/mongoengine-dev
192+
152193

153194
Contributing
154195
============
155-
We welcome contributions! See the `Contribution guidelines <https://github.com/MongoEngine/mongoengine/blob/master/CONTRIBUTING.rst>`_
196+
197+
Contributions are welcome!
198+
199+
Please see:
200+
https://github.com/MongoEngine/mongoengine/blob/master/CONTRIBUTING.rst

‎docs/apireference.rst‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,17 @@ Connecting
66
==========
77

88
.. autofunction:: mongoengine.connect
9+
.. autofunction:: mongoengine.async_connect
910
.. autofunction:: mongoengine.register_connection
11+
.. autofunction:: mongoengine.async_register_connection
12+
.. autofunction:: mongoengine.disconnect
13+
.. autofunction:: mongoengine.async_disconnect
14+
.. autofunction:: mongoengine.disconnect_all
15+
.. autofunction:: mongoengine.async_disconnect_all
16+
.. autofunction:: mongoengine.get_db
17+
.. autofunction:: mongoengine.async_get_db
18+
.. autofunction:: mongoengine.get_connection
19+
.. autofunction:: mongoengine.async_get_connection
1020

1121
Documents
1222
=========
@@ -20,6 +30,11 @@ Documents
2030
A :class:`~mongoengine.queryset.QuerySet` object that is created lazily
2131
on access.
2232

33+
.. attribute:: aobjects
34+
35+
An :class:`~mongoengine.queryset.AsyncQuerySet` object that is created
36+
lazily on access.
37+
2338
.. autoclass:: mongoengine.EmbeddedDocument
2439
:members:
2540
:inherited-members:
@@ -46,8 +61,10 @@ Context Managers
4661

4762
.. autoclass:: mongoengine.context_managers.switch_db
4863
.. autoclass:: mongoengine.context_managers.switch_collection
49-
.. autoclass:: mongoengine.context_managers.no_dereference
64+
.. autoclass:: mongoengine.context_managers.no_sub_classes
5065
.. autoclass:: mongoengine.context_managers.query_counter
66+
.. autoclass:: mongoengine.context_managers.async_query_counter
67+
.. autoclass:: mongoengine.context_managers.run_in_transaction
5168

5269
Querying
5370
========
@@ -66,6 +83,13 @@ Querying
6683

6784
.. automethod:: mongoengine.queryset.QuerySetNoCache.__call__
6885

86+
.. autoclass:: mongoengine.queryset.AsyncQuerySet
87+
:members:
88+
:inherited-members:
89+
90+
.. autoclass:: mongoengine.queryset.AsyncQuerySetNoCache
91+
:members:
92+
6993
.. autofunction:: mongoengine.queryset.queryset_manager
7094

7195
Fields
@@ -93,7 +117,6 @@ Fields
93117
.. autoclass:: mongoengine.fields.MapField
94118
.. autoclass:: mongoengine.fields.ReferenceField
95119
.. autoclass:: mongoengine.fields.GenericReferenceField
96-
.. autoclass:: mongoengine.fields.CachedReferenceField
97120
.. autoclass:: mongoengine.fields.BinaryField
98121
.. autoclass:: mongoengine.fields.FileField
99122
.. autoclass:: mongoengine.fields.ImageField

0 commit comments

Comments
 (0)