PyMongo Driver

https://www.mongodb.com/docs/languages/python/pymongo-driver/current
Admin
PyMongo is the official MongoDB driver for Python, providing tools and methods for interacting with...
Tokens:78,625
Snippets:1,021
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install PyMongoExplain

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/aggregation

Command to install the library required for explaining aggregation operations.

```sh
python3 -m pip install pymongoexplain
```

--------------------------------

### Install Dependencies

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/flask-celery-integration

Command to install the necessary Python packages for the application.

```bash
pip install flask-pymongo Flask-Mail celery
```

--------------------------------

### Install pytest

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/test-package-library

Command to install the pytest testing framework.

```shell
pip install -U pytest
```

--------------------------------

### Install Azure Identity Library

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/authentication/oidc

Install the required package for fetching Azure credentials.

```sh
python3 -m pip install azure-identity
```

--------------------------------

### Install build and twine packages

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/test-package-library

Command to install tools required for packaging and publishing the library.

```shell
python -m pip install --upgrade build twine
```

--------------------------------

### Start the Flask application

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/flask-azure

Run this command in your working directory to start the local development server.

```bash
flask run
```

--------------------------------

### Clone the FastAPI sample repository

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/fastapi-integration

Use git to download the example project and navigate into the directory.

```shell
git clone git@github.com:mongodb-developer/mongodb-pymongo-fastapi.git
cd mongodb-pymongo-fastapi
```

--------------------------------

### Build process output

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/test-package-library

Example output generated after successfully running the build command.

```shell
* Creating isolated environment: venv+pip...
* Installing packages in isolated environment:
  - hatchling
* Getting build dependencies for sdist...
* Building sdist...
* Building wheel from sdist
* Creating isolated environment: venv+pip...
* Installing packages in isolated environment:
  - hatchling
* Getting build dependencies for wheel...
* Building wheel...
Successfully built sample_application-0.0.1.tar.gz and sample_application-0.0.1-py3-none-any.whl
```

--------------------------------

### Database Command Output

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/aggregation

Example output for the database command explanation.

```javascript
...
'command': {'aggregate': 'collection',
  'pipeline': [{'$match': {'cuisine': 'Bakery'}},
               {'$group': {'_id': '$borough',
                           'count': {'$sum': 1}}}],
  'explain': True,
...
```

--------------------------------

### Install project dependencies

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/fastapi-integration

Install the required Python packages from the requirements file within an active virtual environment.

```shell
cd mongodb-pymongo-fastapi
pip install -r requirements.txt
```

--------------------------------

### Publish process output

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/test-package-library

Example output generated after successfully uploading the package to PyPI.

```shell
* Uploading distributions to https://upload.pypi.org/legacy/
* Enter your username:
* Enter your password:
* Uploading sample_application-0.0.1-py3-none-any.whl
* Uploading sample_application-0.0.1.tar.gz
* View at: https://pypi.org/project/sample_application/0.0.1/
```

--------------------------------

### Install PyMongo with OCSP support

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/tls

Required installation command to enable OCSP functionality.

```sh
python -m pip install pymongo[ocsp]
```

--------------------------------

### start_transaction()

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/transactions

Starts a new transaction on the session with optional configuration.

```APIDOC
## start_transaction()

### Description
Starts a new transaction, configured with the given options, on this session. Returns an error if there is already a transaction in progress for the session.

### Parameters
- **read_concern** (optional) - Read concern for the transaction.
- **write_concern** (optional) - Write concern for the transaction.
- **read_preference** (optional) - Read preference for the transaction.
- **max_commit_time_ms** (optional) - Maximum commit time in milliseconds.

### Return Type
- **ContextManager**
```

--------------------------------

### Aggregation Output Example

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/aggregation

Example output format for the bakery count aggregation.

```javascript
{'_id': 'Bronx', 'count': 71}
{'_id': 'Brooklyn', 'count': 173}
{'_id': 'Missing', 'count': 2}
{'_id': 'Manhattan', 'count': 221}
{'_id': 'Queens', 'count': 204}
{'_id': 'Staten Island', 'count': 20}
```

--------------------------------

### Start FastAPI Server

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/fastapi-integration

Command to launch the FastAPI application using Uvicorn.

```shell
uvicorn app:app --reload
```

--------------------------------

### Install PyMongo with AWS support

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/authentication/aws-iam

Install the necessary dependencies to enable AWS IAM authentication.

```sh
python -m pip install pymongo[aws]
```

--------------------------------

### Example Output

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/get-started

The expected output format when the query successfully retrieves a document.

```none
{
  _id: ...,
  plot: 'A young man is accidentally sent 30 years into the past...',
  genres: [ 'Adventure', 'Comedy', 'Sci-Fi' ],
  ...
  title: 'Back to the Future',
  ...
}
```

--------------------------------

### Explain Aggregation Output

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/aggregation

Example output showing the winning execution plan.

