tortoise-orm 0.25.1
pip install tortoise-orm
Released:
Easy async ORM for python, built with relations in mind
Navigation
Verified details
These details have beenverified by PyPIMaintainers
BondarAn
long2ice
Nickolas.GrigoriadisUnverified details
These details havenot been verified by PyPIProject links
Meta
- License: Apache Software License (Apache-2.0)
- Author:Andrey Bondar
- Tags sql, mysql, postgres, psql, sqlite, aiosqlite, asyncpg, relational, database, rdbms, orm, object mapper, async, asyncio, aio, psycopg
- Requires: Python >=3.9
- Provides-Extra:
accel,aiomysql,asyncmy,asyncodbc,asyncpg,psycopg
Classifiers
- Development Status
- Framework
- Intended Audience
- License
- Operating System
- Programming Language
- Topic
Project description
Introduction
Tortoise ORM is an easy-to-useasyncio ORM(Object Relational Mapper) inspired by Django.
You can find the docs atDocumentation
Note
Tortoise ORM is a young project and breaking changes are to be expected.We keep aChangelog and it will have possible breakage clearly documented.
Tortoise ORM supports CPython 3.9 and later for SQLite, MySQL, PostgreSQL, Microsoft SQL Server, and Oracle.
Why was Tortoise ORM built?
Tortoise ORM was built to provide a lightweight, async-native Object-Relational Mapper for Python with a familiar Django-like API.
Tortoise ORM performs well when compared to other Python ORMs. Inour benchmarks, where we measure different read and write operations (rows/sec, more is better), it’s trading places with Pony ORM:
How is an ORM useful?
An Object-Relational Mapper (ORM) abstracts database interactions, allowing developers to work with databases using high-level, object-oriented code instead of raw SQL.
Reduces boilerplate SQL, allowing faster development with cleaner, more readable code.
Helps prevent SQL injection by using parameterized queries.
Centralized schema and relationship definitions make code easier to manage and modify.
Handles schema changes through version-controlled migrations.
Getting Started
Installation
The following table shows the available installation options for different databases (note that there are multiple options of clients for some databases):
Database | Installation Command |
|---|---|
SQLite | pip installtortoise-orm |
PostgreSQL (psycopg) | pip installtortoise-orm[psycopg] |
PostgreSQL (asyncpg) | pip installtortoise-orm[asyncpg] |
MySQL (aiomysql) | pip installtortoise-orm[aiomysql] |
MySQL (asyncmy) | pip installtortoise-orm[asyncmy] |
MS SQL | pip installtortoise-orm[asyncodbc] |
Oracle | pip installtortoise-orm[asyncodbc] |
Quick Tutorial
Define the models by inheriting fromtortoise.models.Model.
fromtortoise.modelsimportModelfromtortoiseimportfieldsclassTournament(Model):id=fields.IntField(primary_key=True)name=fields.CharField(max_length=20)classEvent(Model):id=fields.BigIntField(primary_key=True)name=fields.TextField()tournament=fields.ForeignKeyField('models.Tournament',related_name='events',on_delete=fields.OnDelete.CASCADE)participants=fields.ManyToManyField('models.Team',related_name='events',through='event_team',on_delete=fields.OnDelete.SET_NULL)classTeam(Model):id=fields.UUIDField(primary_key=True)name=fields.CharField(max_length=20,unique=True)After defining the models, Tortoise ORM needs to be initialized to establish the relationships between models and connect to the database.The code below creates a connection to a SQLite DB database with theaiosqlite client.generate_schema sets up schema on an empty database.generate_schema is for development purposes only, check outaerich or other migration tools for production use.
fromtortoiseimportTortoise,run_asyncasyncdefinit():# Here we connect to a SQLite DB file.# also specify the app name of "models"# which contain models from "app.models"awaitTortoise.init(db_url='sqlite://db.sqlite3',modules={'models':['app.models']})# Generate the schemaawaitTortoise.generate_schemas()run_async(main())run_async is a helper function to run simple Tortoise scripts. Check outDocumentation for FastAPI, Sanic and other integrations.
With the Tortoise initialized, the models are available for use:
asyncdefmain():awaitTortoise.init(db_url='sqlite://db.sqlite3',modules={'models':['app.models']})awaitTortoise.generate_schemas()# Creating an instance with .save()tournament=Tournament(name='New Tournament')awaittournament.save()# Or with .create()awaitEvent.create(name='Without participants',tournament=tournament)event=awaitEvent.create(name='Test',tournament=tournament)participants=[]foriinrange(2):team=awaitTeam.create(name='Team{}'.format(i+1))participants.append(team)# Many to Many Relationship management is quite straightforward# (there are .remove(...) and .clear() too)awaitevent.participants.add(*participants)# Iterate over related entities with the async context managerasyncforteaminevent.participants:print(team.name)# The related entities are cached and can be iterated in the synchronous way afterwardsforteaminevent.participants:pass# Use prefetch_related to fetch related objectsselected_events=awaitEvent.filter(participants=participants[0].id).prefetch_related('participants','tournament')foreventinselected_events:print(event.tournament.name)print([t.namefortinevent.participants])# Prefetch multiple levels of related entitiesawaitTeam.all().prefetch_related('events__tournament')# Filter and order by related models tooawaitTournament.filter(events__name__in=['Test','Prod']).order_by('-events__participants__name').distinct()run_async(main())Learn more at thedocumentation site
Migration
Tortoise ORM usesAerich as its database migration tool, see more detail at itsdocs.
Contributing
Please have a look at theContribution Guide.
ThanksTo
Powerful Python IDEPycharmfromJetbrains.
License
This project is licensed under the Apache License - see theLICENSE.txt file for details.
Project details
Verified details
These details have beenverified by PyPIMaintainers
BondarAnlong2iceNickolas.GrigoriadisUnverified details
These details havenot been verified by PyPIProject links
Meta
- License: Apache Software License (Apache-2.0)
- Author:Andrey Bondar
- Tags sql, mysql, postgres, psql, sqlite, aiosqlite, asyncpg, relational, database, rdbms, orm, object mapper, async, asyncio, aio, psycopg
- Requires: Python >=3.9
- Provides-Extra:
accel,aiomysql,asyncmy,asyncodbc,asyncpg,psycopg
Classifiers
- Development Status
- Framework
- Intended Audience
- License
- Operating System
- Programming Language
- Topic
Release historyRelease notifications |RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more aboutinstalling packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more aboutwheel file names.
Copy a direct link to the current filters
File details
Details for the filetortoise_orm-0.25.1.tar.gz.
File metadata
- Download URL:tortoise_orm-0.25.1.tar.gz
- Upload date:
- Size: 128.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 4d5bfd13d5750935ffe636a6b25597c5c8f51c47e5b72d7509d712eda1a239fe | |
| MD5 | ef8df163a207f40230c618efa18ca32b | |
| BLAKE2b-256 | d79bde966810021fa773fead258efd8deea2bb73bb12479e27f288bd8ceb8763 |
File details
Details for the filetortoise_orm-0.25.1-py3-none-any.whl.
File metadata
- Download URL:tortoise_orm-0.25.1-py3-none-any.whl
- Upload date:
- Size: 167.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.1.0 CPython/3.12.9
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | df0ef7e06eb0650a7e5074399a51ee6e532043308c612db2cac3882486a3fd9f | |
| MD5 | 8a386089f6a0f1cdb0460a4dd15c1c34 | |
| BLAKE2b-256 | 70552bda7f4445f4c07b734385b46d1647a388d05160cf5b8714a713e8709378 |
