Skip to main content

MSO (Mongo Schema Object Library)

MSO is a lightweight Object-Document Mapper (ODM) for MongoDB that allows Python developers to interact with MongoDB collections in an intuitive and Pythonic way. It offers the flexibility of a schema-less database with the convenience of strongly-typed classes, enabling seamless operations on MongoDB collections using familiar Python patterns.


🚀 Key Features:

  • Dynamic Model Generation: Automatically generates Python classes from your MongoDB collection’s $jsonSchema.
  • Pythonic API: Use common patterns like save(), find_one(), update_one(), etc.
  • REST API with Swagger: Automatically generates a REST API for your models with Swagger documentation.
  • Deeply Nested Models: Supports arbitrarily nested schemas, including arrays of objects.
  • Auto-validation: Ensures types, enums, and structure match your schema.
  • Recursive Object Serialization: Works out-of-the-box with nested documents and arrays.
  • Developer Tools: Includes tree views, schema printers, and class introspection.

📦 Requirements

  • Python 3.12+
  • MongoDB with $jsonSchema validation on your collections

🔧 Installation

pip install mso

🤖 AI Coding Assistant Support

MSO includes comprehensive documentation for AI coding assistants:

  • AI_CODING_GUIDE.md - Detailed guide for AI assistants with examples and patterns
  • .ai/quick-reference.md - Quick reference for common operations
  • .ai/examples.md - Code examples for typical use cases

When using AI assistants (like GitHub Copilot, ChatGPT, Claude), reference these files for optimal code generation.


Recommended MongoDB Validation Schema Format

{
  $jsonSchema: {
    bsonType: 'object',
    properties: {
      _id: {
        bsonType: 'objectId'
      },
      # ADD YOUR FIELDS HERE
      last_modified: {
        bsonType: [
          'date',
          'null'
        ]
      },
      created_at: {
        bsonType: [
          'date',
          'null'
        ]
      }
    },
    additionalProperties: false
  }
}

🛠️ Basic Usage

In this basic example we have already created a $jsonSchema validator for the "People" collection in MongoDB. We create a new person, update some information and save the person MongoDB.

from mso import connect_to_mongo, get_model

# Connect to MongoDB
db = connect_to_mongo("mongodb://localhost:27017", "db-name")

# Generate a model based on the "people" collection's schema
People = get_model(db, "people")

# Create a new person
person = People(name="Tony Pajama", age=34)

# Add nested data
person.health.primary_physician.name = "Dr. Strange"
person.address.add(type="home", street="123 Elm", city="NY", state="NY", zip="10001")

# Save to the database
person.save()

🧪 View Your Class Tree

People.print_nested_class_tree()

Output

Tree View:
└── people
    ├── name: str
    ├── age: int
    ├── email: str
    ├── gender: enum [Male, Female, Other]
    ├── addresses: List[addresses_item]
    │   ├── type: enum [Home, Business, Other]
    │   ├── street: str
    │   ├── city: str
    │   ├── state: str
    │   └── zip: str
    └── health: Object
        ├── medical_history: Object
        │   ├── conditions: List[conditions_item]
        │   │   ├── name: str
        │   │   ├── diagnosed: str
        │   │   └── medications: List[medications_item]
        │   │       ├── name: str
        │   │       ├── dose: str
        │   │       └── frequency: str
        │   └── allergies: List
        └── primary_physician: Object
            ├── name: str
            └── contact: Object
                ├── phone: str
                └── address: Object
                    ├── street: str
                    ├── city: str
                    ├── state: str
                    └── zip: str

🔍 Querying the Database

# Find one
person = People.find_one({"name": "Tony Pajama"})

# Find many
person_list = People.find_many(sort=[("created_at", -1)], limit=10)

Document Manipulation

# Delete
person.delete()

# Clone
new_person = person.clone()

📊 Data Summary & Analysis

MSO includes a powerful .summarize() method to help you quickly explore and understand your MongoDB collection. It performs a field-level summary with support for:

⚙️ Options

sample_size: Limit the number of documents to analyze (defaults to all)

top: Number of top strings to return (default: 5)

🔍 Example

from mso import connect_to_mongo, get_model

# Connect to MongoDB
db = connect_to_mongo("mongodb://localhost:27017", "db-name")

# Get the model for the "people" collection
People = get_model(db, "people")

print(People.summarize(top=10))

🧠 Example Output

{
  "sample_size": 1000,
  "fields": {
    "name": {
      "type": "str",
      "count": 1000,
      "missing": 0,
      "unique": 993,
      "top_5": [
        {
          "value": "Tony Pajama",
          "count": 7,
          "percent": 0.007
        },
        ...
      ]
    },
    "age": {
      "type": "int",
      "count": 978,
      "missing": 22,
      "unique": 43,
      "min": 1,
      "max": 99,
      "mean": 38.6,
      "median": 34,
      "stdev": 19.2
    },
    "health.primary_physician.name": {
      "type": "str",
      "count": 1000,
      "missing": 0,
      "unique": 12,
      "top_5": [
        {
          "value": "Dr. Strange",
          "count": 46,
          "percent": 0.046
        },
        ...
      ]
    }
  }
}

🔍 Document Comparison

MSO makes it easy to compare two MongoDB documents—either as model instances or dictionaries—using the powerful Model.diff() method. It supports:

  • Deep recursive comparison of nested objects and arrays
  • Detection of value and type changes
  • Flat or nested output formatting
  • Optional strict mode (type-sensitive)
  • Filtering for specific fields or changes