```javascript
...
'winningPlan': {'queryPlan': {'stage': 'GROUP',
                                      'planNodeId': 3,
                                      'inputStage': {'stage': 'COLLSCAN',
                                                     'planNodeId': 1,
                                                     'filter': {'cuisine': {'$eq': 'Bakery'}},
                                                     'direction': 'forward'}},
                                                    ...
```

--------------------------------

### Install PyMongo

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/get-started

Installs the PyMongo driver using pip within the active virtual environment.

```bash
python3 -m pip install pymongo
```

--------------------------------

### Install Flask-PyMongo dependencies

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/flask-migrate-to-mongo

Install the required Flask and Flask-PyMongo packages via pip.

```bash
pip install Flask-PyMongo Flask
```

--------------------------------

### Start Flask and Celery Services

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/flask-celery-integration

Commands to launch the Flask development server and the Celery background worker.

```bash
flask --app app run
```

```bash
celery -A app.celery worker --loglevel=info
```

--------------------------------

### Check OpenSSL Version

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/tls

Command to verify the installed version of OpenSSL.

```bash
openssl version
```

--------------------------------

### Dockerfile configuration

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/flask-azure

This Dockerfile defines the environment, installs dependencies, and sets the entry point for the container.

```dockerfile
FROM python:3.9-slim-buster
WORKDIR /azurecontainerappsdemo

COPY ./config/requirements.txt /azurecontainerappsdemo/
RUN pip install -r requirements.txt

COPY . /azurecontainerappsdemo/

ENV FLASK_APP=app.py
EXPOSE 5000
CMD ["flask", "run", "--host=0.0.0.0"]
```

--------------------------------

### Test API with curl

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/fastapi-integration

Example command to send a POST request to the students endpoint.

```shell
curl -X POST "http://127.0.0.1:8000/students/" \
    -H "Content-Type: application/json" \
    -d '{"name": "Jane Doe", "email": "jdoe@example.com", "course": "Physics", "gpa": 3.8}'
```

--------------------------------

### Install and Configure Docker Buildx for M1 Mac

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/flask-azure

Commands to set up and use Docker Buildx for cross-platform image building on M1 Mac architectures.

```bash
docker buildx install
```

```bash
docker buildx create --use
```

--------------------------------

### Example Log Output

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/monitoring-and-logging/logging

Displays the format of a DEBUG level log message generated by the driver.

```none
DEBUG:pymongo.command:{"clientId": {"$oid": "..."}, "message": "Command started", "command": "{\"insert\": \"test\", \"ordered\": true, \"lsid\": {\"id\": {\"$binary\": {\"base64\": \"...\", \"subType\": \"04\"}}}, \"$db\": \"db\", \"documents\": [{\"x\": 1, \"_id\": {\"$oid\": \"...\"}}]}", "commandName": "insert", "databaseName": "db", "requestId": ..., "operationId": ..., "driverConnectionId": 1, "serverConnectionId": 3554, "serverHost": "localhost", "serverPort": 27017}
```

--------------------------------

### with_transaction()

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/transactions

Starts a transaction and executes a callback function.

```APIDOC
## with_transaction()

### Description
Starts a transaction on this session and runs `callback` once, then commits the transaction. In the event of an exception, this method may retry the commit or the entire transaction.

### Parameters
- **callback** (function) - The function to execute within the transaction.
- **read_concern** (optional) - Read concern for the transaction.
- **write_concern** (optional) - Write concern for the transaction.
- **read_preference** (optional) - Read preference for the transaction.
- **max_commit_time_ms** (optional) - Maximum commit time in milliseconds.

### Return Value
- The result of the `callback` function.
```

--------------------------------

### Connect to MongoDB and Query Data

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/get-started

Use these examples to establish a connection to your MongoDB deployment and retrieve a document. Choose between synchronous and asynchronous implementations based on your application requirements.

```python
from pymongo import MongoClient
import json

uri = "<connection string URI>"
client = MongoClient(uri)

try:
    database = client.get_database("sample_mflix")
    movies = database.get_collection("movies")

    # Queries for a movie that has the title 'Back to the Future'
    query = { "title": "Back to the Future" }
    movie = movies.find_one(query)

    print(json.dumps(movie, indent=4, default=str))

    client.close()

except Exception as e:
    raise Exception("Unable to find the document due to the following error: ", e)
```

```python
import asyncio
from pymongo import AsyncMongoClient

async def main():
    uri = "<connection string URI>"
    client = AsyncMongoClient(uri)

    try:
        database = client.get_database("sample_mflix")
        movies = database.get_collection("movies")

        # Query for a movie that has the title 'Back to the Future'
        query = { "title": "Back to the Future" }
        movie = await movies.find_one(query)

        print(movie)

        await client.close()

    except Exception as e:
        raise Exception("Unable to find the document due to the following error: ", e)

# Run the async function
asyncio.run(main())
```

