tortoise / tortoise/tortoise-orm
Tortoise ORM tutorial missing context?
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 5.6k
- Forks
- 516
- Avg merge
- 2d 21h
- Merged PRs (30d)
- 9
Description
Describe the bug
I'm going through the tortoise-orm tutorial and I'm getting bugs at every step, and some parts are confusing.
In this part, I didn't understand where run_async was coming from or where I was supposed to be putting it, so I just put it at the bottom of this script once I finally found out
from tortoise import Tortoise, run_async
async def init():
# Here we create a SQLite DB using file "db.sqlite3"
# also specify the app name of "models"
# which contain models from "app.models"
await Tortoise.init(
db_url='sqlite://db.sqlite3',
modules={'models': ['app.models']}
)
# Generate the schema
await Tortoise.generate_schemas()
run_async(init())
Then it said that after you run this you should be able to run the following, so I added it below that part:
# Create instance by save
tournament = Tournament(name='New Tournament')
await tournament.save()
# Or by .create()
await Event.create(name='Without participants', tournament=tournament)
event = await Event.create(name='Test', tournament=tournament)
participants = []
for i in range(2):
team = await Team.create(name='Team {}'.format(i + 1))
participants.append(team)
# M2M Relationship management is quite straightforward
# (look for methods .remove(...) and .clear())
await event.participants.add(*participants)
# You can query related entity just with async for
async for team in event.participants:
pass
# After making related query you can iterate with regular for,
# which can be extremely convenient for using with other packages,
# for example some kind of serializers with nested support
for team in event.participants:
pass
# Or you can make preemptive call to fetch related objects,
# so you can work with related objects immediately
selected_events = await Event.filter(
participants=participants[0].id
).prefetch_related('participants', 'tournament')
for event in selected_events:
print(event.tournament.name)
print([t.name for t in event.participants])
# Tortoise ORM supports variable depth of prefetching related entities
# This will fetch all events for team and in those team tournament will be prefetched
await Team.all().prefetch_related('events__tournament')
# You can filter and order by related models too
await Tournament.filter(
events__name__in=['Test', 'Prod']
).order_by('-events__participants__name').distinct()
First thing it says is that "await can't be used outside of a function".
What are the docs missing for me to be able to use this properly?
To Reproduce
Steps to reproduce the behavior, preferably a small code snippet.
Follow the getting tutorial from scratch as a beginner who knows nothing about using async in Python and type the code in a file.
Expected behavior
A clear and concise description of what you expected to happen.
That I could use the code in the tutorial anywhere.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the tutorial's initialization and relationship-management examples, focusing on where run_async is introduced and where the await-based snippets are placed. Run the tutorial from scratch as a beginner and document the required async structure and execution order. Done means the examples are runnable together and explain why await cannot appear at top level.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, sqlite
- Domain
- database, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100