Cut 2026.07.16 release, prose and dash pass

mikeckennedy · mikeckennedy · commit 5fd6f58eeccf · 2026-07-16T21:53:34.000-07:00
Move the Unreleased entries into a dated release matching the existing
YYYY.MM.DD - slug convention, and leave Unreleased empty for next time.

Prose:
- Replace em dashes with plain hyphens or shorter sentences across the
  guide and README, keeping dashes where they earn their place
- Tighten the --default explanation, which used "default" three times
- Fix a comma splice in the experimental-warning note
- "which interpreter python points to" rather than tangling Python/python

Step 3 no longer opens by telling readers to close and reopen a terminal
they already reopened in Step 1. Once ~/.local/bin is on PATH, python
resolves as soon as the install finishes (verified with an isolated PATH),
so the reopen is now a fallback after the expected output, where someone
who actually needs it will look.

Two changelog entries were stale: one claimed we added the reopen reminder
we ended up removing, and the fmt/MD044 work was unrecorded.
diff --git a/README.md b/README.md
@@ -1,9 +1,9 @@
 # Installing Python
 
-Installing Python used to be a complex decision tree experiment. Windows, macOS, or Linux? Is Python already installed? Is it the right version? Anaconda, Homebrew, or python.org? Not anymore — these days it's two commands on every platform, thanks to [uv](https://docs.astral.sh/uv/).
+Installing Python used to be a complex decision tree experiment. Windows, macOS, or Linux? Is Python already installed? Is it the right version? Anaconda, Homebrew, or python.org? Not anymore. These days it's two commands on every platform, thanks to [uv](https://docs.astral.sh/uv/).
 
 This repo is a place to allow for feedback and conversations around our **[Installing Python from Talk Python Training how-to article](https://training.talkpython.fm/installing-python)**.
 
 See the article source via [`install-python.md`](./install-python.md), and notable changes in [`change-log.md`](./change-log.md).
 
-Post an issue if you have a problem or comment *with the article* — note that we generally can't provide tech support. If you have a fix, PRs are accepted if they are a good fit.
+Post an issue if you have a problem or comment *with the article*. Note that we generally can't provide tech support. If you have a fix, PRs are accepted if they are a good fit.
diff --git a/change-log.md b/change-log.md
@@ -6,22 +6,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [2026.07.16] - python-default-flag
+
 ### Fixed
 
 - **`python -V` now actually works after following the guide.** `uv python install 3.14` only creates a versioned `python3.14` executable, so the macOS and Linux verification steps told readers to run `python -V` and expect success when they'd get `command not found`. All three platforms now install with `--default`, which creates the `python` and `python3` executables the guide promises.
 - Verification step is now consistent across Windows, macOS, and Linux (previously Windows used `uv run python -V` while macOS and Linux claimed bare `python -V` worked).
 - Corrected sample command output, which showed a `Searching for Python 3.14` line that uv does not print and omitted the installed executable names.
 - Updated Python version references from 3.14.2 to 3.14.6, and resolved the intro contradiction between "3.12+ is recommended" and installing 3.14.
 - Rewrote the virtual environment explanation. It said "once activated, you can use `python` directly," which was only meaningful back when bare `python` didn't work at all. It now teaches what activation actually does: `python` switches from your global 3.14 to the project's interpreter, which may be a different version entirely.
-- Refreshed the README, which still described the guide as a "complex decision tree" — the exact thing the 2025 rewrite eliminated. Also added Linux (the guide covers it), linked the changelog, and fixed punctuation.
+- Refreshed the README, which still described the guide as a "complex decision tree". That's the exact thing the 2025 rewrite eliminated. Also added Linux (the guide covers it), linked the changelog, and fixed punctuation.
 - Fixed two silently-ignored keys in `.rumdl.toml`: `disabled-rules` → `disable` and `MD048.code-fence-style` → `MD048.style`. Because the disable list never loaded, the guide's intentional inline HTML was being flagged on every run.
+- Stopped `rumdl fmt` from rewriting the repo link to display `https://GitHub.com/...`. MD044's proper-name rule was capitalizing the URL in the link text on every run. The link text is now descriptive rather than a raw URL.
 
 ### Added
 
 - Note that `--default` emits an experimental warning, so readers don't think the install failed.
 - Note that the patch version and install time in sample output will differ, so the page doesn't read as wrong the moment 3.14.7 ships.
 - Warning against using `--default` when installing multiple Python versions, plus how to intentionally repoint `python` at a different version later.
-- Explicit "close and reopen your terminal" reminder in each verification step.
+- `PATH` troubleshooting fallback in each verification step, phrased per platform, for anyone whose terminal hasn't picked up the new executables.
+
+### Changed
+
+- Prose pass over the guide and README: replaced em dashes with plain hyphens or shorter sentences, tightened the `--default` explanation, and corrected the "two steps" promise that was followed by three.
+- Applied `rumdl fmt` for consistent list markers, horizontal rules, and blank lines.
 
 ## [2025.12.10] - python-2025-guide
 
diff --git a/install-python.md b/install-python.md
@@ -2,13 +2,13 @@
 
 <img src="https://training.talkpython.fm/static/img/cms/nopy-final.jpg" style="border-radius: 10px; display: block;" class="img img-responsive" />
 
-Welcome soon-to-be Python user! Python is one of the easiest programming languages to learn and grow with. But there can be a bump right at the beginning: **making sure you have Python installed** with a sufficiently new version (3.14 is the current release, and it's what we'll install below).
+Welcome, soon-to-be Python user! Python is one of the easiest programming languages to learn and grow with. But there can be a bump right at the beginning: **making sure you have Python installed** with a sufficiently new version (3.14 is the current release, and it's what we'll install below).
 
-Good news! These days, installing Python has become incredibly simple thanks to **[uv](https://docs.astral.sh/uv/)** -- a blazing-fast Python package and project manager that also handles Python installation. With uv, you get **one tool** that works the same way on Windows, macOS, and Linux. [Hear all about it](https://talkpython.fm/episodes/show/476/unified-python-packaging-with-uv) on Talk Python.
+The good news is that these days, installing Python is incredibly simple thanks to **[uv](https://docs.astral.sh/uv/)**, a blazing-fast Python package and project manager that also handles Python installation. With uv, you get **one tool** that works the same way on Windows, macOS, and Linux. [Hear all about it](https://talkpython.fm/episodes/show/476/unified-python-packaging-with-uv) on Talk Python.
 
 ## The Modern Approach: Install uv, Then Python
 
-The process is just two steps:
+The process is just two commands:
 
 1. **Install uv** (one command)
 2. **Install Python with uv** (one command)
@@ -43,7 +43,7 @@ Now install Python 3.14 with a single command:
 uv python install 3.14 --default
 ```
 
-The `--default` flag is what gives you a plain `python` command (rather than only `python3.14`), so this is the version you'll get by default from now on.
+The `--default` flag gives you a plain `python` command rather than only `python3.14`, so this becomes the Python you get from now on.
 
 You'll see output like:
 
@@ -52,12 +52,10 @@ Installed Python 3.14.6 in 2.1s
  + cpython-3.14.6-windows-x86_64-none (python, python3, python3.14)
 ```
 
-Your exact patch version and install time will differ — Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong: the flag works, it just isn't finalized yet.
+Your exact patch version and install time will differ. Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong. The flag works; it just isn't finalized yet.
 
 ### Step 3. Verify It Works
 
-**Close and reopen your terminal**, then run:
-
 ```powershell
 python -V
 ```
@@ -68,6 +66,8 @@ You should see:
 Python 3.14.6
 ```
 
+If PowerShell says `python` isn't recognized, close and reopen your terminal so it picks up the updated `PATH`, then try again.
+
 **You're all set!** 🎉
 
 <a id="macos" style="margin-bottom: 10px; display: inline-block;"></a>
@@ -94,7 +94,7 @@ Now install Python 3.14 with a single command:
 uv python install 3.14 --default
 ```
 
-The `--default` flag is what gives you a plain `python` command (rather than only `python3.14`), so this is the version you'll get by default from now on.
+The `--default` flag gives you a plain `python` command rather than only `python3.14`, so this becomes the Python you get from now on.
 
 You'll see output like:
 
@@ -103,12 +103,10 @@ Installed Python 3.14.6 in 1.9s
  + cpython-3.14.6-macos-aarch64-none (python, python3, python3.14)
 ```
 
-Your exact patch version and install time will differ — Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong: the flag works, it just isn't finalized yet.
+Your exact patch version and install time will differ. Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong. The flag works; it just isn't finalized yet.
 
 ### Step 3. Verify It Works
 
-**Close and reopen your terminal**, then run:
-
 ```bash
 python -V
 ```
@@ -119,6 +117,8 @@ You should see:
 Python 3.14.6
 ```
 
+If you get a `command not found` error, close and reopen your terminal so it picks up the updated `PATH`, then try again.
+
 **You're all set!** 🎉
 
 <a id="linux" style="margin-bottom: 10px; display: inline-block;"></a>
@@ -145,7 +145,7 @@ Now install Python 3.14 with a single command:
 uv python install 3.14 --default
 ```
 
-The `--default` flag is what gives you a plain `python` command (rather than only `python3.14`), so this is the version you'll get by default from now on.
+The `--default` flag gives you a plain `python` command rather than only `python3.14`, so this becomes the Python you get from now on.
 
 You'll see output like:
 
@@ -154,12 +154,10 @@ Installed Python 3.14.6 in 1.5s
  + cpython-3.14.6-linux-x86_64-gnu (python, python3, python3.14)
 ```
 
-Your exact patch version and install time will differ — Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong: the flag works, it just isn't finalized yet.
+Your exact patch version and install time will differ. Python ships regular patch releases, so 3.14.7 or later is just as good. uv also prints a `warning:` noting that `--default` is experimental. That's expected, and nothing is wrong. The flag works; it just isn't finalized yet.
 
 ### Step 3. Verify It Works
 
-**Close and reopen your terminal** (or run `source ~/.bashrc` or `source ~/.zshrc`), then run:
-
 ```bash
 python -V
 ```
@@ -170,6 +168,8 @@ You should see:
 Python 3.14.6
 ```
 
+If you get a `command not found` error, close and reopen your terminal (or run `source ~/.bashrc` or `source ~/.zshrc`) so it picks up the updated `PATH`, then try again.
+
 **You're all set!** 🎉
 
 _________________________
@@ -186,7 +186,7 @@ Navigate to your project folder and run:
 uv venv --python 3.14
 ```
 
-This creates a `.venv` folder in your project. If Python 3.14 isn't already installed, **uv will automatically download and install it for you**.
+This creates a `.venv` folder in your project. If Python 3.14 isn't already installed, **uv will automatically download and install it for you**. On a fast connection, this can take as little as 2-3 seconds.
 
 ### Activating the Virtual Environment
 
@@ -202,7 +202,7 @@ This creates a `.venv` folder in your project. If Python 3.14 isn't already inst
 source .venv/bin/activate
 ```
 
-Activating doesn't just make `python` available — it changes which Python `python` means. Instead of the global 3.14 you installed earlier, it now points at this project's interpreter, which can be an entirely different version:
+Activating doesn't just make `python` available - it changes which interpreter `python` points to. Instead of the global 3.14 you installed earlier, you get this project's own Python, which can be an entirely different version:
 
 ```bash
 python -V
@@ -240,7 +240,7 @@ Need multiple Python versions? uv handles that too:
 uv python install 3.12 3.13 3.14
 ```
 
-Note there's no `--default` here. Only one version at a time can own the plain `python` command, so leave `--default` off when installing extra versions — otherwise you'll quietly repoint `python` at whichever version you installed last. Each version is always reachable by its full name (`python3.12`, `python3.13`) regardless.
+Note there's no `--default` here. Only one version at a time can own the plain `python` command, so leave `--default` off when installing extra versions. Otherwise you'll quietly repoint `python` at whichever version you installed last. Each version is always reachable by its full name (`python3.12`, `python3.13`) regardless.
 
 List installed versions, including any that came with your system:
 
@@ -266,11 +266,11 @@ _________________________
 
 **[uv](https://docs.astral.sh/uv/)** is developed by [Astral](https://astral.sh/), the creators of [Ruff](https://docs.astral.sh/ruff/) (the popular Python linter). It's designed to be:
 
-- ⚡️ **Blazing fast** -- 10-100x faster than pip
-- 🐍 **Python version manager** -- installs and manages Python itself
-- 📦 **Package manager** -- replaces pip, pip-tools, and virtualenv
-- 🔒 **Lockfile support** -- reproducible environments
-- 🖥️ **Cross-platform** -- works identically on Windows, macOS, and Linux
+- ⚡️ **Blazing fast** - 10-100x faster than pip
+- 🐍 **Python version manager** - installs and manages Python itself
+- 📦 **Package manager** - replaces pip, pip-tools, and virtualenv
+- 🔒 **Lockfile support** - reproducible environments
+- 🖥️ **Cross-platform** - works identically on Windows, macOS, and Linux
 
 One tool. No complexity. Just Python.
 
@@ -280,4 +280,4 @@ _________________________
 
 If you find a problem or have a suggestion to make this page better, please open an issue on GitHub. Note that this is not intended for tech support but rather for genuine, broadly applicable improvements to the instructions:
 
-[**talkpython/installing-python**](https://github.com/talkpython/installing-python)
+[**https://github.com/talkpython/installing-python**](https://github.com/talkpython/installing-python)
