or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-queries.mdbson-handling.mdbulk-transactions.mdclient-connection.mddatabase-collection.mdgridfs-storage.mdindex.mdmonitoring-events.md
tile.json

tessl/pypi-pymongo

Official Python driver for MongoDB providing comprehensive tools for database operations, BSON handling, and GridFS file storage

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/pymongo@3.13.x

To install, run

npx @tessl/cli install tessl/pypi-pymongo@3.13.0

index.mddocs/

PyMongo

The official Python driver for MongoDB, providing comprehensive tools for interacting with MongoDB databases from Python applications. PyMongo includes three main components: the bson package for BSON format handling, the pymongo package as the core driver, and the gridfs package for GridFS file storage.

Package Information

  • Package Name: pymongo
  • Language: Python
  • Installation: pip install pymongo

Core Imports

import pymongo
from pymongo import MongoClient, ASCENDING, DESCENDING

For BSON handling:

import bson
from bson import ObjectId, encode, decode, Binary, Decimal128

For GridFS file storage:

import gridfs
from gridfs import GridFS, GridFSBucket

Common bulk operations:

from pymongo.operations import InsertOne, UpdateOne, DeleteOne, ReplaceOne

Basic Usage

from pymongo import MongoClient
from bson import ObjectId

# Connect to MongoDB
client = MongoClient('mongodb://localhost:27017/')
db = client.mydatabase
collection = db.mycollection

# Insert a document
doc = {"name": "Alice", "age": 30, "city": "New York"}
result = collection.insert_one(doc)
print(f"Inserted document with id: {result.inserted_id}")

# Find documents
for doc in collection.find({"age": {"$gte": 25}}):
    print(doc)

# Update a document
collection.update_one(
    {"name": "Alice"},
    {"$set": {"age": 31}}
)

# Delete a document
collection.delete_one({"name": "Alice"})

Architecture

PyMongo follows MongoDB's hierarchical structure:

  • MongoClient: Connection management and client configuration
  • Database: Database-level operations and collection access
  • Collection: Document CRUD operations, indexing, and aggregation
  • Cursor: Result iteration with filtering and sorting capabilities

The driver provides comprehensive support for MongoDB features including transactions, change streams, aggregation pipelines, GridFS, and advanced authentication mechanisms.

Capabilities

Client Connection and Configuration

MongoDB client creation, connection management, authentication, and configuration options including connection pooling, timeouts, and replica set support.

class MongoClient:
    def __init__(self, host='localhost', port=27017, **kwargs): ...
    def get_database(self, name, **kwargs): ...
    def list_database_names(self, session=None, **kwargs): ...
    def close(self): ...

class MongoReplicaSetClient:
    """DEPRECATED - Legacy replica set client interface."""

Client and Connection Management

Database and Collection Operations

Database management, collection operations, document CRUD operations, indexing, and basic query functionality.

class Database:
    def get_collection(self, name, **kwargs): ...
    def list_collection_names(self, session=None, **kwargs): ...
    def create_collection(self, name, **kwargs): ...

class Collection:
    def insert_one(self, document, **kwargs): ...
    def find(self, filter=None, **kwargs): ...
    def update_one(self, filter, update, **kwargs): ...
    def delete_one(self, filter, **kwargs): ...

Database and Collection Operations

BSON Data Types and Encoding

BSON encoding/decoding functions and MongoDB-specific data types including ObjectId, Decimal128, Binary data, and timestamp handling.

def encode(document, **kwargs): ...
def decode(data, **kwargs): ...

class ObjectId:
    def __init__(self, oid=None): ...
    @classmethod
    def from_datetime(cls, generation_time): ...

class Decimal128:
    def __init__(self, value): ...

BSON Handling

Advanced Query Operations

Aggregation pipelines, advanced querying, sorting, pagination, and cursor operations for complex data retrieval patterns.

class Collection:
    def aggregate(self, pipeline, **kwargs): ...
    def find_one_and_update(self, filter, update, **kwargs): ...
    def create_index(self, keys, **kwargs): ...
    def distinct(self, key, filter=None, **kwargs): ...

class Cursor:
    def sort(self, key_or_list, direction=1): ...
    def limit(self, limit): ...
    def skip(self, skip): ...

Advanced Queries and Aggregation