--------------------------------

### Start RabbitMQ Service

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/flask-celery-integration

Commands to initiate the RabbitMQ message broker based on the host operating system.

```bash
brew services start rabbitmq
```

```bash
rabbitmq-service start
```

```bash
sudo systemctl start rabbitmq-server
```

--------------------------------

### Example Change Stream Output

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/monitoring-and-logging/change-streams

The structure of a change event document returned by the change stream.

```sh
{'_id': {'_data': '...'}, 'operationType': 'update', 'clusterTime': Timestamp(...), 'wallTime': datetime.datetime(...),
'ns': {'db': 'sample_restaurants', 'coll': 'restaurants'}, 'documentKey': {'_id': ObjectId('...')},
'updateDescription': {'updatedFields': {'cuisine': 'Irish'}, 'removedFields': [], 'truncatedArrays': []}}
```

--------------------------------

### Check OpenSSL Version

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/tls

Command to verify the installed OpenSSL version on Unix-like systems.

```bash
$ openssl version
```

--------------------------------

### Configure Root Certificates for Portable PyPy

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/tls

Commands to install the certifi module and export the SSL_CERT_FILE environment variable.

```bash
$ pypy -m pip install certifi
$ export SSL_CERT_FILE=$(pypy -c "import certifi; print(certifi.where())")
```

--------------------------------

### Define a pytest fixture

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/test-package-library

A basic fixture example using a yield statement to manage setup and teardown logic.

```python
def sample_fixture():
    # Code before the test runs
    yield "Hello, World"
    # Code after the test runs
```

--------------------------------

### Create Application File

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/get-started

Creates the quickstart.py file in the project directory.

```bash
cd pymongo-quickstart
touch quickstart.py
```

```bash
cd pymongo-quickstart
type nul > quickstart.py
```

--------------------------------

### Run the Application

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/get-started

Execute the application from the command line.

```sh
python3 quickstart.py
```

--------------------------------

### Tail the Oplog with Tailable Cursors

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/query/cursors

Use CursorType.TAILABLE_AWAIT to keep a cursor open for new documents. The synchronous and asynchronous examples demonstrate tailing the oplog of a replica set.

```python
oplog = client.local.oplog.rs
first = oplog.find().sort('$natural', pymongo.ASCENDING).limit(-1).next()
print(first)
ts = first['ts']

while True:
    cursor = oplog.find({'ts': {'$gt': ts}},
                        cursor_type=pymongo.CursorType.TAILABLE_AWAIT)
    while cursor.alive:
        for doc in cursor:
            ts = doc['ts']
            print(doc)

        # You end up here if the find() method returns no documents, or if
        # no new documents are added to the collection for more than 1 second.
        time.sleep(1)
```

```python
oplog = client.local.oplog.rs
first = await oplog.find().sort('$natural', pymongo.ASCENDING).limit(-1).next()
print(first)
ts = first['ts']

while True:
    cursor = oplog.find({'ts': {'$gt': ts}},
                        cursor_type=pymongo.CursorType.TAILABLE_AWAIT)
    while cursor.alive:
        async for doc in cursor:
            ts = doc['ts']
            print(doc)

        # You end up here if the find() method returns no documents, or if
        # no new documents are added to the collection for more than 1 second.
        await asyncio.sleep(1)
```

--------------------------------

### Client Bulk Write Synchronous Example

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/bulk-write

Performs multiple write operations across different namespaces using a MongoClient instance.

```python
operations = [
    InsertOne(
        namespace="sample_mflix.movies",
        document={
            "title": "Minari",
            "runtime": 217,
            "genres": ["Drama", "Comedy"]
        }
    ),
    UpdateOne(
        namespace="sample_mflix.movies",
        filter={ "title": "Minari" },
        update={ "$set": { "runtime": 117 }}
    ),
    DeleteMany(
        namespace="sample_restaurants.restaurants",
        filter={ "cuisine": "French" }
    )
]

results = client.bulk_write(operations)

print(results)
```

--------------------------------

### Create project directory

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/test-package-library

Initialize the project structure via terminal commands.

```shell
mkdir sample_application
cd sample_application
```

--------------------------------

### Initialize Flask, MongoDB, and Celery

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/flask-celery-integration

Initialize core application components and connect to services in app.py.

```python
from flask import Flask
from flask_mail import Mail
from flask_pymongo import PyMongo
from celery import Celery

# Create a Flask application
app = Flask(__name__)
app.config.from_object('config.Config')

# Create a Flask-Mail instance
mail = Mail(app)

# Connect to MongoDB
client = PyMongo(app).cx
db = client[app.config['DATABASE_NAME']]

# Create a Celery instance
celery = Celery(app.name, broker=app.config['CELERY_BROKER_URL'])
celery.conf.update(app.config)

from routes import *
from tasks import *

if __name__ == '__main__':
   app.run(debug=True)
```

--------------------------------

