Python 3.14 Fundamentals

Python 3.14 Fundamentals

13+

Learn Python the way it is actually written in 2026

0 followers
21 chapters
Software & AI Development
2026

$49 a year. The paperback ships free with your first year.

Buying multiple copies? Request bulk pricing.
You're viewing a limited preview. Create a free account to read free books or get Premium to unlock the entire library.

Chapter 1: Hello, Python 3.14

What You Will Learn

  • Install the uv toolchain and use it to manage CPython 3.14 interpreters
  • Create a new Python project with uv init and recognize the generated source layout
  • Pin a project to a specific Python interpreter using .python-version
  • Launch the modern REPL and execute Python statements interactively
  • Run a minimal module inside a uv-managed environment using uv run
  • Identify the Personal Knowledge Tracker CLI as the sample application that will evolve throughout this book

Prerequisites

No additional prerequisites beyond those listed in About This Book.

Concept Overview

Python 3.14 is the current general-availability release of CPython, the reference implementation of Python written in C. A reference implementation is the standard version that defines how the language behaves. Most developers run CPython in production.

Two interpreter binaries ship with the release. The standard build is python3.14. It retains the Global Interpreter Lock (GIL), a mutex that allows only one thread to execute Python bytecode at a time. The second build is python3.14t, an officially supported free-threaded interpreter that removes the GIL. Free-threaded means multiple threads can run Python bytecode truly in parallel. The free-threaded build is opt-in only.

Start with the standard build. Only switch if you have a specific CPU-bound threading workload, meaning tasks that spend most of their time computing rather than waiting for external I/O.

For project management, modern Python relies on uv. Astral's uv binary replaces pip, pip-tools, pipenv, poetry, pyenv, and virtualenv. It installs interpreters, creates virtual environments, resolves dependencies, and runs commands. This book uses uv for every project task.

The Personal Knowledge Tracker CLI is this book's running sample application. It is a local-first command-line tool for capturing, organizing, and searching short knowledge notes. Over the next twelve chapters it will grow from a single file into a tested, typed, async-capable package. In this chapter you will scaffold the project and write its first lines of code.

Step-by-Step Implementation

Step 1: Install uv

Install the uv binary using the official installer in your terminal, the command-line interface where you type shell commands.

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows, use PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

The installer places uv in a directory that is typically on your PATH. PATH is an environment variable that tells your shell where to find executable programs. After installation, verify that uv is available.

uv --version

If uv --version prints an error instead of a version number, close and reopen your terminal so the shell reloads its environment, or manually add the uv binary directory to your PATH. Once the command succeeds, the toolchain is ready.

Step 2: Install CPython 3.14

uv can download and manage Python interpreters itself. Install CPython 3.14 now; this places the interpreter in uv's managed cache without modifying your system Python.

uv python install 3.14

Verify the installation by listing available interpreters.

uv python list

You should see an entry for 3.14.0 or a later patch release. Seeing the version in this list confirms that uv can provision the interpreter on demand.

Step 3: Create the Personal Knowledge Tracker Project

Create a new project directory and initialize it with uv init. The command generates a pyproject.toml, a .python-version pin, and a src/ tree. If the generated .python-version does not already contain 3.14, overwrite it with the following command.

uv init knowledge-tracker
cd knowledge-tracker
echo "3.14" > .python-version

The generated pyproject.toml looks like this (excerpt):

[project]
name = "knowledge-tracker"
version = "0.1.0"
description = "A new Python project."
requires-python = ">=3.14"

If uv init detected a different default interpreter and produced a lower requires-python value, edit the file so it matches the excerpt above. The .python-version file contains a single line, 3.14. Every uv run or uv sync command in this directory will select the latest patch release of that Python version. Pinning prevents the "works on my machine" problem.

Step 4: Understand the Source Layout

uv init creates a source layout by default. A source layout places the package code, the importable Python code for your application, under src/knowledge_tracker/ rather than at the repository root, the top-level directory of your project. An installed package is what users import after installation. Flat layout, where code lives directly at the project root, is a legacy pattern.

knowledge-tracker/
├── .python-version
├── pyproject.toml
├── src/
│   └── knowledge_tracker/
│       └── __init__.py
└── tests/

Source layout is the correct default for every new Python project. It prevents accidental imports from the repository root and ensures that test code imports the installed package exactly as users will. Last year I migrated a flat-layout project to src/ and watched an entire category of CI import failures vanish overnight. Treat flat layout as a legacy pattern. The uv.lock lockfile will appear once you add dependencies and run uv sync; it is not present yet because the project has no external packages.

