📝 Tweak docs

tiangolo · tiangolo · commit 6ff74f212a39 · 2024-08-21T19:40:10.000-05:00
diff --git a/docs/en/docs/advanced/settings.md b/docs/en/docs/advanced/settings.md
@@ -8,15 +8,15 @@ For this reason it's common to provide them in environment variables that are re
 
 /// tip
 
-To understand environment variables you can read the page [Environment Variables](../environment-variables.md){.internal-link target=_blank}
+To understand environment variables you can read [Environment Variables](../environment-variables.md){.internal-link target=_blank}.
 
 ///
 
 ## 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 validation has to be done in code.
+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.
 
 ## Pydantic `Settings`
 
diff --git a/docs/en/docs/environment-variables.md b/docs/en/docs/environment-variables.md
@@ -161,11 +161,11 @@ You can read more about it at <a href="https://12factor.net/config" class="exter
 
 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 validation has to be done in code.
+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.
 
 You will learn more about using environment variables for handling **application settings** in the [Advanced User Guide - Settings and Environment Variables](./advanced/settings.md){.internal-link target=_blank}.
 
-## `PATH` environment variable
+## `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.
 
@@ -192,13 +192,13 @@ This means that the system should look for programs in the directories:
 //// tab | Windows
 
 ```plaintext
-C:\Program Files\Python39\Scripts;C:\Program Files\Python39;C:\Windows\System32
+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\Python39\Scripts`
-* `C:\Program Files\Python39`
+* `C:\Program Files\Python312\Scripts`
+* `C:\Program Files\Python312`
 * `C:\Windows\System32`
 
 ////
@@ -236,7 +236,7 @@ Let's say you install Python and it ends up in a directory `C:\opt\custompython\
 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\Python39\Scripts;C:\Program Files\Python39;C:\Windows\System32;C:\opt\custompython\bin
+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.
diff --git a/docs/en/docs/tutorial/security/first-steps.md b/docs/en/docs/tutorial/security/first-steps.md
@@ -58,9 +58,11 @@ The <a href="https://github.com/Kludex/python-multipart" class="external-link" t
 
 However, if you use the `pip install fastapi` command, the `python-multipart` package is not included by default.
 