### Insert Sample Data into MongoDB

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/query/specify-query

Initializes a database and collection, then populates it with sample fruit documents using either synchronous or asynchronous PyMongo clients.

```python
from pymongo import MongoClient

uri = "<connection string URI>"
client = MongoClient(uri)

try:
    database = client["sample_fruit"]
    collection = database["fruits"]

    collection.insert_many([
        { "_id": 1, "name": "apples", "qty": 5, "rating": 3, "color": "red", "type": ["fuji", "honeycrisp"] },
        { "_id": 2, "name": "bananas", "qty": 7, "rating": 4, "color": "yellow", "type": ["cavendish"] },
        { "_id": 3, "name": "oranges", "qty": 6, "rating": 2, "type": ["naval", "mandarin"] },
        { "_id": 4, "name": "pineapple", "qty": 3, "rating": 5, "color": "yellow" },
    ])

    client.close()

except Exception as e:
    raise Exception("Error inserting documents: ", e)
```

```python
from pymongo import AsyncMongoClient

uri = "<connection string URI>"
client = AsyncMongoClient(uri)

try:
    database = client["sample_fruit"]
    collection = database["fruits"]

    await collection.insert_many([
        { "_id": 1, "name": "apples", "qty": 5, "rating": 3, "color": "red", "type": ["fuji", "honeycrisp"] },
        { "_id": 2, "name": "bananas", "qty": 7, "rating": 4, "color": "yellow", "type": ["cavendish"] },
        { "_id": 3, "name": "oranges", "qty": 6, "rating": 2, "type": ["naval", "mandarin"] },
        { "_id": 4, "name": "pineapple", "qty": 3, "rating": 5, "color": "yellow" },
    ])

    await client.close()

except Exception as e:
    raise Exception("Error inserting documents: ", e)
```

--------------------------------

### Server Selection Timeout Error

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/connection-targets

Stack trace example occurring when attempting to connect to a replica set over an SSH tunnel without direct connection enabled.

```python
File "/Library/Python/2.7/site-packages/pymongo/collection.py", line 1560, in count
  return self._count(cmd, collation, session)
  File "/Library/Python/2.7/site-packages/pymongo/collection.py", line 1504, in _count
  with self._socket_for_reads() as (connection, slave_ok):
  File "/System/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/contextlib.py", line 17, in __enter__
  return self.gen.next()
  File "/Library/Python/2.7/site-packages/pymongo/mongo_client.py", line 982, in _socket_for_reads
  server = topology.select_server(read_preference)
  File "/Library/Python/2.7/site-packages/pymongo/topology.py", line 224, in select_server
  address))
  File "/Library/Python/2.7/site-packages/pymongo/topology.py", line 183, in select_servers
  selector, server_timeout, address)
  File "/Library/Python/2.7/site-packages/pymongo/topology.py", line 199, in _select_servers_loop
  self._error_message(selector))
pymongo.errors.ServerSelectionTimeoutError: localhost:27017: timed out
```

--------------------------------

### Install macOS Root Certificates

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/tls

Command to install root certificates for Python 3.7+ on macOS.

```bash
open "/Applications/Python <YOUR PYTHON VERSION>/Install Certificates.command"
```

--------------------------------

### Create Project Directory

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/get-started

Initializes a new directory for the PyMongo project.

```bash
mkdir pymongo-quickstart
```

--------------------------------

### Specify $or Logical Operator in PyMongo

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/query/specify-query

Use the $or operator to match documents that satisfy at least one of the provided conditions. The synchronous example uses a standard for loop, while the asynchronous example uses an async for loop.

```python
results = collection.find({ 
    "$or": [
        { "qty": { "$gt": 5 }},
        { "color": "yellow" }
    ]
})

for f in results:
    print(f)
```

```python
results = collection.find({ 
    "$or": [
        { "qty": { "$gt": 5 }},
        { "color": "yellow" }
    ]
})

async for f in results:
    print(f)
```

--------------------------------

### Initialize MongoDB client and collections

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/fastapi-integration

Establish an asynchronous connection to the database and define pointers for the database and collection.

```python
client = AsyncMongoClient(os.environ["MONGODB_URL"],server_api=pymongo.server_api.ServerApi(version="1", strict=True,deprecation_errors=True))
db = client.get_database("college")
student_collection = db.get_collection("students")
```

--------------------------------

### Clone the Flask application repository

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/flask-azure

Use this command to download the starter Flask application from GitHub.

```bash
git clone https://github.com/mongodb-developer/atlas-flask-azure-demo
```

--------------------------------

### Configure document_class with OrderedDict

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/mongoclient

Example of specifying an OrderedDict as the document_class for the MongoClient.

```python
client = MongoClient(document_class=OrderedDict[str, int])
```

--------------------------------

### Configure database settings with get_database

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/configure

Use get_database to retrieve a database instance with specific read and write settings applied.