Basic Example

from mso import connect_to_mongo, get_model

db = connect_to_mongo("mongodb://localhost:27017", "db-name")
People = get_model(db, "people")

# Create a valid model instance
person1 = People(name="Alice", age=30, gender="Female")

# Use a dictionary with type mismatch (age as string)
person2 = {
    "name": "Alice",
    "age": "30",  # string instead of int
    "gender": "Female"
}

diff = People.diff(person1, person2, strict=True)

from pprint import pprint

pprint(diff)

Example Output

{
  'age': {
    'old': 30,
    'new': '30',
    'type_changed': True
  }
}

Convert to and from dictionary

person_dict = person.to_dict()

⏱ Automatic Timestamps

By default, models automatically include created_at and updated_at fields to track when a document is created or modified. These are managed internally and do not need to be defined in your schema.

🔧 How it works

created_at is set once, when the document is first saved.

updated_at is updated every time the document is modified and saved.

Both are stored as UTC datetime.datetime objects.

🚫 Disabling timestamps

Timestamps are enabled by default. To disable them, set the timestamps parameter to False when creating a model.

from mso import connect_to_mongo, get_model

# Connect to MongoDB
db = connect_to_mongo("mongodb://localhost:27017", "db-name")

# Get the model for the collection
People = get_model(db, "people")

# Disable timestamps for a specific model or instance
People.timestamps_enabled = False

🧩 Lifecycle Hooks

You can use decorators like @pre_save, @post_save, @pre_delete, and @post_delete to hook into model lifecycle events. This is useful for setting defaults, cleaning up, triggering logs, or validating conditions.

Example: Automatically output a message when a document is saved

from mso import connect_to_mongo, get_model
from mso.base_model import MongoModel, post_save

# Connect to MongoDB
db = connect_to_mongo("mongodb://localhost:27017", "db-name")

# Define the model hooks you would like to use
class People(MongoModel):
    @post_save  # This method will be called after the document is saved
    def confirm_save(self):
        print(f"[+] Document saved: {self.name}")


People = get_model(db, "people")

person = People(name="Jane Doe")
person.save()

# Output:
# [+] Document saved: Jane Doe

🧪 REST API with Swagger

MSO can automatically generate a REST API for your models, complete with Swagger documentation. This allows you to easily expose your MongoDB collections as RESTful endpoints.

from mso import connect_to_mongo
from mso.api import start_api

# Connect to MongoDB
db = connect_to_mongo("mongodb://localhost:27017", "db-name")

start_api(db)

This will start a REST API server with Swagger documentation at http://127.0.0.1:8000/docs

🔌 Custom API Endpoints

You can extend the auto-generated API with your own custom routes using the extra_routes parameter in start_api.

➕ Example

from fastapi import APIRouter
from mso import connect_to_mongo
from mso.api import start_api

# Connect to MongoDB
db = connect_to_mongo("mongodb://localhost:27017", "db-name")

# Define your custom routes
custom_router = APIRouter()

@custom_router.get("/people/stats", tags=["People"])
def get_people_stats():
    return {"message": "Custom stats for the People collection"}

# Start the API with custom routes
start_api(
    db=db,
    collections=["*"],
    extra_routes=custom_router
)

🔗 Community & Links

PyPi: https://pypi.org/project/MSO/

Reddit: https://www.reddit.com/r/MSO_Mongo_Python_ORM/

Gitlab: https://github.com/chuckbeyor101/MSO-Mongo-Schema-Object-Library.git

🛡 LICENSE & COPYWRIGHT WARNING

MSO Copyright (c) 2025 by Charles L Beyor
is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International.
To view a copy of this license, visit https://creativecommons.org/licenses/by-nc-sa/4.0/

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND
, either express or implied.

See the License for the specific language governing permissions and limitations under the License.

Metadata

Release files for MSO 1.0.86

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for MSO 1.0.86
File Size Uploaded Provenance Actions
mso-1.0.86.tar.gz 29.7 kB With provenance Details for mso-1.0.86.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for MSO 1.0.86
File Interpreter ABI Platform Actions
mso-1.0.86-py3-none-any.whl Python 3 none any Details for mso-1.0.86-py3-none-any.whl

Total release size: 64.6 kB

Release files / mso-1.0.86.tar.gz

Download URL mso-1.0.86.tar.gz
Size 29.7 kB
Tags Source
SHA-256 checksum
How to use checksums
a1931b9521e974aabfe17359ea66783995a4eb4d6be17783da1a6887a61eaafa
BLAKE2b-256 checksum
How to use checksums
89bf6998c46b8641550ad63be461d1168e700a0f893470d4adb307c2488b3e42
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Dec 7, 2025.

Transparency log

Release files / mso-1.0.86-py3-none-any.whl

Download URL mso-1.0.86-py3-none-any.whl
Size 34.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ce6a154c10e702237f2a60be580c5a94f13a9bd406a36261fe897fe0f4198d34
BLAKE2b-256 checksum
How to use checksums
b97101a2831efcb60ae4a030567e4fdc9dc8b26cd81eb3f91f9227ac36b51935
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Dec 7, 2025.

Transparency log

Security for MSO 1.0.86

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mso-1.0.86.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Dec 7, 2025.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page