From: Sebastián Ramírez Date: Mon, 18 May 2026 11:41:36 +0000 (+0200) Subject: 📝 Update admonitions, simplify and use defaults (#1915) X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=466b24b199a269a9f936a07d99a87a883502f74c;p=thirdparty%2Ffastapi%2Fsqlmodel.git 📝 Update admonitions, simplify and use defaults (#1915) --- diff --git a/docs/advanced/decimal.md b/docs/advanced/decimal.md index ce971b201..4439cba8b 100644 --- a/docs/advanced/decimal.md +++ b/docs/advanced/decimal.md @@ -23,7 +23,7 @@ Pydantic has special support for SQLAlchemy's `DECIMAL` type. diff --git a/docs/advanced/uuid.md b/docs/advanced/uuid.md index abfcfeda2..c18639027 100644 --- a/docs/advanced/uuid.md +++ b/docs/advanced/uuid.md @@ -12,7 +12,7 @@ You might have seen **UUIDs**, for example in URLs. They look something like thi UUIDs can be particularly useful as an alternative to auto-incrementing integers for **primary keys**. -/// info +/// note Official support for UUIDs was added in SQLModel version `0.0.20`. diff --git a/docs/databases.md b/docs/databases.md index de25ebb4c..8c29b7f96 100644 --- a/docs/databases.md +++ b/docs/databases.md @@ -1,6 +1,6 @@ # Intro to Databases -/// info +/// note Are you a seasoned developer and already know everything about databases? 🤓 @@ -317,7 +317,7 @@ Next, it receives the data and puts it in Python objects that you can continue t I'll tell you more about SQL, SQLModel, how to use them, and how they are related in the next sections. -/// info | Technical Details +/// note | Technical Details SQLModel is built on top of SQLAlchemy. It is, in fact, just SQLAlchemy and Pydantic mixed together with some sugar on top. diff --git a/docs/db-to-code.md b/docs/db-to-code.md index fbba54c16..0bcb17f29 100644 --- a/docs/db-to-code.md +++ b/docs/db-to-code.md @@ -190,7 +190,7 @@ Then your code will continue to execute and calmly tell the user that it couldn' But we never deleted the `hero` table. 🎉 -/// info +/// note Of course, there are also other ways to do SQL data sanitization without using a tool like **SQLModel**, but it's still a nice feature you get by default. @@ -296,7 +296,7 @@ There are many ORMs available apart from **SQLModel**, you can read more about s ## SQL Table Names -/// info | Technical Background +/// note | Technical Background This is a bit of boring background for SQL purists. Feel free to skip this section. 😉 diff --git a/docs/help.md b/docs/help.md index a0cfa4ea0..4065f679c 100644 --- a/docs/help.md +++ b/docs/help.md @@ -157,7 +157,7 @@ And if there's any other style or consistency need, I'll ask directly for that, * Then **comment** saying that you did that, that's how I will know you really checked it. -/// info +/// note Unfortunately, I can't simply trust PRs that just have several approvals. diff --git a/docs/tutorial/connect/create-connected-rows.md b/docs/tutorial/connect/create-connected-rows.md index 2f952bf70..230921054 100644 --- a/docs/tutorial/connect/create-connected-rows.md +++ b/docs/tutorial/connect/create-connected-rows.md @@ -37,7 +37,7 @@ Each row in the table `hero` will point to a row in the table `team`: table relationships -/// info +/// note We will later update **Spider-Boy** to add him to the **Preventers** team too, but not yet. diff --git a/docs/tutorial/connect/create-connected-tables.md b/docs/tutorial/connect/create-connected-tables.md index 2b1a4f875..14fc3c925 100644 --- a/docs/tutorial/connect/create-connected-tables.md +++ b/docs/tutorial/connect/create-connected-tables.md @@ -100,7 +100,7 @@ This is the name of the **table** in the database, so it is `"team"`, not the na If you had a custom table name, you would use that custom table name. -/// info +/// note You can learn about setting a custom table name for a model in the Advanced User Guide. diff --git a/docs/tutorial/connect/read-connected-data.md b/docs/tutorial/connect/read-connected-data.md index 2868c69dd..5fa6fbf8c 100644 --- a/docs/tutorial/connect/read-connected-data.md +++ b/docs/tutorial/connect/read-connected-data.md @@ -55,7 +55,7 @@ FROM hero, team WHERE hero.team_id = team.id ``` -/// info +/// note Because we have two columns called `name`, one for `hero` and one for `team`, we can specify them with the prefix of the table name and the dot to make it explicit what we refer to. @@ -133,7 +133,7 @@ For each iteration in the `for` loop we get a tuple with an instance of the clas And in this `for` loop we assign them to the variable `hero` and the variable `team`. -/// info +/// note There was a lot of research, design, and work behind **SQLModel** to make this provide the best possible developer experience. diff --git a/docs/tutorial/create-db-and-table.md b/docs/tutorial/create-db-and-table.md index bbd5532ba..aca59af46 100644 --- a/docs/tutorial/create-db-and-table.md +++ b/docs/tutorial/create-db-and-table.md @@ -47,7 +47,7 @@ This class `Hero` **represents the table** for our heroes. And each instance we We use the config `table=True` to tell **SQLModel** that this is a **table model**, it represents a table. -/// info +/// note It's also possible to have models without `table=True`, those would be only **data models**, without a table in the database, they would not be **table models**. @@ -366,7 +366,7 @@ INFO Engine COMMIT -/// info +/// note I simplified the output above a bit to make it easier to read. @@ -538,7 +538,7 @@ if __name__ == "__main__": ...will **not** be executed. -/// info +/// note For more information, check the official Python docs. diff --git a/docs/tutorial/fastapi/limit-and-offset.md b/docs/tutorial/fastapi/limit-and-offset.md index 1a464a664..12416fcc7 100644 --- a/docs/tutorial/fastapi/limit-and-offset.md +++ b/docs/tutorial/fastapi/limit-and-offset.md @@ -8,7 +8,7 @@ So, we probably want to limit it. Let's use the same **offset** and **limit** we learned about in the previous tutorial chapters for the API. -/// info +/// note In many cases, this is also called **pagination**. @@ -32,7 +32,7 @@ So, to prevent it, we add additional validation to the `limit` query parameter, This way, a client can decide to take fewer heroes if they want, but not more. -/// info +/// note If you need to refresh how query parameters and their validation work, check out the docs in FastAPI: diff --git a/docs/tutorial/fastapi/read-one.md b/docs/tutorial/fastapi/read-one.md index 03a65a0a2..593818dba 100644 --- a/docs/tutorial/fastapi/read-one.md +++ b/docs/tutorial/fastapi/read-one.md @@ -8,7 +8,7 @@ Let's add a new *path operation* to read one single hero. We want to get the hero based on the `id`, so we will use a **path parameter** `hero_id`. -/// info +/// note If you need to refresh how *path parameters* work, including their data validation, check the FastAPI docs about Path Parameters. diff --git a/docs/tutorial/fastapi/response-model.md b/docs/tutorial/fastapi/response-model.md index f9214332c..a9f7f0f83 100644 --- a/docs/tutorial/fastapi/response-model.md +++ b/docs/tutorial/fastapi/response-model.md @@ -68,7 +68,7 @@ Additionally, because the schemas are defined in using a standard, there are man For example, client generators, that can automatically create the code necessary to talk to your API in many languages. -/// info +/// note If you are curious about the standards, FastAPI generates OpenAPI, that internally uses JSON Schema. diff --git a/docs/tutorial/fastapi/simple-hero-api.md b/docs/tutorial/fastapi/simple-hero-api.md index 79cf075e1..f40fb1056 100644 --- a/docs/tutorial/fastapi/simple-hero-api.md +++ b/docs/tutorial/fastapi/simple-hero-api.md @@ -40,7 +40,7 @@ But here we will make sure we don't share the same **session** in more than one And we also need to disable it because in **FastAPI** each request could be handled by multiple interacting threads. -/// info +/// note That's enough information for now, you can read more about it in the FastAPI docs for `async` and `await`. @@ -68,7 +68,7 @@ This should be called only once at startup, not before every request, so we put ## Create Heroes *Path Operation* -/// info +/// note If you need a refresher on what a **Path Operation** is (an endpoint with a specific HTTP Operation) and how to work with it in FastAPI, check out the FastAPI First Steps docs. @@ -80,7 +80,7 @@ It will be called when a user sends a request with a `POST` **operation** to the {* ./docs_src/tutorial/fastapi/simple_hero_api/tutorial001_py310.py ln[23:37] hl[31:32] *} -/// info +/// note If you need a refresher on some of those concepts, checkout the FastAPI documentation: @@ -152,7 +152,7 @@ $ fastapi dev main.py -/// info +/// note The `fastapi` command uses Uvicorn underneath. diff --git a/docs/tutorial/fastapi/tests.md b/docs/tutorial/fastapi/tests.md index f7fd92c9c..3ed6c50a8 100644 --- a/docs/tutorial/fastapi/tests.md +++ b/docs/tutorial/fastapi/tests.md @@ -214,7 +214,7 @@ Do we really have to duplicate all that for **each test**? No, we can do better! We are using **pytest** to run the tests. And pytest also has a very similar concept to the **dependencies in FastAPI**. -/// info +/// note In fact, pytest was one of the things that inspired the design of the dependencies in FastAPI. diff --git a/docs/tutorial/indexes.md b/docs/tutorial/indexes.md index 459ee8ce3..857938469 100644 --- a/docs/tutorial/indexes.md +++ b/docs/tutorial/indexes.md @@ -267,7 +267,7 @@ We use the same `Field()` again as we did before, and set `index=True`. That's i Notice that we didn't set an argument of `default=None` or anything similar. This means that **SQLModel** (thanks to Pydantic) will keep it as a **required** field. -/// info +/// note SQLModel (actually SQLAlchemy) will **automatically generate the index name** for you. diff --git a/docs/tutorial/insert.md b/docs/tutorial/insert.md index e2d9a4637..82a222902 100644 --- a/docs/tutorial/insert.md +++ b/docs/tutorial/insert.md @@ -193,7 +193,7 @@ And once we are ready, we can **commit** those changes, and then the **session** This makes the interactions with the database more efficient (plus some extra benefits). -/// info | Technical Details +/// note | Technical Details The session will create a new transaction and execute all the SQL code in that transaction. diff --git a/docs/tutorial/many-to-many/index.md b/docs/tutorial/many-to-many/index.md index 5cb3067e4..2e92df871 100644 --- a/docs/tutorial/many-to-many/index.md +++ b/docs/tutorial/many-to-many/index.md @@ -109,7 +109,7 @@ Specifically, the new link table `heroteamlink` would be: -/// info +/// note Other names used for this **link table** are: diff --git a/docs/tutorial/many-to-many/link-with-extra-fields.md b/docs/tutorial/many-to-many/link-with-extra-fields.md index 7c7756bcd..8e7d9de08 100644 --- a/docs/tutorial/many-to-many/link-with-extra-fields.md +++ b/docs/tutorial/many-to-many/link-with-extra-fields.md @@ -39,7 +39,7 @@ The new **relationship attributes** have their own `back_populates` pointing to * `team`: has `back_populates="hero_links"`, because in the `Team` model, the attribute will contain the links to the **team's heroes**. * `hero`: has `back_populates="team_links"`, because in the `Hero` model, the attribute will contain the links to the **hero's teams**. -/// info +/// note In SQLAlchemy this is called an Association Object or Association Model. diff --git a/docs/tutorial/relationship-attributes/cascade-delete-relationships.md b/docs/tutorial/relationship-attributes/cascade-delete-relationships.md index 3b6fe9156..ea1d47051 100644 --- a/docs/tutorial/relationship-attributes/cascade-delete-relationships.md +++ b/docs/tutorial/relationship-attributes/cascade-delete-relationships.md @@ -8,7 +8,7 @@ Should their `team_id` instead be set to `NULL` in the database? Let's see how to configure that with **SQLModel**. -/// info +/// note This feature, including `cascade_delete`, `ondelete`, and `passive_deletes`, is available since SQLModel version `0.0.21`. @@ -440,7 +440,7 @@ To be able to test this out with SQLite, we first need to enable foreign key sup {* ./docs_src/tutorial/relationship_attributes/cascade_delete_relationships/tutorial003_py310.py ln[30:33] hl[33] *} -/// info +/// note You can learn more about SQLite, foreign keys, and this SQL command on the SQLAlchemy docs. diff --git a/docs/tutorial/relationship-attributes/index.md b/docs/tutorial/relationship-attributes/index.md index f63b2669e..c45f75b4e 100644 --- a/docs/tutorial/relationship-attributes/index.md +++ b/docs/tutorial/relationship-attributes/index.md @@ -6,7 +6,7 @@ And then we read the data together with `select()` and using `.where()` or `.joi Now we will see how to use **Relationship Attributes**, an extra feature of **SQLModel** (and SQLAlchemy), to work with the data in the database in a much more familiar way, and closer to normal Python code. -/// info +/// note When I say "**relationship**" I mean the standard dictionary term, of data related to other data. diff --git a/docs/tutorial/relationship-attributes/type-annotation-strings.md b/docs/tutorial/relationship-attributes/type-annotation-strings.md index 74b97f08d..ca8114168 100644 --- a/docs/tutorial/relationship-attributes/type-annotation-strings.md +++ b/docs/tutorial/relationship-attributes/type-annotation-strings.md @@ -16,7 +16,7 @@ And of course, **SQLModel** can also understand it in the string correctly. ✨ That is actually part of Python, it's the current official solution to handle it. -/// info +/// note There's a lot of work going on in Python itself to make that simpler and more intuitive, and find ways to make it possible to not wrap the class in a string. diff --git a/docs/tutorial/select.md b/docs/tutorial/select.md index f31722d44..df0d1c0ff 100644 --- a/docs/tutorial/select.md +++ b/docs/tutorial/select.md @@ -289,7 +289,7 @@ And the second section reading data from the database could be in another functi So, both sections could be in **different places** and would need their own sessions. -/// info +/// note To be fair, in this example all that code could actually share the same **session**, there's actually no need to have two here. @@ -319,7 +319,7 @@ After printing it, we would see something like: ] ``` -/// info +/// note It would actually look more compact, I'm formatting it a bit for you to see that it is actually a list with all the data. @@ -353,7 +353,7 @@ SQLAchemy also has its own `select`, and SQLModel's `select` uses SQLAlchemy's ` But SQLModel's version does a lot of **tricks** with type annotations to make sure you get the best **editor support** possible, no matter if you use **VS Code**, **PyCharm**, or something else. ✨ -/// info +/// note There was a lot of work and research, with different versions of the internal code, to improve this as much as possible. 🤓 diff --git a/docs/tutorial/update.md b/docs/tutorial/update.md index 406637921..55af9c94d 100644 --- a/docs/tutorial/update.md +++ b/docs/tutorial/update.md @@ -34,7 +34,7 @@ And the second part, with the `WHERE`, defines to which rows it should apply tha In this case, as we only have one hero with the name `"Spider-Boy"`, it will only apply the update in that row. -/// info +/// note Notice that in the `UPDATE` the single equals sign (`=`) means **assignment**, setting a column to some value. diff --git a/docs/virtual-environments.md b/docs/virtual-environments.md index 131cd53d7..214c11213 100644 --- a/docs/virtual-environments.md +++ b/docs/virtual-environments.md @@ -2,7 +2,7 @@ When you work in Python projects you probably should use a **virtual environment** (or a similar mechanism) to isolate the packages you install for each project. -/// info +/// note If you already know about virtual environments, how to create them and use them, you might want to skip this section. 🤓 @@ -18,7 +18,7 @@ A **virtual environment** is a directory with some files in it. /// -/// info +/// note This page will teach you how to use **virtual environments** and how they work. diff --git a/docs_src/tutorial/automatic_id_none_refresh/annotations/en/tutorial002.md b/docs_src/tutorial/automatic_id_none_refresh/annotations/en/tutorial002.md index fee38368d..eea540309 100644 --- a/docs_src/tutorial/automatic_id_none_refresh/annotations/en/tutorial002.md +++ b/docs_src/tutorial/automatic_id_none_refresh/annotations/en/tutorial002.md @@ -307,7 +307,7 @@ 33. Print the `hero_1`. - /// info + /// note Even if the `hero_1` wasn't fresh, this would **not** trigger a `refresh` making the **session** use the **engine** to fetch data from the database because it is not accessing an attribute. @@ -323,7 +323,7 @@ 34. Print the `hero_2`. - /// info + /// note Even if the `hero_2` wasn't fresh, this would **not** trigger a `refresh` making the **session** use the **engine** to fetch data from the database because it is not accessing an attribute. @@ -339,7 +339,7 @@ 35. Print the `hero_3`. - /// info + /// note Even if the `hero_3` wasn't fresh, this would **not** trigger a `refresh` making the **session** use the **engine** to fetch data from the database because it is not accessing an attribute. diff --git a/docs_src/tutorial/fastapi/app_testing/tutorial001_py310/annotations/en/test_main_004.md b/docs_src/tutorial/fastapi/app_testing/tutorial001_py310/annotations/en/test_main_004.md index de754c5e7..3be0f1f7c 100644 --- a/docs_src/tutorial/fastapi/app_testing/tutorial001_py310/annotations/en/test_main_004.md +++ b/docs_src/tutorial/fastapi/app_testing/tutorial001_py310/annotations/en/test_main_004.md @@ -22,7 +22,7 @@ We tell it that with the `poolclass=StaticPool` parameter. - /// info + /// note You can read more details in the SQLAlchemy documentation about Using a Memory Database in Multiple Threads diff --git a/mkdocs.yml b/mkdocs.yml index 191e06b0e..8db44a124 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -165,17 +165,6 @@ markdown_extensions: # pymdownx blocks pymdownx.blocks.admonition: - types: - - note - - attention - - caution - - danger - - error - - tip - - hint - - warning - # Custom types - - info pymdownx.blocks.details: pymdownx.blocks.tab: alternate_style: True