{"id":24137,"library":"odmantic","title":"ODMantic","description":"ODMantic is an async ODM (Object Document Mapper) for MongoDB, based on Pydantic and Motor. It leverages Python type hints to define models and provides a clean asynchronous API. Current version is 1.1.0, with active development and quarterly releases.","status":"active","version":"1.1.0","language":"python","source_language":"en","source_url":"https://github.com/art049/odmantic","tags":["odm","mongodb","async","pydantic","motor"],"install":[{"cmd":"pip install odmantic","lang":"bash","label":"Install ODMantic"}],"dependencies":[{"reason":"Async MongoDB driver; required at runtime","package":"motor","optional":false},{"reason":"Data validation and settings management; required at runtime","package":"pydantic","optional":false}],"imports":[{"note":"ODMantic models must inherit from odmantic.Model, not BaseModel, to enable MongoDB persistence.","wrong":"from pydantic import BaseModel","symbol":"Model","correct":"from odmantic import Model"},{"note":"Use ODMantic's Field for model fields; it wraps Pydantic's Field but adds ODM-specific features.","wrong":"from pydantic import Field","symbol":"Field","correct":"from odmantic import Field"},{"note":"ODMantic provides its own version of ObjectId that integrates with its model system.","wrong":"from bson import ObjectId","symbol":"ObjectId","correct":"from odmantic import ObjectId"}],"quickstart":{"code":"import asyncio\nfrom odmantic import AIOEngine, Model, Field\nfrom motor.motor_asyncio import AsyncIOMotorClient\n\nclass Player(Model):\n    name: str\n    level: int = Field(default=1)\n\nasync def run():\n    client = AsyncIOMotorClient(os.environ.get('MONGODB_URI', 'mongodb://localhost:27017'))\n    engine = AIOEngine(motor_client=client, database='test')\n    player = Player(name='Alice', level=5)\n    await engine.save(player)\n    print(f\"Saved player with id: {player.id}\")\n    found = await engine.find_one(Player, Player.name == 'Alice')\n    print(found)\n    client.close()\n\nasyncio.run(run())","lang":"python","description":"Creates a Player model, saves an instance to MongoDB, and retrieves it."},"warnings":[{"fix":"Upgrade models to Pydantic v2 syntax (e.g., use `Field` from odmantic, update validators).","message":"ODMantic 1.0.0 dropped support for Pydantic v1 and Python 3.7. Models defined with Pydantic v1 syntax will break.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Always import Field from odmantic: `from odmantic import Field`.","message":"Do not mix ODMantic's `Field` with Pydantic's `Field`. Using `from pydantic import Field` inside an ODMantic model can cause validation issues.","severity":"gotcha","affected_versions":"all"},{"fix":"Always use `await` with engine methods like `save`, `find`, `find_one`, `delete`, etc.","message":"ODMantic models are async-only. Calling `save()` without `await` will not persist data and may return a coroutine.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Ensure you're using the AIOEngine correctly: `await engine.save(instance)`. Verify you have installed ODMantic >=0.7.","cause":"In older versions (<0.7), 'save' was a method on the Engine instance. After refactoring, it's still a method, but the error may occur if a typo or using a wrong object.","error":"AttributeError: 'AIOEngine' object has no attribute 'save'"},{"fix":"Change the import to: `from odmantic import Field`","cause":"Using `from pydantic import Field` instead of `from odmantic import Field`.","error":"pydantic.errors.PydanticUserError: Cannot use `Field` from pydantic inside an ODMantic model"},{"fix":"Add `await` before the engine call: `player = await engine.find_one(...)`","cause":"Forgetting to await an async engine call (e.g., `engine.find_one(...)` returns a coroutine, not the result).","error":"TypeError: 'coroutine' object does not support item assignment"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}