fix: Add PyMongo 4.13+ async dependency management and documentation

- Add HAS_ASYNC_SUPPORT check with proper error messages
- Update setup.py with async extras requirement
- Add PyMongo 4.13+ version to tox.ini for testing
- Update README.rst with async installation instructions
- Fix pre-commit formatting and linting issues
- Support Python 3.7-3.13 with proper version constraints

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: jeonghanjoo

README.rst

@@ -51,14 +51,22 @@ to both create the virtual environment and install the package. Otherwise, you c
 download the source from `GitHub <https://github.com/MongoEngine/mongoengine>`_ and
 run ``python setup.py install``.
 
+For async support, you need PyMongo 4.13+ and can install it with:
+
+.. code-block:: shell
+
+    # Install MongoEngine with async support
+    $ python -m pip install mongoengine[async]
+
 The support for Python2 was dropped with MongoEngine 0.20.0
 
 Dependencies
 ============
 All of the dependencies can easily be installed via `python -m pip <https://pip.pypa.io/>`_.
-At the very least, you'll need these two packages to use MongoEngine:
+At the very least, you'll need these packages to use MongoEngine:
 
-- pymongo>=3.12
+- pymongo>=3.12 (for synchronous operations)
+- pymongo>=4.13 (for asynchronous operations)
 
 If you utilize a ``DateTimeField``, you might also use a more flexible date parser:
 
@@ -152,7 +160,7 @@ All major database operations are available with async/await syntax:
         post = await TextPost.objects.async_get(title='Async Post')
         posts = await TextPost.objects.filter(tags='python').async_to_list()
         count = await TextPost.objects.async_count()
-        
+
         # Async iteration
         async for post in TextPost.objects.filter(published=True):
             print(post.title)
@@ -176,10 +184,10 @@ All major database operations are available with async/await syntax:
         from mongoengine import FileField
         class MyDoc(Document):
             file = FileField()
-        
+
         doc = MyDoc()
         await MyDoc.file.async_put(file_data, instance=doc)
-        
+
         # Context managers
         from mongoengine import async_switch_db
         async with async_switch_db(MyDoc, 'other_db'):
@@ -205,20 +213,20 @@ All major database operations are available with async/await syntax:
 The following features are intentionally not implemented due to low priority or complexity:
 
 - **async_values()**, **async_values_list()**: Field projection methods
-  
+
   *Reason*: Low usage frequency in typical applications. Can be implemented if needed.
 
 - **async_explain()**: Query execution plan analysis
-  
+
   *Reason*: Debugging/optimization feature with limited general use.
 
 - **Hybrid Signal System**: Automatic sync/async signal handling
-  
-  *Reason*: High complexity due to backward compatibility requirements. 
+
+  *Reason*: High complexity due to backward compatibility requirements.
   Consider as separate project if needed.
 
 - **ListField with ReferenceField**: Automatic AsyncReferenceProxy conversion
-  
+
   *Reason*: Complex implementation requiring deep changes to ListField.
   Manual async dereferencing is required for now.
 

docs/guide/async-support.rst

@@ -62,17 +62,17 @@ Basic Queries
 
     # Get single document
     user = await User.objects.async_get(name="John")
-    
+
     # Get first matching document
     user = await User.objects.filter(email__contains="@gmail.com").async_first()
-    
+
     # Count documents
     count = await User.objects.async_count()
     total_users = await User.objects.filter(active=True).async_count()
-    
+
     # Check existence
     exists = await User.objects.filter(name="John").async_exists()
-    
+
     # Convert to list
     users = await User.objects.filter(active=True).async_to_list()
 
@@ -116,10 +116,10 @@ Update Operations
 
     # Update single document
     result = await User.objects.filter(name="John").async_update_one(email="[email protected]")
-    
+
     # Bulk update
     result = await User.objects.filter(active=False).async_update(active=True)