```python
client.get_database("test-database",
                    read_preference=ReadPreference.SECONDARY,
                    read_concern="local",
                    write_concern="majority")
```

--------------------------------

### Example URL with ObjectId

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/query/specify-query

A representation of a URL containing an encoded ObjectId string.

```python
"/posts/50b3bda58a02fb9a84d8991e"
```

--------------------------------

### Configure Virtual Environment

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/get-started

Sets up and activates a Python virtual environment for dependency management.

```bash
python3 -m venv venv
source venv/bin/activate
```

```bash
python3 -m venv venv
. venv\Scripts\activate
```

--------------------------------

### Create a GridFS Bucket

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/gridfs

Initialize a GridFS bucket using a database instance. Use the appropriate constructor for synchronous or asynchronous applications.

```python
client = MongoClient("<connection string>")
db = client["db"]
bucket = gridfs.GridFSBucket(db)
```

```python
client = AsyncMongoClient("<connection string>")
db = client["db"]
bucket = gridfs.AsyncGridFSBucket(db)
```

--------------------------------

### Explain Aggregation via Database Command

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/aggregation

Use the database.command method to run an aggregation with the explain flag enabled.

```python
# Define an aggregation pipeline with a match stage and a group stage
pipeline = [
   { $match: { cuisine: "Bakery" } },
   { $group: { _id: "$borough", count: { $sum: 1 } } }
]

# Execute the operation and print the explanation
result = database.command("aggregate", "collection", pipeline=pipeline, explain=True)
print(result)
```

--------------------------------

### Pytest output example

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/test-package-library

Expected console output upon successful test execution.

```shell
============================= test session starts ==============================
collected 1 item

test_mongodb_fixture.py .                                              [100%]

============================== 1 passed in 0.XXs ===============================
```

```shell
============================= test session starts ==============================
collected 1 item

test_update_mongodb.py .                                              [100%]

============================== 1 passed in 0.XXs ===============================
```

--------------------------------

### Run the Flask application

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/flask-migrate-to-mongo

Execute the Flask application entry point script.

```bash
python run.py
```

--------------------------------

### Proximity Query Output

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/geo

The expected JSON output format for the proximity query examples.

```json
{ "_id" : ObjectId("59a47287cfa9a3a73e51e8e2"), "theaterId" : 1908 }
{ "_id" : ObjectId("59a47286cfa9a3a73e51e838"), "theaterId" : 1448 }
```

--------------------------------

### Build and Push Docker Images for Windows

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/flask-azure

Standard Docker build and push commands for Windows environments.

```bash
docker build --t <azure registry url>/<image name>:<image tag> .
```

```bash
docker push <image name>:<image tag>
```

--------------------------------

### Sample GeoJSON Document

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/indexes

Example of a document containing a GeoJSON Point object for geospatial indexing.

```javascript
{
   "_id" : ObjectId("59a47286cfa9a3a73e51e75c"),
   "theaterId" : 104,
   "location" : {
      "address" : {
         "street1" : "5000 W 147th St",
         "city" : "Hawthorne",
         "state" : "CA",
         "zipcode" : "90250"
      },
      "geo" : {
         "type" : "Point",
         "coordinates" : [
            -118.36559,
            33.897167
         ]
      }
   }
}
```

--------------------------------

### Configure collection settings with with_options

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/configure

Use with_options to return a new collection instance with updated read and write settings.

```python
collection.with_options(read_preference=ReadPreference.SECONDARY,
                        read_concern="local",
                        write_concern="majority")
```

--------------------------------

### Configure Server Selection

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect

Specifies a custom server selection function during client initialization.

```python
client = pymongo.MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
   server_selector=<selector function>)
```

```python
client = pymongo.AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
   server_selector=<selector function>)
```

--------------------------------

### Initialize a replica set with directConnection

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/connection-targets

Connects directly to a single member of a replica set by setting directConnection to True.

```python
from pymongo import MongoClient

client = MongoClient("mongodb://<hostname>:<port>",
                     directConnection=True)
```

```python
from pymongo import MongoClient

uri = ("mongodb://<hostname>:<port>/?"
       "directConnection=true")
client = MongoClient(uri)
```

```python
from pymongo import AsyncMongoClient

client = AsyncMongoClient("mongodb://<hostname>:<port>",
                           directConnection=True)
```

```python
from pymongo import AsyncMongoClient

uri = ("mongodb://<hostname>:<port>/?"
       "directConnection=true")
client = AsyncMongoClient(uri)
```

--------------------------------

### BulkWriteError Example

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/connection-options/csot

Indicates that a bulk operation failed due to write concern timeout constraints.

```text
pymongo.errors.BulkWriteError: batch op errors occurred, full error: {'writeErrors': [], 'writeConcernErrors': [{'code': 50, 'codeName': 'MaxTimeMSExpired', 'errmsg': 'operation exceeded time limit', 'errInfo': {'writeConcern': {'w': 1, 'wtimeout': 0}}}], 'nInserted': 2, 'nUpserted': 0, 'nMatched': 0, 'nModified': 0, 'nRemoved': 0, 'upserted': []}
```