Bulk Operations and Transactions

Bulk write operations, transaction support, and session management for high-performance and ACID-compliant operations.

class Collection:
    def bulk_write(self, requests, **kwargs): ...

class MongoClient:
    def start_session(self, **kwargs): ...

class ClientSession:
    def start_transaction(self, **kwargs): ...
    def commit_transaction(self): ...
    def abort_transaction(self): ...

# Bulk Operation Classes
class InsertOne:
    def __init__(self, document): ...

class UpdateOne:
    def __init__(self, filter, update, upsert=False): ...

class UpdateMany:
    def __init__(self, filter, update, upsert=False): ...

class ReplaceOne:
    def __init__(self, filter, replacement, upsert=False): ...

class DeleteOne:
    def __init__(self, filter): ...

class DeleteMany:
    def __init__(self, filter): ...

class IndexModel:
    def __init__(self, keys, **kwargs): ...

Bulk Operations and Transactions

GridFS File Storage

GridFS support for storing and retrieving large files, including streaming operations and metadata management.

class GridFS:
    def __init__(self, database, collection='fs', **kwargs): ...
    def put(self, data, **kwargs): ...
    def get(self, file_id, **kwargs): ...

class GridFSBucket:
    def __init__(self, db, bucket_name='fs', **kwargs): ...
    def upload_from_stream(self, filename, source, **kwargs): ...
    def download_to_stream(self, file_id, destination, **kwargs): ...

GridFS File Storage

Monitoring and Events

Change streams, monitoring capabilities, and event handling for real-time data updates and application performance monitoring.

class Collection:
    def watch(self, pipeline=None, **kwargs): ...

class ChangeStream:
    def __iter__(self): ...
    def next(self): ...
    def close(self): ...

Monitoring and Change Streams

Utility Functions

Core utility functions for version checking and C extension detection:

def get_version_string():
    """
    Get PyMongo version string.

    Returns:
    str: Version string (e.g., "3.13.0")
    """

def has_c():
    """
    Check if C extensions are available.

    Returns:
    bool: True if C extensions are loaded
    """

version: str  # Current PyMongo version
version_tuple: tuple  # Version as tuple (3, 13, 0)

Types

Core types used throughout the PyMongo API:

# Read/Write Preferences
class ReadPreference:
    PRIMARY: int
    SECONDARY: int
    PRIMARY_PREFERRED: int
    SECONDARY_PREFERRED: int

class WriteConcern:
    def __init__(self, w=None, wtimeout=None, j=None, fsync=None): ...

# Common Result Types
class InsertOneResult:
    inserted_id: ObjectId

class UpdateResult:
    matched_count: int
    modified_count: int
    upserted_id: ObjectId

class DeleteResult:
    deleted_count: int

# Sort Constants
ASCENDING: int  # 1
DESCENDING: int  # -1

# Index Types
GEO2D: str  # "2d"
GEOSPHERE: str  # "2dsphere"
GEOHAYSTACK: str  # "geoHaystack" (DEPRECATED)
HASHED: str  # "hashed"
TEXT: str  # "text"

# Database Profiling Levels (DEPRECATED)
OFF: int  # 0 (DEPRECATED)
SLOW_ONLY: int  # 1 (DEPRECATED)
ALL: int  # 2 (DEPRECATED)

# Wire Protocol Constants
MAX_SUPPORTED_WIRE_VERSION: int
MIN_SUPPORTED_WIRE_VERSION: int

# Bulk Operation Result Types
class BulkWriteResult:
    acknowledged: bool
    deleted_count: int
    inserted_count: int
    matched_count: int
    modified_count: int
    upserted_count: int
    upserted_ids: dict

class InsertManyResult:
    acknowledged: bool
    inserted_ids: list

# Exception Classes
class PyMongoError(Exception):
    """Base exception for PyMongo errors."""

class ConfigurationError(PyMongoError):
    """Configuration related errors."""

class OperationFailure(PyMongoError):
    """Database operation failures."""

class DuplicateKeyError(OperationFailure):
    """Duplicate key violations."""

class BulkWriteError(OperationFailure):
    """Bulk write operation errors."""

class NetworkTimeout(PyMongoError):
    """Network timeout errors."""

class ServerSelectionTimeoutError(PyMongoError):
    """Server selection timeout errors."""