-    
+
     # Update with operators
     await User.objects.filter(name="John").async_update(inc__login_count=1)
     await User.objects.filter(email="[email protected]").async_update(
@@ -134,7 +134,7 @@ Delete Operations
 
     # Delete matching documents
     result = await User.objects.filter(active=False).async_delete()
-    
+
     # Delete with cascade (if references exist)
     await User.objects.filter(name="John").async_delete()
 
@@ -160,7 +160,7 @@ In async context, reference fields return an ``AsyncReferenceProxy`` that requir
     # Create and save documents
     user = User(name="Alice", email="[email protected]")
     await user.async_save()
-    
+
     post = Post(title="My Post", author=user)
     await post.async_save()
 
@@ -193,31 +193,31 @@ File Storage
 .. code-block:: python
 
     from mongoengine import Document, FileField
-    
+
     class MyDocument(Document):
         name = StringField()
         file = FileField()
 
     # Store file asynchronously
     doc = MyDocument(name="My Document")
-    
+
     with open("example.txt", "rb") as f:
         file_data = f.read()
-    
+
     # Put file
     await MyDocument.file.async_put(file_data, instance=doc, filename="example.txt")
     await doc.async_save()
 
     # Read file
     file_content = await MyDocument.file.async_read(doc)
-    
+
     # Get file metadata
     file_proxy = await MyDocument.file.async_get(doc)
     print(f"File size: {file_proxy.length}")
-    
+
     # Delete file
     await MyDocument.file.async_delete(doc)
-    
+
     # Replace file
     await MyDocument.file.async_replace(new_file_data, doc, filename="new_example.txt")
 
@@ -235,13 +235,13 @@ MongoDB transactions are supported through the ``async_run_in_transaction`` cont
             # All operations within this block are transactional
             sender = await Account.objects.async_get(user_id="sender123")
             receiver = await Account.objects.async_get(user_id="receiver456")
-            
+
             sender.balance -= 100
             receiver.balance += 100
-            
+
             await sender.async_save()
             await receiver.async_save()
-            
+
             # Automatically commits on success, rolls back on exception
 
     # Usage
@@ -305,7 +305,7 @@ Aggregation Pipelines
     pipeline = [
         {"$match": {"active": True}},
         {"$group": {
-            "_id": "$department", 
+            "_id": "$department",
             "count": {"$sum": 1},
             "avg_salary": {"$avg": "$salary"}
         }},
@@ -327,7 +327,7 @@ Distinct Values
     # Get unique values
     departments = await User.objects.async_distinct("department")
     active_emails = await User.objects.filter(active=True).async_distinct("email")
-    
+
     # Distinct on embedded documents
     cities = await User.objects.async_distinct("address.city")
 
@@ -362,7 +362,7 @@ You can use both sync and async operations in the same application by using diff
     # Sync connection
     connect('mydb', alias='sync_conn')
 
-    # Async connection  
+    # Async connection
     await connect_async('mydb', alias='async_conn')
 
     # Configure models to use specific connections
@@ -409,14 +409,14 @@ Batch Processing
     async def process_users_in_batches(batch_size=100):
         total = await User.objects.async_count()
         processed = 0
-        
+
         while processed < total:
             batch = await User.objects.skip(processed).limit(batch_size).async_to_list()
-            
+
             for user in batch:
                 await process_single_user(user)
                 await user.async_save()
-            
+
             processed += len(batch)
             print(f"Processed {processed}/{total} users")
 
@@ -475,7 +475,7 @@ Query execution plan analysis is not implemented as it's primarily a debugging f
 .. code-block:: python
 
     from mongoengine.connection import get_db
-    
+
     db = get_db()  # Get async database
     collection = db[User._get_collection_name()]
     explanation = await collection.find({"active": True}).explain()
@@ -516,13 +516,13 @@ Step-by-Step Migration
 ----------------------
 
 1. **Update connection**:
-   
+
    .. code-block:: python
 
        # Before
        connect('mydb')
-       
-       # After  
+
+       # After
        await connect_async('mydb')
 
 2. **Update function signatures**:
@@ -532,7 +532,7 @@ Step-by-Step Migration
        # Before
        def get_user(name):
            return User.objects.get(name=name)
-       
+
        # After
        async def get_user(name):
            return await User.objects.async_get(name=name)
@@ -546,7 +546,7 @@ Step-by-Step Migration
        users = User.objects.filter(active=True)
        for user in users:
            process(user)
-       
+
        # After
        await user.async_save()
        async for user in User.objects.filter(active=True):
@@ -558,7 +558,7 @@ Step-by-Step Migration
 
        # Before (sync context)
        author = post.author  # Automatic dereferencing
-       
+
        # After (async context)
        author = await post.author.async_fetch()  # Explicit fetching
 
@@ -571,4 +571,4 @@ Compatibility Notes
 - **Performance**: Async operations provide better I/O concurrency
 - **MongoDB Support**: Works with all MongoDB versions supported by MongoEngine
 
-For more examples and advanced usage, see the `API Reference <../apireference.html>`_.
+For more examples and advanced usage, see the `API Reference <../apireference.html>`_.