Step 5: Add a Minimal Entry Point

You will now add three things: a function that returns text, a function that runs the program, and an execution guard that prevents accidental invocation on import. The -> str and -> None symbols are type hints; they document that a function returns a string or returns nothing. Python ignores these at runtime, but they help readers and tools understand the code.

Open src/knowledge_tracker/__init__.py. Replace its contents with a small greeting function and a main entry point.

def greet() -> str:
    return "Hello from the Personal Knowledge Tracker."

def main() -> None:
    message = greet()
    print(message)

The greet function returns a str. The main function coordinates the program; it calls greet, captures the result, and prints it. The if __name__ == "__main__" guard ensures main runs only when the file is executed directly, not when it is imported as a module. The -m flag tells Python to run a module as a script. For uv run python -m knowledge_tracker to find an entry point, the package needs a __main__.py file that imports and calls main().

Create src/knowledge_tracker/__main__.py with the following content.

from knowledge_tracker import main

if __name__ == "__main__":
    main()

This separation keeps executable behavior in __main__.py while leaving __init__.py clean for imports.

Step 6: Run the Application

A virtual environment is an isolated Python installation with its own packages. Execute the module through uv run. This command selects the interpreter pinned in .python-version, creates the virtual environment if it does not yet exist, and runs your code.

uv run python -m knowledge_tracker

You should see:

Hello from the Personal Knowledge Tracker.

If you see a ModuleNotFoundError, check that you are inside the knowledge-tracker directory and that .python-version is present. Running the module through uv confirms that the source layout is wired correctly and the package is importable.

Step 7: Explore the REPL

Python's interactive REPL is a first-class tool. Launch it with uv run python.

uv run python

At the >>> prompt, inspect the running interpreter. The sys module provides system-specific parameters and functions.

>>> import sys
>>> sys.version_info
sys.version_info(major=3, minor=14, micro=0, releaselevel='final', serial=0)
>>> sys._is_gil_enabled()
True

The sys.version_info tuple confirms you are running Python 3.14. The sys._is_gil_enabled() function returns True because the standard build is active. The REPL supports syntax highlighting and multiline editing. Use it to experiment before committing code to a file.

Exit the REPL with Ctrl+D on Linux or macOS, or Ctrl+Z followed by Enter on Windows.

Full Example

Here is the complete state of the package after the steps above.

src/knowledge_tracker/__init__.py:

def greet() -> str:
    return "Hello from the Personal Knowledge Tracker."

def main() -> None:
    message = greet()
    print(message)

src/knowledge_tracker/__main__.py:

from knowledge_tracker import main

if __name__ == "__main__":
    main()

To run it, ensure your working directory is the project root and execute:

uv run python -m knowledge_tracker

The project structure should now match the source layout convention:

knowledge-tracker/
├── .python-version
├── pyproject.toml
├── src/
│   └── knowledge_tracker/
│       ├── __init__.py
│       └── __main__.py
└── tests/

This skeleton is small, but it is the foundation for every chapter that follows. The greet function will evolve into note creation logic, and main will become the CLI dispatcher. The src/ tree will expand into models, storage, commands, and cli modules. The uv.lock file will appear once you add external dependencies and run uv sync. Start simple; grow deliberately.

Common Mistakes

  • Mixing system Python with uv-managed interpreters. Installing Python through apt, brew, or Windows Store alongside uv python install creates confusion about which binary is active. Pick one source per machine; uv is the modern default.
  • Forgetting the `.python-version` pin. Without this file, uv run selects a different interpreter on a teammate's machine. Always commit .python-version to version control.
  • Adding code at the project root instead of under `src/`. Files placed next to pyproject.toml are not part of the installed package. Keep all application code inside src/knowledge_tracker/.
  • Using `pip install` inside a uv project. uv manages its own virtual environment. Use uv add <package> to declare dependencies and uv run to execute commands. Don't activate virtual environments manually.
  • Omitting the `if __name__ == "__main__"` guard. Without it, importing the module as a library triggers main() immediately. The guard separates executable behavior from importable behavior.

Performance and Production Considerations

uv resolves dependencies an order of magnitude faster than pip. For local development, this means installing packages in milliseconds rather than seconds. For CI pipelines, it means faster job startup and lower compute costs. Standardize on uv for every new project.

The standard python3.14 build remains the correct choice for production services. The free-threaded python3.14t build is available for CPU-bound multithreading. It is somewhat slower per thread than the standard build but can scale work across multiple cores. Do not switch to the free-threaded build unless profiling proves the GIL is your bottleneck.