--------------------------------

### Identify SSL Handshake Failure

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/tls

Example of client-side error messages related to SSL handshake failures.

```python
SSL handshake failed: localhost:27017: [SSL: SSLV3_ALERT_HANDSHAKE_FAILURE] sslv3 alert handshake failure (_ssl.c:997)
SSL handshake failed: localhost:27017: EOF occurred in violation of protocol (_ssl.c:997)
```

--------------------------------

### MongoClient(host=None, port=None, document_class=dict, tz_aware=False, connect=True, type_registry=None, **kwargs)

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/mongoclient

Initializes a new MongoClient instance to connect to a MongoDB deployment.

```APIDOC
## MongoClient

### Description
Creates a connection to a MongoDB instance. Use `MongoClient` for synchronous applications or `AsyncMongoClient` for asynchronous applications.

### Parameters
- **host** (Union[str, Sequence[str]]) - Optional - The hostname, IP address, or Unix domain socket path. Default: "localhost".
- **port** (int) - Optional - The port number. Default: 27017.
- **document_class** (Type[_DocumentType]) - Optional - The default class used to decode BSON documents. Default: dict.
- **tz_aware** (bool) - Optional - If True, treats datetime values as aware; otherwise, naive.
- **connect** (bool) - Optional - If True, connects in the background immediately. If False, connects on the first operation. Default: True (False in FaaS environments).
- **type_registry** (TypeRegistry) - Optional - Instance to enable encoding/decoding of custom types.
```

--------------------------------

### Configure Connection Options via URI

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/connection-options

Pass connection options as key-value pairs within the connection URI string.

```python
uri = "mongodb://<hostname>:<port>/?connectTimeoutMS=60000&tls=true"
client = pymongo.MongoClient(uri)
```

```python
uri = "mongodb://<hostname>:<port>/?connectTimeoutMS=60000&tls=true"
client = pymongo.AsyncMongoClient(uri)
```

--------------------------------

### Collection Bulk Write Asynchronous Example

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/bulk-write

Performs multiple write operations on a single collection asynchronously.

```python
operations = [
    InsertOne(
        document={
            "name": "Mongo's Deli",
            "cuisine": "Sandwiches",
            "borough": "Manhattan",
            "restaurant_id": "1234"
        }
    ),
    InsertOne(
        document={
            "name": "Mongo's Deli",
            "cuisine": "Sandwiches",
            "borough": "Brooklyn",
            "restaurant_id": "5678"
        }
    ),
    UpdateMany(
        filter={ "name": "Mongo's Deli" },
        update={ "$set": { "cuisine": "Sandwiches and Salads" }}
    ),
    DeleteOne(
        filter={ "restaurant_id": "1234" }
    )
]

results = await restaurants.bulk_write(operations)

print(results)
```

--------------------------------

### Build and run the Docker container

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/flask-azure

Commands to build the local image and run it with the MongoDB connection string.

```bash
docker build --tag azurecontainerappsdemo .
```

```bash
docker run -d -p 5000:5000 -e "CONNECTION_STRING=<MONGODB_ATLAS_URI_STRING_HERE>" azurecontainerappsdemo
```

--------------------------------

### Collection Bulk Write Synchronous Example

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/bulk-write

Performs multiple write operations on a single collection synchronously.

```python
operations = [
    InsertOne(
        document={
            "name": "Mongo's Deli",
            "cuisine": "Sandwiches",
            "borough": "Manhattan",
            "restaurant_id": "1234"
        }
    ),
    InsertOne(
        document={
            "name": "Mongo's Deli",
            "cuisine": "Sandwiches",
            "borough": "Brooklyn",
            "restaurant_id": "5678"
        }
    ),
    UpdateMany(
        filter={ "name": "Mongo's Deli" },
        update={ "$set": { "cuisine": "Sandwiches and Salads" }}
    ),
    DeleteOne(
        filter={ "restaurant_id": "1234" }
    )
]

results = restaurants.bulk_write(operations)

print(results)
```

--------------------------------

### Incompatible type hint error

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/mongoclient

Example of a type checker error when document data types are missing.

```python
error: Dict entry 0 has incompatible type "str": "int";
expected "Mapping[str, Any]": "int"
```

--------------------------------

### Connect with OIDC Callback

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/authentication/oidc

Initialize the client using the OIDC authentication mechanism and properties.

```python
client = MongoClient(
   "mongodb[+srv]://<hostname>:<port>",
   authMechanism="MONGODB-OIDC",
   authMechanismProperties=properties
)
```

```python
client = AsyncMongoClient(
   "mongodb[+srv]://<hostname>:<port>",
   authMechanism="MONGODB-OIDC",
   authMechanismProperties=properties
)
```