-To install it manually, make sure you create a [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then install it with:
+To install it manually, make sure you create a [virtual environment](../../virtual-environments.md){.internal-link target=_blank}, activate it, and then install it with:
 
-`pip install python-multipart`
+```console
+$ pip install python-multipart
+```
 
 This is because **OAuth2** uses "form data" for sending the `username` and `password`.
 
diff --git a/docs/en/docs/tutorial/security/oauth2-jwt.md b/docs/en/docs/tutorial/security/oauth2-jwt.md
@@ -30,7 +30,7 @@ If you want to play with JWT tokens and see how they work, check <a href="https:
 
 We need to install `PyJWT` to generate and verify the JWT tokens in Python.
 
-Make sure you create a [virtual environment](../virtual-environments.md){.internal-link target=_blank}, activate it, and then install `pyjwt`:
+Make sure you create a [virtual environment](../../virtual-environments.md){.internal-link target=_blank}, activate it, and then install `pyjwt`:
 
 <div class="termy">
 
diff --git a/docs/en/docs/virtual-environments.md b/docs/en/docs/virtual-environments.md
@@ -106,7 +106,7 @@ But you could customize it passing an additional argument with the directory nam
 
 ////
 
-That creates a new virtual environment in a directory called `.venv`.
+That command creates a new virtual environment in a directory called `.venv`.
 
 /// details | `.venv` or other name
 
@@ -269,7 +269,7 @@ $ echo "*" > .venv/.gitignore
 /// details | What that command means
 
 * `echo "*"`: will "print" the text `*` in the terminal (the next part changes that a bit)
-* `>`: anything printed to the terminal by the previous command before `>` should not be printed but instead written to the file that goes next to `>`
+* `>`: anything printed to the terminal by the command to the left of `>` should not be printed but instead written to the file that goes to the right of `>`
 * `.gitignore`: the name of the file where the text should be written
 
 And `*` for Git means "everything". So, it will ignore everything in the `.venv` directory.
@@ -300,7 +300,7 @@ If you're in a hurry and don't want to use a file to declare your project's pack
 
 /// tip
 
-It's a (very) good idea to put the packages and versions your program needs in a file later (for example `requirements.txt` or `pyproject.toml`).
+It's a (very) good idea to put the packages and versions your program needs in a file (for example `requirements.txt` or `pyproject.toml`).
 
 ///
 
@@ -358,6 +358,7 @@ If you have <a href="https://github.com/astral-sh/uv" class="external-link" targ
 
 ```console
 $ uv pip install -r requirements.txt
+---> 100%
 ```
 
 </div>
@@ -486,7 +487,7 @@ flowchart LR
     end
 ```
 
-But then if you want to run `priosner-of-azkaban`, you will need to uninstall `harry` version `1` and install `harry` version `3` (or just installing version `3` would automatically uninstall version `1`).
+But then if you want to run `prisoner-of-azkaban`, you will need to uninstall `harry` version `1` and install `harry` version `3` (or just installing version `3` would automatically uninstall version `1`).
 
 <div class="termy">
 
@@ -498,6 +499,8 @@ $ pip install "harry==3"
 
 And then you would end up with `harry` version `3` installed in your global Python environment.
 
+And if you try to run `philosophers-stone` again, there's a chance it would **not work** because it needs `harry` version `1`.
+
 ```mermaid
 flowchart LR
     subgraph global[global env]
@@ -513,7 +516,13 @@ flowchart LR
     end
 ```
 
-Now, imagine that with **many** other **packages** that all your **projects depend on**. That's very difficult to manage. And you would probably end up trying to run some projects with some **incompatible versions** of the packages, and not knowing why some are working or not.
+/// tip
+
+It's very common in Python packages to try the best to **avoid breaking changes** in **new versions**, but it's better to be safe, and install newer versions intentionally and when you can run the tests to check everything is working correctly.
+
+///
+
+Now, imagine that with **many** other **packages** that all your **projects depend on**. That's very difficult to manage. And you would probably end up running some projects with some **incompatible versions** of the packages, and not knowing why something isn't working.
 
 Also, depending on your operating system (e.g. Linux, Windows, macOS), it could have come with Python already installed. And in that case it probably had some packages pre-installed with some specific versions **needed by your system**. If you install packages in the global Python environment, you could end up **breaking** some of the programs that came with your operating system.
 
@@ -610,7 +619,7 @@ $ source .venv/Scripts/activate
 
 ////
 
-That command will create some [environment variables](environment-variables.md){.internal-link target=_blank} that will be available for the next commands.
+That command will create or modify some [environment variables](environment-variables.md){.internal-link target=_blank} that will be available for the next commands.
 
 One of those variables is the `PATH` variable.
 
@@ -620,7 +629,7 @@ You can learn more about the `PATH` environment variable in the [Environment Var
 
 ///
 
-Activating a virtual environment adds its path, `.venv/bin` (on Linux and macOS) or `.venv\Scripts` (on Windows) to the `PATH` environment variable.
+Activating a virtual environment adds its path `.venv/bin` (on Linux and macOS) or `.venv\Scripts` (on Windows) to the `PATH` environment variable.
 
 Let's say that before activating the environment, the `PATH` variable looked like this:
 
@@ -701,7 +710,9 @@ and use that one.
 
 ////
 
-Activating a virtual environment also changes a couple of other things, but this is one of the most important details.
+An important detail is that it will put the virtual environment path at the **beginning** of the `PATH` variable. The system will find it **before** finding any other Python available. This way, when you run `python`, it will use the Python **from the virtual environment** instead of any other `python` (for example, a `python` from a global environment).
+
+Activating a virtual environment also changes a couple of other things, but this is one of the most important things it does.
 
 ## Checking a Virtual Environment
 
@@ -823,7 +834,7 @@ Once you are ready and want to use a tool to **manage the entire project**, pack
 * Manage the **virtual environment** for your projects
 * Install **packages**
 * Manage package **dependencies and versions** for your project
-* Make sure you have an **exact** set of packages and versions to install, including their dependencies, so that you can be sure that you can run your project exactly the same as in your computer while developing, this is called **locking**
+* Make sure you have an **exact** set of packages and versions to install, including their dependencies, so that you can be sure that you can run your project in production exactly the same as in your computer while developing, this is called **locking**
 * And many other things
 
 ## Conclusion
