📝 Add docs for virtual environments and environment variables

Author: tiangolo

.gitignore

@@ -1,5 +1,4 @@
 *.pyc
-env*
 .mypy_cache
 .vscode
 .idea
@@ -12,3 +11,4 @@ coverage.xml
 site
 *.db
 .cache
+.venv*

README.md

@@ -65,6 +65,8 @@ As **SQLModel** is based on **Pydantic** and **SQLAlchemy**, it requires them. T
 
 ## Installation
 
+Make sure you create a <a href="https://sqlmodel.tiangolo.com/virtual-environments/" class="external-link" target="_blank">virtual environment</a>, activate it, and then install SQLModel, for example with:
+
 <div class="termy">
 
 ```console

docs/databases.md

@@ -4,7 +4,7 @@
 
 Are you a seasoned developer and already know everything about databases? 🤓
 
-Then you can skip to the [Tutorial - User Guide: First Steps](tutorial/index.md){.internal-link target=_blank} right away.
+Then you can skip to the next sections right away.
 
 ///
 

docs/environment-variables.md

@@ -0,0 +1,300 @@
+# Environment Variables
+
+Before we jump into code, let's cover a bit some of the **basics** that we'll need to understand how to work with Python (and programming) in general. Let's check a bit about **environment variables**.
+
+/// tip
+
+If you already know what "environment variables" are and how to use them, feel free to skip this.
+
+///
+
+An environment variable (also known as "**env var**") is a variable that lives **outside** of the Python code, in the **operating system**, and could be read by your Python code (or by other programs as well).
+
+Environment variables could be useful for handling application **settings**, as part of the **installation** of Python, etc.
+
+## Create and Use Env Vars
+
+You can **create** and use environment variables in the **shell (terminal)**, without needing Python:
+
+//// tab | Linux, macOS, Windows Bash
+
+<div class="termy">
+
+```console
+// You could create an env var MY_NAME with
+$ export MY_NAME="Wade Wilson"
+
+// Then you could use it with other programs, like
+$ echo "Hello $MY_NAME"
+
+Hello Wade Wilson
+```
+
+</div>
+
+////
+
+//// tab | Windows PowerShell
+
+<div class="termy">
+
+```console
+// Create an env var MY_NAME
+$ $Env:MY_NAME = "Wade Wilson"
+
+// Use it with other programs, like
+$ echo "Hello $Env:MY_NAME"
+
+Hello Wade Wilson
+```
+
+</div>
+
+////
+
+## Read env vars in Python
+
+You could also create environment variables **outside** of Python, in the terminal (or with any other method), and then **read them in Python**.
+
+For example you could have a file `main.py` with:
+
+```Python hl_lines="3"
+import os
+
+name = os.getenv("MY_NAME", "World")
+print(f"Hello {name} from Python")
+```
+
+/// tip
+
+The second argument to <a href="https://docs.python.org/3.8/library/os.html#os.getenv" class="external-link" target="_blank">`os.getenv()`</a> is the default value to return.
+
+If not provided, it's `None` by default, here we provide `"World"` as the default value to use.
+
+///
+
+Then you could call that Python program:
+
+//// tab | Linux, macOS, Windows Bash
+
+<div class="termy">
+
+```console
+// Here we don't set the env var yet
+$ python main.py
+
+// As we didn't set the env var, we get the default value
+
+Hello World from Python
+
+// But if we create an environment variable first
+$ export MY_NAME="Wade Wilson"
+
+// And then call the program again
+$ python main.py
+
+// Now it can read the environment variable
+
+Hello Wade Wilson from Python
+```
+
+</div>
+
+////
+
+//// tab | Windows PowerShell
+
+<div class="termy">
+
+```console
+// Here we don't set the env var yet
+$ python main.py
+
+// As we didn't set the env var, we get the default value
+
+Hello World from Python
+
+// But if we create an environment variable first
+$ $Env:MY_NAME = "Wade Wilson"
+
+// And then call the program again
+$ python main.py
+
+// Now it can read the environment variable
+
+Hello Wade Wilson from Python
+```
+
+</div>
+
+////
+
+As environment variables can be set outside of the code, but can be read by the code, and don't have to be stored (committed to `git`) with the rest of the files, it's common to use them for configurations or **settings**.
+
+You can also create an environment variable only for a **specific program invocation**, that is only available to that program, and only for its duration.
+
+To do that, create it right before the program itself, on the same line:
+
+<div class="termy">
+
+```console
+// Create an env var MY_NAME in line for this program call
+$ MY_NAME="Wade Wilson" python main.py
+
+// Now it can read the environment variable
+
+Hello Wade Wilson from Python
+
+// The env var no longer exists afterwards
+$ python main.py
+
+Hello World from Python
+```
+
+</div>
+
+/// tip
+
+You can read more about it at <a href="https://12factor.net/config" class="external-link" target="_blank">The Twelve-Factor App: Config</a>.
+
+///
+
+## Types and Validation
+
+These environment variables can only handle **text strings**, as they are external to Python and have to be compatible with other programs and the rest of the system (and even with different operating systems, as Linux, Windows, macOS).
+
+That means that **any value** read in Python from an environment variable **will be a `str`**, and any conversion to a different type or any validation has to be done in code.
+
+## `PATH` Environment Variable
+
+There is a **special** environment variable called **`PATH`** that is used by the operating systems (Linux, macOS, Windows) to find programs to run.
+
+The value of the variable `PATH` is a long string that is made of directories separated by a colon `:` on Linux and macOS, and by a semicolon `;` on Windows.
+
+For example, the `PATH` environment variable could look like this:
+
+//// tab | Linux, macOS
+
+```plaintext
+/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
+```
+
+This means that the system should look for programs in the directories:
+
+* `/usr/local/bin`
+* `/usr/bin`
+* `/bin`
+* `/usr/sbin`
+* `/sbin`
+
+////
+
+//// tab | Windows
+
+```plaintext
+C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32
+```
+
+This means that the system should look for programs in the directories:
+
+* `C:\Program Files\Python312\Scripts`
+* `C:\Program Files\Python312`
+* `C:\Windows\System32`
+
+////
+
+When you type a **command** in the terminal, the operating system **looks for** the program in **each of those directories** listed in the `PATH` environment variable.
+
+For example, when you type `python` in the terminal, the operating system looks for a program called `python` in the **first directory** in that list.
+
+If it finds it, then it will **use it**. Otherwise it keeps looking in the **other directories**.
+
+### Installing Python and Updating the `PATH`
+
+When you install Python, you might be asked if you want to update the `PATH` environment variable.
+
+//// tab | Linux, macOS
+
+Let's say you install Python and it ends up in a directory `/opt/custompython/bin`.
+
+If you say yes to update the `PATH` environment variable, then the installer will add `/opt/custompython/bin` to the `PATH` environment variable.
+
+It could look like this:
+
+```plaintext
+/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin
+```
+
+This way, when you type `python` in the terminal, the system will find the Python program in `/opt/custompython/bin` (the last directory) and use that one.
+
+////
+
+//// tab | Windows
+
+Let's say you install Python and it ends up in a directory `C:\opt\custompython\bin`.
+
+If you say yes to update the `PATH` environment variable, then the installer will add `C:\opt\custompython\bin` to the `PATH` environment variable.
+
+```plaintext
+C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin
+```
+
+This way, when you type `python` in the terminal, the system will find the Python program in `C:\opt\custompython\bin` (the last directory) and use that one.
+
+////
+
+This way, when you type `python` in the terminal, the system will find the Python program in `/opt/custompython/bin` (the last directory) and use that one.
+
+So, if you type:
+
+<div class="termy">
+
+```console
+$ python
+```
+
+</div>
+
+//// tab | Linux, macOS
+
+The system will **find** the `python` program in `/opt/custompython/bin` and run it.
+
+It would be roughly equivalent to typing:
+
+<div class="termy">
+
+```console
+$ /opt/custompython/bin/python
+```
+
+</div>
+
+////
+
+//// tab | Windows
+
+The system will **find** the `python` program in `C:\opt\custompython\bin\python` and run it.
+
+It would be roughly equivalent to typing:
+
+<div class="termy">
+
+```console
+$ C:\opt\custompython\bin\python
+```
+
+</div>
+
+////
+
+This information will be useful when learning about [Virtual Environments](virtual-environments.md){.internal-link target=_blank}.
+
+## Conclusion
+
+With this you should have a basic understanding of what **environment variables** are and how to use them in Python.
+
+You can also read more about them in the <a href="https://en.wikipedia.org/wiki/Environment_variable" class="external-link" target="_blank">Wikipedia for Environment Variable</a>.
+
+In many cases it's not very obvious how environment variables would be useful and applicable right away. But they keep showing up in many different scenarios when you are developing, so it's good to know about them.
+
+For example, you will need this information in the next section, about [Virtual Environments](virtual-environments.md).

docs/index.md

@@ -78,6 +78,8 @@ As **SQLModel** is based on **Pydantic** and **SQLAlchemy**, it requires them. T
 
 ## Installation
 
+Make sure you create a <a href="https://sqlmodel.tiangolo.com/virtual-environments/" class="external-link" target="_blank">virtual environment</a>, activate it, and then install SQLModel, for example with:
+
 <div class="termy">
 
 ```console