--------------------------------

### Configure document_class with TypedDict

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/mongoclient

Example of using a TypedDict subclass for the document_class parameter with appropriate type hinting.

```python
client: MongoClient[MyTypedDict] = MongoClient()
```

--------------------------------

### WTimeoutError Example

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/connection-options/csot

Indicates a write operation failed to complete within the specified write concern timeout.

```text
pymongo.errors.WTimeoutError: operation exceeded time limit, full error: {'code': 50, 'codeName': 'MaxTimeMSExpired', 'errmsg': 'operation exceeded time limit', 'errInfo': {'writeConcern': {'w': 1, 'wtimeout': 0}}}
```

--------------------------------

### Enable Compression via Async Connection String

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/connection-options/network-compression

Include the 'compressors' parameter in the connection URI for asynchronous clients.

```python
uri = ("mongodb://<db_username>:<db_password>@<hostname>:<port>/?"
       "compressors=snappy,zstd,zlib")
client = pymongo.AsyncMongoClient(uri)
```

--------------------------------

### NetworkTimeout Example

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/connection-options/csot

Indicates a failure to establish a connection or a lack of server response within the timeout limit.

```text
pymongo.errors.NetworkTimeout: localhost:27017: timed out
```

--------------------------------

### ServerSelectionTimeoutError Example

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/connection-options/csot

Indicates the client failed to locate an available server within the configured timeout period.

```text
pymongo.errors.ServerSelectionTimeoutError: No servers found yet, Timeout: -0.00202266700216569s, Topology Description: <TopologyDescription id: 63698e87cebfd22ab1bd2ae0, topology_type: Unknown, servers: [<ServerDescription ('localhost', 27017) server_type: Unknown, rtt: None>]>
```

--------------------------------

### PyMongo Sample Application Templates

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/query

Boilerplate code for setting up synchronous and asynchronous MongoDB connections.

```python
import pymongo
from pymongo import MongoClient

try:
    uri = "<connection string URI>"
    client = MongoClient(uri)

    database = client["<database name>"]
    collection = database["<collection name>"]

    # start example code here

    # end example code here

    client.close()

except Exception as e:
    raise Exception(
        "The following error occurred: ", e)
```

```python
import asyncio
import pymongo
from pymongo import AsyncMongoClient

async def main():
    try:
        uri = "<connection string URI>"
        client = AsyncMongoClient(uri)

        database = client["<database name>"]
        collection = database["<collection name>"]

        # start example code here

        # end example code here

        await client.close()

    except Exception as e:
        raise Exception(
            "The following error occurred: ", e)

asyncio.run(main())
```

--------------------------------

### Configure OpenSSL for Legacy Renegotiation

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/tls

Configuration file content to enable the UnsafeLegacyServerConnect option.

```shell
openssl_conf = openssl_init

[openssl_init]
ssl_conf = ssl_sect

[ssl_sect]
system_default = system_default_sect

[system_default_sect]
Options = UnsafeLegacyServerConnect
```

--------------------------------

### Define rollback session fixture

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/test-package-library

Implement a function-scoped fixture that starts a transaction and aborts it after the test completes.

```python
@pytest.fixture
def rollback_session(mongodb):
    session = mongodb.start_session()
    session.start_transaction()
    try:
        yield session
    finally:
        session.abort_transaction()
```

--------------------------------

### Get a Collection Reference with CodecOptions

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/custom-types/type-codecs

Pass the TypeRegistry to a CodecOptions instance and use it when retrieving a collection reference.

```python
from bson.codec_options import CodecOptions

codec_options = CodecOptions(type_registry=type_registry)
collection = database.get_collection("test", codec_options=codec_options)
```

--------------------------------

### Identify OpenSSL Error Message

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/tls

Example of the error message triggered by legacy renegotiation restrictions in OpenSSL v3+.

```python
[SSL: UNSAFE_LEGACY_RENEGOTIATION_DISABLED] unsafe legacy renegotiation disabled
```

--------------------------------

### Define Project Structure

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/flask-celery-integration

The recommended file and directory layout for a modular Flask application.

```none
newsletter/
├── app.py
├── config.py
├── routes.py
├── tasks.py
├── templates/
│   ├── admin.html
│   └── subscribe.html
└── static/
    └── styles.css
```

--------------------------------

### Identify Server-Side Handshake Error

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/tls

Example of the error message found in MongoDB server logs during a handshake failure.

```python
2021-06-30T21:22:44.917+0100 E NETWORK  [conn16] SSL: error:1408A0C1:SSL routines:ssl3_get_client_hello:no shared cipher
```

--------------------------------

### Identify Invalid Status Response Error

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/tls

Example of the error message indicating a failure in certificate revocation checking.

```python
[('SSL routines', 'tls_process_initial_server_flight', 'invalid status response')]
```

--------------------------------

### Identify TLS Protocol Version Alert

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/tls

