Skip to content

Commit d2adb99

Browse files
committed
📝 Adopt unversioned documentation snippets
1 parent 2ebee74 commit d2adb99

243 files changed

Lines changed: 364 additions & 400 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/advanced/datetime.md‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ Pydantic provides [`AwareDatetime` and `NaiveDatetime`](https://docs.pydantic.de
6565

6666
We can use them as field types:
6767

68-
{* ./docs_src/advanced/datetime/tutorial002_py310.py ln[1:8] hl[1,7:8] *}
68+
{* ./docs_src/advanced/datetime/tutorial002.py ln[1:8] hl[1,7:8] *}
6969

7070
Here, `starts_at` requires timezone information during validation. It uses the same database type as `datetime`: `UTCDateTime`.
7171

@@ -77,7 +77,7 @@ These types also work with `| None` and with `Annotated`, for example `Annotated
7777

7878
We can use `Event.model_validate()` to validate the data before creating an event:
7979

80-
{* ./docs_src/advanced/datetime/tutorial002_py310.py ln[11:17] hl[13:14,16] *}
80+
{* ./docs_src/advanced/datetime/tutorial002.py ln[11:17] hl[13:14,16] *}
8181

8282
The `Z` at the end of `starts_at` means **UTC**. The value for `local_time` has no timezone, so both values pass validation.
8383

@@ -137,13 +137,13 @@ Back up the database and test schema changes, data conversions, and application
137137

138138
Change the field annotation to `NaiveDatetime`:
139139

140-
{* ./docs_src/advanced/datetime/tutorial005_py310.py ln[1:9] hl[3,9] *}
140+
{* ./docs_src/advanced/datetime/tutorial005.py ln[1:9] hl[3,9] *}
141141

142142
This keeps the previous database column type, so no database migration is needed for that field. It also adds the validation constraint described above.
143143

144144
To retain the previous database type **and** plain `datetime` validation behavior, declare the database type explicitly:
145145

146-
{* ./docs_src/advanced/datetime/tutorial003_py310.py ln[1:9] hl[3,9] *}
146+
{* ./docs_src/advanced/datetime/tutorial003.py ln[1:9] hl[3,9] *}
147147

148148
### Adopt Timezone-Aware Storage on PostgreSQL
149149

@@ -153,7 +153,7 @@ To retain the previous database type **and** plain `datetime` validation behavio
153153

154154
For example, if `event.created_at` contains naive **UTC** values, the operations in the generated revision can be:
155155

156-
{* ./docs_src/advanced/datetime/tutorial004_py310.py hl[9:11,19:21] *}
156+
{* ./docs_src/advanced/datetime/tutorial004.py hl[9:11,19:21] *}
157157

158158
This migration uses `sa.DateTime(timezone=True)`, the underlying database type of `UTCDateTime`.
159159

‎docs/advanced/decimal.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ For the database, **SQLModel** will use [SQLAlchemy's `DECIMAL` type](https://do
3333

3434
Let's say that each hero in the database will have an amount of money. We can define that field as a `Decimal` and configure the maximum number of digits and decimal places using the parameters of `Field()`:
3535

36-
{* ./docs_src/advanced/decimal/tutorial001_py310.py ln[1:11] hl[11] *}
36+
{* ./docs_src/advanced/decimal/tutorial001.py ln[1:11] hl[11] *}
3737

3838
Here we are saying that `money` can have at most `5` digits with `max_digits`, **this includes the integers** (to the left of the decimal dot) **and the decimals** (to the right of the decimal dot).
3939

@@ -67,13 +67,13 @@ Make sure you adjust the number of digits and decimal places for your own needs,
6767

6868
When creating new models you can actually pass normal (`float`) numbers, Pydantic will automatically convert them to `Decimal` types, and **SQLModel** will store them as `Decimal` types in the database (using SQLAlchemy).
6969

70-
{* ./docs_src/advanced/decimal/tutorial001_py310.py ln[24:34] hl[25:27] *}
70+
{* ./docs_src/advanced/decimal/tutorial001.py ln[24:34] hl[25:27] *}
7171

7272
## Select Decimal data
7373

7474
Then, when working with Decimal types, you can confirm that they indeed avoid those rounding errors from floats:
7575

76-
{* ./docs_src/advanced/decimal/tutorial001_py310.py ln[37:50] hl[49:50] *}
76+
{* ./docs_src/advanced/decimal/tutorial001.py ln[37:50] hl[49:50] *}
7777

7878
## Review the results
7979

‎docs/advanced/uuid.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ We don't call `uuid.uuid4()` ourselves in the code (we don't put the parenthesis
8080

8181
This means that the UUID will be generated in the Python code, **before sending the data to the database**.
8282

83-
{* ./docs_src/advanced/uuid/tutorial001_py310.py ln[1:10] hl[1,7] *}
83+
{* ./docs_src/advanced/uuid/tutorial001.py ln[1:10] hl[1,7] *}
8484

8585
Pydantic has support for [`UUID` types](https://docs.pydantic.dev/latest/api/standard_library_types/#uuid).
8686

@@ -94,15 +94,15 @@ As `uuid.uuid4` will be called when creating the model instance, even before sen
9494

9595
And that **same ID (a UUID)** will be saved in the database.
9696

97-
{* ./docs_src/advanced/uuid/tutorial001_py310.py ln[23:34] hl[25,27,29,34] *}
97+
{* ./docs_src/advanced/uuid/tutorial001.py ln[23:34] hl[25,27,29,34] *}
9898

9999
### Select a Hero
100100

101101
We can do the same operations we could do with other fields.
102102

103103
For example we can **select a hero by ID**:
104104

105-
{* ./docs_src/advanced/uuid/tutorial001_py310.py ln[37:54] hl[49] *}
105+
{* ./docs_src/advanced/uuid/tutorial001.py ln[37:54] hl[49] *}
106106

107107
/// tip
108108

@@ -116,7 +116,7 @@ SQLModel (actually SQLAlchemy) will take care of making it work. ✨
116116

117117
We could also select by ID with `session.get()`:
118118

119-
{* ./docs_src/advanced/uuid/tutorial002_py310.py ln[37:53] hl[49] *}
119+
{* ./docs_src/advanced/uuid/tutorial002.py ln[37:53] hl[49] *}
120120

121121
The same way as with other fields, we could update, delete, etc. 🚀
122122

‎docs/tutorial/automatic-id-none-refresh.md‎

Lines changed: 9 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ Now let's talk a bit about why the `id` field **can't be `NULL`** on the databas
66

77
But the same `id` field actually **can be `None`** in the Python code, so we declare the type with `int | None`, and set the default value to `Field(default=None)`:
88

9-
{* ./docs_src/tutorial/automatic_id_none_refresh/tutorial001_py310.py ln[4:8] hl[5] *}
9+
{* ./docs_src/tutorial/automatic_id_none_refresh/tutorial001.py ln[4:8] hl[5] *}
1010

1111
Next, I'll show you a bit more about the synchronization of data between the database and the Python code.
1212

@@ -16,7 +16,7 @@ When do we get an actual `int` from the database in that `id` field? Let's see a
1616

1717
When we create a new `Hero` instance, we don't set the `id`:
1818

19-
{* ./docs_src/tutorial/automatic_id_none_refresh/tutorial001_py310.py ln[21:24] hl[21:24] *}
19+
{* ./docs_src/tutorial/automatic_id_none_refresh/tutorial001.py ln[21:24] hl[21:24] *}
2020

2121
### How `int | None` Helps
2222

@@ -44,7 +44,7 @@ But by declaring it with `int | None`, the editor will help us to avoid writing
4444

4545
We can confirm that by printing our heroes before adding them to the database:
4646

47-
{* ./docs_src/tutorial/automatic_id_none_refresh/tutorial001_py310.py ln[21:29] hl[27:29] *}
47+
{* ./docs_src/tutorial/automatic_id_none_refresh/tutorial001.py ln[21:29] hl[27:29] *}
4848

4949
That will output:
5050

@@ -75,7 +75,7 @@ After we add the `Hero` instance objects to the **session**, the IDs are *still*
7575

7676
We can verify by creating a session using a `with` block and adding the objects. And then printing them again:
7777

78-
{* ./docs_src/tutorial/automatic_id_none_refresh/tutorial001_py310.py ln[21:39] hl[37:39] *}
78+
{* ./docs_src/tutorial/automatic_id_none_refresh/tutorial001.py ln[21:39] hl[37:39] *}
7979

8080
This will, again, output the `id`s of the objects as `None`:
8181

@@ -100,7 +100,7 @@ As we saw before, the **session** is smart and doesn't talk to the database ever
100100

101101
Then we can `commit` the changes in the session, and print again:
102102

103-
{* ./docs_src/tutorial/automatic_id_none_refresh/tutorial001_py310.py ln[31:46] hl[41,44:46] *}
103+
{* ./docs_src/tutorial/automatic_id_none_refresh/tutorial001.py ln[31:46] hl[41,44:46] *}
104104

105105
And now, something unexpected happens, look at the output, it seems as if the `Hero` instance objects had no data at all:
106106

@@ -158,7 +158,7 @@ We didn't access the object's attributes, like `hero.name`. We only accessed the
158158

159159
To confirm and understand how this **automatic expiration and refresh** of data when accessing attributes work, we can print some individual fields (instance attributes):
160160

161-
{* ./docs_src/tutorial/automatic_id_none_refresh/tutorial001_py310.py ln[31:56] hl[49:51,54:56] *}
161+
{* ./docs_src/tutorial/automatic_id_none_refresh/tutorial001.py ln[31:56] hl[49:51,54:56] *}
162162

163163
Now we are actually accessing the attributes, because instead of printing the whole object `hero_1`:
164164

@@ -239,7 +239,7 @@ But what if you want to **explicitly refresh** the data?
239239

240240
You can do that too with `session.refresh(object)`:
241241

242-
{* ./docs_src/tutorial/automatic_id_none_refresh/tutorial001_py310.py ln[31:65] hl[58:60,63:65] *}
242+
{* ./docs_src/tutorial/automatic_id_none_refresh/tutorial001.py ln[31:65] hl[58:60,63:65] *}
243243

244244
When Python executes this code:
245245

@@ -297,7 +297,7 @@ Now, as a final experiment, we can also print data after the **session** is clos
297297

298298
There are no surprises here, it still works:
299299

300-
{* ./docs_src/tutorial/automatic_id_none_refresh/tutorial001_py310.py ln[31:70] hl[68:70] *}
300+
{* ./docs_src/tutorial/automatic_id_none_refresh/tutorial001.py ln[31:70] hl[68:70] *}
301301

302302
And the output shows again the same data:
303303

@@ -332,16 +332,12 @@ And as we created the **engine** with `echo=True`, we can see the SQL statements
332332

333333
///
334334

335-
//// tab | Python 3.10+
336-
337335
```Python
338-
{!./docs_src/tutorial/automatic_id_none_refresh/tutorial002_py310.py!}
336+
{!./docs_src/tutorial/automatic_id_none_refresh/tutorial002.py!}
339337
```
340338

341339
{!./docs_src/tutorial/automatic_id_none_refresh/annotations/en/tutorial002.md!}
342340

343-
////
344-
345341
And here's all the output generated by running this program, all together:
346342

347343
<div class="termy">

‎docs/tutorial/code-structure.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,7 @@ We can use these relative imports because, for example, in the file `app.py` (th
6767

6868
You could put all the database Models in a single Python module (a single Python file), for example `models.py`:
6969

70-
{* ./docs_src/tutorial/code_structure/tutorial001_py310/models.py *}
70+
{* ./docs_src/tutorial/code_structure/tutorial001/models.py *}
7171

7272
This way, you wouldn't have to deal with circular imports for other models.
7373

@@ -77,15 +77,15 @@ And then you could import the models from this file/module in any other file/mod
7777

7878
Then you could put the code creating the **engine** and the function to create all the tables (if you are not using migrations) in another file `database.py`:
7979

80-
{* ./docs_src/tutorial/code_structure/tutorial001_py310/database.py *}
80+
{* ./docs_src/tutorial/code_structure/tutorial001/database.py *}
8181

8282
This file would also be imported by your application code, to use the shared **engine** and to get and call the function `create_db_and_tables()`.
8383

8484
### Application File
8585

8686
Finally, you could put the code to create the **app** in another file `app.py`:
8787

88-
{* ./docs_src/tutorial/code_structure/tutorial001_py310/app.py hl[3:4] *}
88+
{* ./docs_src/tutorial/code_structure/tutorial001/app.py hl[3:4] *}
8989

9090
Here we import the models, the engine, and the function to create all the tables and then we can use them all internally.
9191

@@ -201,23 +201,23 @@ So, we can use it in an `if` block and import things inside the `if` block. And
201201

202202
Using that trick of `TYPE_CHECKING` we can "import" the `Team` in `hero_model.py`:
203203

204-
{* ./docs_src/tutorial/code_structure/tutorial002_py310/hero_model.py hl[1,5:6,16] *}
204+
{* ./docs_src/tutorial/code_structure/tutorial002/hero_model.py hl[1,5:6,16] *}
205205

206206
Keep in mind that now we *have* to put the annotation of `Team` as a string: `"Team"`, so that Python doesn't have errors at runtime.
207207

208208
### Team Model File
209209

210210
We use the same trick in the `team_model.py` file:
211211

212-
{* ./docs_src/tutorial/code_structure/tutorial002_py310/team_model.py hl[1,5:6,14] *}
212+
{* ./docs_src/tutorial/code_structure/tutorial002/team_model.py hl[1,5:6,14] *}
213213

214214
Now we get editor support, autocompletion, inline errors, and **SQLModel** keeps working. 🎉
215215

216216
### App File
217217

218218
Now, just for completeness, the `app.py` file would import the models from both modules:
219219

220-
{* ./docs_src/tutorial/code_structure/tutorial002_py310/app.py hl[4:5,10,12:14] *}
220+
{* ./docs_src/tutorial/code_structure/tutorial002/app.py hl[4:5,10,12:14] *}
221221

222222
And of course, all the tricks with `TYPE_CHECKING` and type annotations in strings are **only needed in the files with circular imports**.
223223

‎docs/tutorial/connect/create-connected-rows.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ We will later update **Spider-Boy** to add him to the **Preventers** team too, b
4545

4646
We will continue with the code in the previous example and we will add more things to it.
4747

48-
{* ./docs_src/tutorial/connect/create_tables/tutorial001_py310.py ln[0] *}
48+
{* ./docs_src/tutorial/connect/create_tables/tutorial001.py ln[0] *}
4949

5050
Make sure you remove the `database.db` file before running the examples to get the same results.
5151

@@ -57,7 +57,7 @@ And now we will also create the teams there. 🎉
5757

5858
Let's start by creating two teams:
5959

60-
{* ./docs_src/tutorial/connect/insert/tutorial001_py310.py ln[29:35] hl[29:35] *}
60+
{* ./docs_src/tutorial/connect/insert/tutorial001.py ln[29:35] hl[29:35] *}
6161

6262
This would hopefully look already familiar.
6363

@@ -73,7 +73,7 @@ And finally we **commit** the session to save the changes to the database.
7373

7474
Let's not forget to add this function `create_heroes()` to the `main()` function so that we run it when calling the program from the command line:
7575

76-
{* ./docs_src/tutorial/connect/insert/tutorial001_py310.py ln[61:63] hl[63] *}
76+
{* ./docs_src/tutorial/connect/insert/tutorial001.py ln[61:63] hl[63] *}
7777

7878
## Run it
7979

@@ -106,7 +106,7 @@ Now let's create one hero object to start.
106106

107107
As the `Hero` class model now has a field (column, attribute) `team_id`, we can set it by using the ID field from the `Team` objects we just created before:
108108

109-
{* ./docs_src/tutorial/connect/insert/tutorial001_py310.py ln[29:39] hl[38] *}
109+
{* ./docs_src/tutorial/connect/insert/tutorial001.py ln[29:39] hl[38] *}
110110

111111
We haven't committed this hero to the database yet, but there are already a couple of things to pay **attention** to.
112112

@@ -130,7 +130,7 @@ INFO Engine [generated in 0.00025s] (2,)
130130

131131
Let's now create two more heroes:
132132

133-
{* ./docs_src/tutorial/connect/insert/tutorial001_py310.py ln[29:50] hl[40:46] *}
133+
{* ./docs_src/tutorial/connect/insert/tutorial001.py ln[29:50] hl[40:46] *}
134134

135135
When creating `hero_rusty_man`, we are accessing `team_preventers.id`, so that will also trigger a refresh of its data, generating an output of:
136136

@@ -161,7 +161,7 @@ INFO Engine COMMIT
161161

162162
Now let's refresh and print those new heroes to see their new ID pointing to their teams:
163163

164-
{* ./docs_src/tutorial/connect/insert/tutorial001_py310.py ln[29:58] hl[52:54,56:58] *}
164+
{* ./docs_src/tutorial/connect/insert/tutorial001.py ln[29:58] hl[52:54,56:58] *}
165165

166166
If we execute that in the command line, it will output:
167167

‎docs/tutorial/connect/create-connected-tables.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ Let's start by creating the tables in code.
5757

5858
Import the things we need from `sqlmodel` and create a new `Team` model:
5959

60-
{* ./docs_src/tutorial/connect/create_tables/tutorial001_py310.py ln[1:7] hl[4:7] *}
60+
{* ./docs_src/tutorial/connect/create_tables/tutorial001.py ln[1:7] hl[4:7] *}
6161

6262
This is very similar to what we have been doing with the `Hero` model.
6363

@@ -76,7 +76,7 @@ Now let's create the `hero` table.
7676

7777
This is the same model we have been using up to now, we are just adding the new column `team_id`:
7878

79-
{* ./docs_src/tutorial/connect/create_tables/tutorial001_py310.py ln[1:16] hl[16] *}
79+
{* ./docs_src/tutorial/connect/create_tables/tutorial001.py ln[1:16] hl[16] *}
8080

8181
Most of that should look familiar:
8282

@@ -110,11 +110,11 @@ You can learn about setting a custom table name for a model in the Advanced User
110110

111111
Now we can add the same code as before to create the engine and the function to create the tables:
112112

113-
{* ./docs_src/tutorial/connect/create_tables/tutorial001_py310.py ln[19:26] hl[19:20,22,25:26] *}
113+
{* ./docs_src/tutorial/connect/create_tables/tutorial001.py ln[19:26] hl[19:20,22,25:26] *}
114114

115115
And as before, we'll call this function from another function `main()`, and we'll add that function `main()` to the main block of the file:
116116

117-
{* ./docs_src/tutorial/connect/create_tables/tutorial001_py310.py ln[29:34] hl[29:30,33:34] *}
117+
{* ./docs_src/tutorial/connect/create_tables/tutorial001.py ln[29:34] hl[29:30,33:34] *}
118118

119119
## Run the Code
120120

0 commit comments

Comments
 (0)