docs/install.md

@@ -0,0 +1,39 @@
+# Install **SQLModel**
+
+Create a project directory, create a [virtual environment](virtual-environments.md){.internal-link target=_blank}, activate it, and then install **SQLModel**, for example with:
+
+<div class="termy">
+
+```console
+$ pip install sqlmodel
+---> 100%
+Successfully installed sqlmodel pydantic sqlalchemy
+```
+
+</div>
+
+As **SQLModel** is built on top of <a href="https://www.sqlalchemy.org/" class="external-link" target="_blank">SQLAlchemy</a> and <a href="https://pydantic-docs.helpmanual.io/" class="external-link" target="_blank">Pydantic</a>, when you install `sqlmodel` they will also be automatically installed.
+
+## Install DB Browser for SQLite
+
+Remember that [SQLite is a simple database in a single file](../databases.md#a-single-file-database){.internal-link target=_blank}?
+
+For most of the tutorial I'll use SQLite for the examples.
+
+Python has integrated support for SQLite, it is a single file read and processed from Python. And it doesn't need an [External Database Server](../databases.md#a-server-database){.internal-link target=_blank}, so it will be perfect for learning.
+
+In fact, SQLite is perfectly capable of handling quite big applications. At some point you might want to migrate to a server-based database like <a href="https://www.postgresql.org/" class="external-link" target="_blank">PostgreSQL</a> (which is also free). But for now we'll stick to SQLite.
+
+Through the tutorial I will show you SQL fragments, and Python examples. And I hope (and expect 🧐) you to actually run them, and verify that the database is working as expected and showing you the same data.
+
+To be able to explore the SQLite file yourself, independent of Python code (and probably at the same time), I recommend you use <a href="https://sqlitebrowser.org/" class="external-link" target="_blank">DB Browser for SQLite</a>.
+
+It's a great and simple program to interact with SQLite databases (SQLite files) in a nice user interface.
+
+<img src="https://sqlitebrowser.org/images/screenshot.png">
+
+Go ahead and <a href="https://sqlitebrowser.org/" class="external-link" target="_blank">Install DB Browser for SQLite</a>, it's free.
+
+## Next Steps
+
+Okay, let's get going! On the next section we'll start the [Tutorial - User Guide](tutorial/index.md). 🚀

docs/tutorial/fastapi/simple-hero-api.md

@@ -10,14 +10,14 @@ FastAPI is the framework to create the **web API**.
 
 But we also need another type of program to run it, it is called a "**server**". We will use **Uvicorn** for that. And we will install Uvicorn with its *standard* dependencies.
 
-Make sure you [have a virtual environment activated](../index.md#create-a-python-virtual-environment){.internal-link target=_blank}.
+Then install FastAPI.
 
-Then install FastAPI and Uvicorn:
+Make sure you create a [virtual environment](../../virtual-environments.md){.internal-link target=_blank}, activate it, and then install them, for example with:
 
 <div class="termy">
 
 ```console
-$ python -m pip install fastapi "uvicorn[standard]"
+$ pip install fastapi "uvicorn[standard]"
 
 ---> 100%
 ```