Source layout prevents import bugs that flat layout encourages. When tests run against an installed package rather than repository root files, they validate the same import paths that production uses. Adopt source layout from day one; retrofitting it later is tedious.

Commit both pyproject.toml and .python-version to version control. Once uv generates a uv.lock file, commit it as well. These files are the minimum needed for another developer to reproduce your environment exactly.

Summary

You installed uv, used it to install CPython 3.14, and created the Personal Knowledge Tracker project. You pinned the interpreter with .python-version, explored the REPL, and ran a minimal module via uv run. The source layout convention is now in place.

The Personal Knowledge Tracker CLI will grow from this foundation, gaining new language features, refactors, and tooling in each subsequent chapter. Keep this project directory open; you'll return to it in Chapter 2.

Key Terms

  • CPython: the reference implementation of Python, written in C. The python3.14 binary runs this interpreter.
  • uv: Astral's project management tool. It installs interpreters, creates projects, resolves dependencies, and runs commands in a single binary.
  • Source layout: the project structure that places package code under src/<package>/ rather than at the repository root. This prevents accidental local imports and ensures tests exercise the installed package.
  • `.python-version`: a text file that tells uv which Python interpreter version to use for a project. uv reads this file automatically.
  • REPL: Read-Eval-Print Loop. The interactive Python shell launched with uv run python that supports syntax highlighting and multiline editing.
  • GIL: Global Interpreter Lock. A mutex in CPython that allows only one thread to execute Python bytecode at a time. The standard python3.14 build retains it.
  • Free-threaded Python: the python3.14t build of CPython that removes the GIL. It is opt-in and officially supported as of 3.14.
  • `if __name__ == "__main__"`: a module-level guard that executes code only when a file is run directly, not when it is imported.

Mini Quiz

  1. A colleague asks you to add the httpx library to the Personal Knowledge Tracker project. Which command is correct?

A. pip install httpx

B. uv init httpx

C. uv run httpx

D. uv add httpx

  1. The project stores its code under src/knowledge_tracker/ instead of at the repository root. What is the main benefit of this source layout?

A. It allows the code to run without a virtual environment.

B. It eliminates the need for __init__.py files.

C. It makes the package importable only on Python 3.14.

D. It prevents accidental imports from the repository root and ensures tests use the installed package.

  1. In src/knowledge_tracker/__init__.py, the main function is wrapped in if __name__ == "__main__": main(). What happens if you remove this guard and import the module from another file?

A. The import statement fails with a syntax error.

B. Python automatically renames __name__ to "__main__".

C. The module becomes impossible to test.

D. main() executes immediately during the import.

  1. After profiling, you confirm the GIL is the bottleneck on a CPU-bound multithreading workload. Which interpreter build should you deploy?

A. The python3.14t free-threaded build

B. The standard python3.14 build

C. The system Python installed by the OS package manager

D. The REPL interactive shell

  1. A new teammate clones the Personal Knowledge Tracker repository, but uv run python selects Python 3.13 instead of 3.14. Which file is most likely missing or incorrect?

A. pyproject.toml

B. uv.lock

C. .python-version

D. src/knowledge_tracker/__init__.py

  1. You open the REPL and run import sys; print(sys._is_gil_enabled()). The output is True. What does this indicate?

A. The interpreter is running with the Global Interpreter Lock active.

B. The interpreter is in free-threaded mode.

C. The project has a syntax error in pyproject.toml.

D. The virtual environment is corrupted.

Answers are provided in the Answer Key at the end of the book.

Activity

  • Open your Personal Knowledge Tracker project directory.
  • Create a new file at src/knowledge_tracker/repl_demo.py.
  • Define a function get_python_version() that returns the string "3.14".
  • Define a main() function that calls get_python_version(), assigns the result to a variable named version, and prints it with print("Tracker running on Python", version).
  • Add the if __name__ == "__main__" guard so main() runs only when the file is executed directly.
  • Run the file with uv run python -m knowledge_tracker.repl_demo and verify the output.
  • Launch the REPL with uv run python, then type the following import and call:
>>> from knowledge_tracker.repl_demo import get_python_version
>>> get_python_version()
'3.14'
  • You'll confirm that importing the module does not trigger the print statement from main().

Enjoying this book?

Create a free account to leave comments, track your progress, and more!

Read and listen on the go with the unQbd app. Get the app
An unhandled error has occurred. Reload 🗙

Rejoining the server...

Rejoin failed... trying again in seconds.

Failed to rejoin.
Please retry or reload the page.

The session has been paused by the server.

Failed to resume the session.
Please reload the page.