Example of the error message indicating an unsupported TLS protocol version.

```python
[SSL: TLSV1_ALERT_PROTOCOL_VERSION] tlsv1 alert protocol version
```

--------------------------------

### Pretty Print Explanation Results

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/aggregation

Use the pprint module to format complex explanation output for better readability.

```python
import pprint
...
pprint.pp(result)
```

--------------------------------

### Identify Certificate Verification Failure

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/security/tls

Example of the error message returned when OpenSSL fails to verify a server certificate.

```python
[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed
```

--------------------------------

### Connect to MongoDB with MongoClient

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/mongoclient

Use the MongoClient constructor with a connection URI string to establish a synchronous connection to a MongoDB instance.

```python
from pymongo import MongoClient

uri = "mongodb://localhost:27017/"
client = MongoClient(uri)
```

--------------------------------

### Change Event Output Example

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/monitoring-and-logging/change-streams

Represents the structure of a change event containing a fullDocument field after an update operation.

```sh
{'_id': {'_data': '...'}, 'operationType': 'update', 'clusterTime': Timestamp(...), 'wallTime': datetime.datetime(...),
 'fullDocument': {'_id': ObjectId('...'), 'address': {...}, 'borough': 'Queens',
 'cuisine': 'Irish', 'grades': [...], 'name': 'Blarney Castle', 'restaurant_id': '40366356'},
 'ns': {'db': 'sample_restaurants', 'coll': 'restaurants'}, 'documentKey': {'_id': ObjectId('...')},
 'updateDescription': {'updatedFields': {'cuisine': 'Irish'}, 'removedFields': [], 'truncatedArrays': []}}
```

--------------------------------

### Build the package distribution

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/test-package-library

Execute this command in the project root to generate wheel and tarball distribution files.

```python
python3 -m build
```

--------------------------------

### MongoClient type annotation error

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect/mongoclient

Example of a type checker error when a MongoClient object lacks a type annotation.

```python
from pymongo import MongoClient
client = MongoClient()  # error: Need type annotation for "client"
```

--------------------------------

### Celery Worker Log Output

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/integrations/flask-celery-integration

Example log output showing successful task execution and email dispatch status.

```bash
[2025-05-27 09:54:43,873: INFO/ForkPoolWorker-7] Task tasks.send_emails[7d7f9616-7b9b-4508-a889-95c35f54fe43] succeeded in 3.93334774998948s: {'result': 'All emails sent'}
[2025-05-27 10:04:52,043: INFO/MainProcess] Task tasks.send_emails[ac2ec70f-2d3e-444a-95bb-185ac659f460] received
[2025-05-27 10:04:52,046: WARNING/ForkPoolWorker-7] Sending email to <subscriber_email>
[2025-05-27 10:04:53,474: WARNING/ForkPoolWorker-7] Email sent
```

--------------------------------

### Sample BSON document structure

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/bson

A sample document structure containing nested objects and arrays.

```none
{
    "address" : {
        "street" : "Pizza St",
        "zipcode" : "10003"
    },
    "coord" : [-73.982419, 41.579505]
    "cuisine" : "Pizza",
    "name" : "Mongo's Pizza"
}
```

--------------------------------

### Troubleshoot UuidRepresentation.UNSPECIFIED error

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/data-formats/uuid

This example demonstrates the ValueError triggered when attempting to insert a native UUID without a specified representation.

```python
unspecified_collection.insert_one({'_id': 'bar', 'uuid': uuid4()})
Traceback (most recent call last):
...
ValueError: cannot encode native uuid.UUID with UuidRepresentation.UNSPECIFIED.
UUIDs can be manually converted to bson.Binary instances using bson.Binary.from_uuid()
or a different UuidRepresentation can be configured. See the documentation for
UuidRepresentation for more information.
```

--------------------------------

### Specify Network Compression Algorithms

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/connect

Configure multiple compression algorithms using the compressors parameter in the client constructor or connection string.

```python
client = pymongo.MongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
                             compressors = "snappy,zstd,zlib")
```

```python
uri = ("mongodb://<db_username>:<db_password>@<hostname>:<port>/?"
       "compressors=snappy,zstd,zlib")
client = pymongo.MongoClient(uri)
```

```python
client = pymongo.AsyncMongoClient("mongodb://<db_username>:<db_password>@<hostname>:<port>",
                                  compressors = "snappy,zstd,zlib")
```

```python
uri = ("mongodb://<db_username>:<db_password>@<hostname>:<port>/?"
       "compressors=snappy,zstd,zlib")
client = pymongo.AsyncMongoClient(uri)
```

--------------------------------

### Handle Deprecated Count Method Error

Source: https://www.mongodb.com/docs/languages/python/pymongo-driver/current/crud/query/count

Example of the error raised when attempting to use the deprecated count method on a cursor.

```text
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'Cursor' object has no attribute 'count'
```
Tokens:
Raw