{"id":29542503,"url":"https://github.com/mathieurodic/ormantism","last_synced_at":"2025-10-08T14:12:37.492Z","repository":{"id":302358605,"uuid":"1012182665","full_name":"mathieurodic/ormantism","owner":"mathieurodic","description":"A lightweight ORM built on Pydantic for simple CRUD operations with minimal code","archived":false,"fork":false,"pushed_at":"2025-09-28T00:43:24.000Z","size":156,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-28T02:37:53.938Z","etag":null,"topics":["open-source","orm","pydantic","python","python3","sqlite","sqlite3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mathieurodic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-02T00:27:05.000Z","updated_at":"2025-09-28T00:43:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"621239de-03d4-4064-8caf-c8b0a790d33f","html_url":"https://github.com/mathieurodic/ormantism","commit_stats":null,"previous_names":["mathieurodic/ormantism"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/mathieurodic/ormantism","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathieurodic%2Formantism","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathieurodic%2Formantism/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathieurodic%2Formantism/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathieurodic%2Formantism/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mathieurodic","download_url":"https://codeload.github.com/mathieurodic/ormantism/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mathieurodic%2Formantism/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278956366,"owners_count":26075227,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["open-source","orm","pydantic","python","python3","sqlite","sqlite3"],"created_at":"2025-07-17T11:03:18.897Z","updated_at":"2025-10-08T14:12:37.462Z","avatar_url":"https://github.com/mathieurodic.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ormantism\n\nA tiny, simple ORM built on top of Pydantic.\n\nWhen you need to perform simple CRUD operations with minimal code.\n\nOffers support for PostgreSQL, MySQL, SQLite (database URL syntax is the same as in SQLAlchemy).\n\n## Features\n\n- **Simple Model Declaration**: Define your models using familiar Pydantic syntax\n- **Automatic Table Creation**: Tables are created automatically when first accessed\n- **Lazy Loading**: Relationships are loaded on-demand for optimal performance\n- **Transaction Support**: Built-in transaction management with automatic rollback\n- **Preloading**: Efficiently load related data with JOIN queries\n- **Optional Timestamps**: Add created_at, updated_at, deleted_at fields automatically\n\n## Installation\n\n```bash\npip install ormantism\n```\n\n## Quick Start\n\n### 1. Connect to Database\n\n```python\nimport ormantism\n\n# Connect to a file database\normantism.connect(\"sqlite:///my_app.db\")\n\n# Or use in-memory database for testing\normantism.connect(\"sqlite://:memory:\")\n\n# MySQL\normantism.connect(\"mysql://login:password@host:port/database\")\n\n# PostgresSQL\normantism.connect(\"postgresql://login:password@host:port/database\")\n```\n\n### 2. Define Models\n\n```python\nfrom ormantism import Base\nfrom typing import Optional\n\nclass User(Base):\n    name: str\n    email: str\n    age: Optional[int] = None\n\nclass Post(Base, with_timestamps=True):\n    title: str\n    content: str\n    author: User\n```\n\n### 3. Create and Save Records\n\n```python\n# Create a user\nuser = User(name=\"Alice\", email=\"alice@example.com\", age=30)\n# The record is automatically saved to the database\n\n# Create a post linked to the user\npost = Post(title=\"My First Post\", content=\"Hello World!\", author=user)\n```\n\n### 4. Query Records\n\n```python\n# Load by ID\nuser = User.load(id=1)\n\n# Load by criteria\nuser = User.load(name=\"Alice\")\nuser = User.load(email=\"alice@example.com\")\n\n# Load latest post from alice@example.com\nlatest_post = Post.load(user_id=user.id, last_created=True)\n\n# Load all records\nusers = User.load_all()\n\n# Load with criteria\nusers_named_alice = User.load_all(name=\"Alice\")\n```\n\n### 5. Update Records\n\n```python\nuser = User.load(id=1)\nuser.age = 31  # Automatically saved to database\n# or\nuser.update(age=31, email=\"alice.updated@example.com\")\n```\n\n### 6. Delete Records\n\n```python\nuser = User.load(id=1)\nuser.delete()\n```\n\n## Advanced Features\n\n### Timestamps\n\nAdd automatic timestamp tracking to your models:\n\n```python\nclass Post(Base, with_timestamps=True):\n    title: str\n    content: str\n```\n\nThis adds `created_at`, `updated_at`, and `deleted_at` fields. Soft deletes are used when timestamps are enabled.\n\n### Relationships and Lazy Loading\n\n```python\nclass Author(Base):\n    name: str\n\nclass Book(Base):\n    title: str\n    author: Author\n\n# Create records\nauthor = Author(name=\"Jane Doe\")\nbook = Book(title=\"My Book\", author=author)\n\n# Lazy loading - author is loaded from DB when accessed\nbook = Book.load(id=1)\nprint(book.author.name)  # Database query happens here\n```\n\n### Preloading (Eager Loading)\n\nAvoid N+1 queries by preloading relationships:\n\n```python\n# Load book with author in a single query\nbook = Book.load(id=1, preload=\"author\")\nprint(book.author.name)  # No additional database query\n\n# Preload nested relationships\nbook = Book.load(id=1, preload=\"author.publisher\")\n\n# Preload multiple relationships\nbook = Book.load(id=1, preload=[\"author\", \"category\"])\n```\n\n### Transactions\n\n```python\nfrom ormantism import transaction\n\ntry:\n    with transaction() as t:\n        user1 = User(name=\"Alice\", email=\"alice@example.com\")\n        user2 = User(name=\"Bob\", email=\"bob@example.com\")\n        # Both users are saved automatically\n        # Transaction commits when exiting the context\nexcept Exception:\n    # Transaction is automatically rolled back on any exception\n    pass\n```\n\n### Querying Examples\n\n```python\n# Load single record\nuser = User.load(name=\"Alice\")\nlatest_user = User.load(last_created=True)\n\n# Load multiple records\nall_users = User.load_all()\nusers_named_alice = User.load_all(name=\"Alice\")\n\n# Include soft-deleted records (when using timestamps)\nall_including_deleted = User.load_all(with_deleted=True)\n```\n\n## Model Definition\n\n### Basic Model\n\n```python\nclass User(Base):\n    name: str\n    email: str\n    age: int = 25  # Default value\n    bio: Optional[str] = None  # Nullable field\n```\n\n### With Timestamps\n\n```python\nclass Post(Base, with_timestamps=True):\n    title: str\n    content: str\n    # Automatically adds: created_at, updated_at, deleted_at\n```\n\n### Supported Field Types\n\n- `int`, `float`, `str`\n- `Optional[T]` for nullable fields\n- `list`, `dict` (stored as JSON)\n- `datetime.datetime`\n- `enum.Enum`\n- Pydantic models (stored as JSON)\n- References to other Base models\n\n### Relationships\n\n```python\nclass Category(Base):\n    name: str\n\nclass Post(Base):\n    title: str\n    category: Category  # Foreign key relationship\n    tags: Optional[Category] = None  # Nullable relationship\n```\n\n## API Reference\n\n### Base Class Methods\n\n#### Creating Records\n- `Model()` - Create and automatically save a new record\n\n#### Querying\n- `Model.load(**criteria)` - Load single record\n- `Model.load(last_created=True)` - Load most recently created record\n- `Model.load_all(**criteria)` - Load multiple records\n- `Model.load(preload=\"relationship\")` - Eager load relationships\n- `Model.load(with_deleted=True)` - Include soft-deleted records\n\n#### Updating\n- `instance.update(**kwargs)` - Update multiple fields\n- `instance.field = value` - Update single field (auto-saves)\n\n#### Deleting\n- `instance.delete()` - Delete record (soft delete if timestamps enabled)\n\n### Database Functions\n\n- `ormantism.connect(database_url)` - Connect to database\n- `ormantism.transaction()` - Get transaction context manager\n\n## Limitations\n\n- **Simple Queries**: Complex queries may require raw SQL\n- **No Migrations**: Schema changes require manual handling\n- **Basic Relationships**: Only supports simple foreign key relationships\n\n## Requirements\n\n- Python 3.12+\n- Pydantic\n\n## License\n\nMIT License\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmathieurodic%2Formantism","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmathieurodic%2Formantism","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmathieurodic%2Formantism/lists"}