EDIT: Update python code guide and include linting, formatting and type checking (#22737)

estebanx64 · web-flow · commit a30fb9e53d28 · 2025-06-24T10:23:54.000-07:00
## Description * I updated the code in the main Python guide. I noticed some deprecations in the libraries. I made a refactor and updated the whole code to be totally up to date with the recent library version * I added a section about linting, formatting, and type checking to follow the best practices. I include them in the CI/CD too @craig-osterhout @usha-mandya - [ ] Technical review - [ ] Editorial review - [ ] Product review
diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt
@@ -1,6 +1,7 @@
 (?i)[A-Z]{2,}'?s
 Amazon
 Anchore
+Aleksandrov
 Apple
 Artifactory
 Azure
@@ -73,6 +74,7 @@ Intune
 iptables
 IPv[46]
 IPvlan
+isort
 Jamf
 JetBrains
 JFrog
@@ -124,6 +126,8 @@ PKG
 Postgres
 PowerShell
 Python
+Pyright
+pyright
 rollback
 rootful
 runc
diff --git a/content/guides/python/_index.md b/content/guides/python/_index.md
@@ -15,10 +15,17 @@ params:
   time: 20 minutes
 ---
 
+> **Acknowledgment**
+>
+> This guide is a community contribution. Docker would like to thank
+> [Esteban Maya](https://www.linkedin.com/in/esteban-x64/) and [Igor Aleksandrov](https://www.linkedin.com/in/igor-aleksandrov/) for their contribution
+> to this guide.
+
 The Python language-specific guide teaches you how to containerize a Python application using Docker. In this guide, you’ll learn how to:
 
 - Containerize and run a Python application
 - Set up a local environment to develop a Python application using containers
+- Lint, format, typing and best practices
 - Configure a CI/CD pipeline for a containerized Python application using GitHub Actions
 - Deploy your containerized Python application locally to Kubernetes to test and debug your deployment
 
diff --git a/content/guides/python/configure-github-actions.md b/content/guides/python/configure-github-actions.md
@@ -1,7 +1,7 @@
 ---
 title: Automate your builds with GitHub Actions
 linkTitle: Automate your builds with GitHub Actions
-weight: 20
+weight: 40
 keywords: ci/cd, github actions, python, flask
 description: Learn how to configure CI/CD using GitHub Actions for your Python application.
 aliases:
@@ -60,6 +60,27 @@ on:
       - main
 
 jobs:
+  lint-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Run pre-commit hooks
+        run: pre-commit run --all-files
+
+      - name: Run pyright
+        run: pyright
+
   build_and_push:
     runs-on: ubuntu-latest
     steps:
@@ -97,7 +118,11 @@ When the workflow is complete, go to your [repositories on Docker Hub](https://h
 
 ## Summary
 
-In this section, you learned how to set up a GitHub Actions workflow for your Python application.
+In this section, you learned how to set up a GitHub Actions workflow for your Python application that includes:
+
+- Running pre-commit hooks for linting and formatting
+- Static type checking with Pyright
+- Building and pushing Docker images
 
 Related information:
 
@@ -107,5 +132,5 @@ Related information:
 
 ## Next steps
 
-In the next section, you'll learn how you can develop your application using containers.
+In the next section, you'll learn how you can develop locally using kubernetes.
 
diff --git a/content/guides/python/containerize.md b/content/guides/python/containerize.md
@@ -58,7 +58,7 @@ This utility will walk you through creating the following files with sensible de
 Let's get started!
 
 ? What application platform does your project use? Python
-? What version of Python do you want to use? 3.11.4
+? What version of Python do you want to use? 3.12
 ? What port do you want your app to listen on? 8000
 ? What is the command to run your app? python3 -m uvicorn app:app --host=0.0.0.0 --port=8000
 ```
@@ -139,8 +139,8 @@ Create a file named `Dockerfile` with the following contents.
 
 # Want to help us make this template better? Share your feedback here: https://forms.gle/ybq9Krt8jtBL3iCk7
 
-ARG PYTHON_VERSION=3.11.4
-FROM python:${PYTHON_VERSION}-slim AS base
+ARG PYTHON_VERSION=3.12
+FROM python:${PYTHON_VERSION}-slim
 
 # Prevents Python from writing pyc files.
 ENV PYTHONDONTWRITEBYTECODE=1
@@ -181,7 +181,7 @@ COPY . .
 EXPOSE 8000
 
 # Run the application.
-CMD python3 -m uvicorn app:app --host=0.0.0.0 --port=8000
+CMD ["python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"]
 ```
 
 Create a file named `compose.yaml` with the following contents.
@@ -375,6 +375,4 @@ Related information:
 
 ## Next steps
 
-In the next section, you'll take a look at how to set up a CI pipeline using GitHub Actions.
-
-
+In the next section, you'll take a look at how to set up a local development environment using Docker containers.
diff --git a/content/guides/python/develop.md b/content/guides/python/develop.md
@@ -1,7 +1,7 @@
 ---
 title: Use containers for Python development
 linkTitle: Develop your app
-weight: 40
+weight: 15
 keywords: python, local, development
 description: Learn how to develop your Python application locally.
 aliases:
@@ -51,7 +51,7 @@ You'll need to clone a new repository to get a sample application that includes
    Let's get started!
 
    ? What application platform does your project use? Python
-   ? What version of Python do you want to use? 3.11.4
+   ? What version of Python do you want to use? 3.12
    ? What port do you want your app to listen on? 8001
    ? What is the command to run your app? python3 -m uvicorn app:app --host=0.0.0.0 --port=8001
    ```
@@ -132,8 +132,8 @@ You'll need to clone a new repository to get a sample application that includes
 
    # Want to help us make this template better? Share your feedback here: https://   forms.gle/ybq9Krt8jtBL3iCk7
 
-   ARG PYTHON_VERSION=3.11.4
-   FROM python:${PYTHON_VERSION}-slim as base
+   ARG PYTHON_VERSION=3.12
+   FROM python:${PYTHON_VERSION}-slim
 
    # Prevents Python from writing pyc files.
    ENV PYTHONDONTWRITEBYTECODE=1
@@ -174,7 +174,7 @@ You'll need to clone a new repository to get a sample application that includes
    EXPOSE 8001
 
    # Run the application.
-   CMD python3 -m uvicorn app:app --host=0.0.0.0 --port=8001
+   CMD ["python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8001"]
    ```
 
    Create a file named `compose.yaml` with the following contents.
@@ -569,4 +569,4 @@ Related information:
 
 ## Next steps
 
-In the next section, you'll learn how you can locally test and debug your workloads on Kubernetes before deploying.
+In the next section, you'll learn how you can set up linting, formatting and type checking to follow the best practices in python apps.
diff --git a/content/guides/python/lint-format-typing.md b/content/guides/python/lint-format-typing.md
@@ -0,0 +1,122 @@
+---
+title: Linting, formatting, and type checking for Python
+linkTitle: Linting and typing
+weight: 25
+keywords: Python, linting, formatting, type checking, ruff, pyright
+description: Learn how to set up linting, formatting and type checking for your Python application.
+aliases:
+  - /language/python/lint-format-typing/
+---
+
+## Prerequisites
+
+Complete [Develop your app](develop.md).
+
+## Overview
+
+In this section, you'll learn how to set up code quality tools for your Python application. This includes:
+
+- Linting and formatting with Ruff
+- Static type checking with Pyright
+- Automating checks with pre-commit hooks
+
+## Linting and formatting with Ruff
+
+Ruff is an extremely fast Python linter and formatter written in Rust. It replaces multiple tools like flake8, isort, and black with a single unified tool.
+
+Create a `pyproject.toml` file:
+
+```toml
+[tool.ruff]
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+    "ARG001", # unused arguments in functions
+]
+ignore = [
+    "E501",  # line too long, handled by black
+    "B008",  # do not perform function calls in argument defaults
+    "W191",  # indentation contains tabs
+    "B904",  # Allow raising exceptions without from e, for HTTPException
+]
+```
+
+### Using Ruff
+
+Run these commands to check and format your code:
+
+```bash
+# Check for errors
+ruff check .
+
+# Automatically fix fixable errors
+ruff check --fix .
+
+# Format code
+ruff format .
+```
+
+## Type checking with Pyright
+
+Pyright is a fast static type checker for Python that works well with modern Python features.
+
+Add `Pyright` configuration in `pyproject.toml`:
+
+```toml
+[tool.pyright]
+typeCheckingMode = "strict"
+pythonVersion = "3.12"
+exclude = [".venv"]
+```
+
+### Running Pyright
+
+To check your code for type errors:
+
+```bash
+pyright
+```
+
+## Setting up pre-commit hooks
+
+Pre-commit hooks automatically run checks before each commit. The following `.pre-commit-config.yaml` snippet sets up Ruff:
+
+```yaml
+  https: https://github.com/charliermarsh/ruff-pre-commit
+  rev: v0.2.2
+  hooks:
+    - id: ruff
+      args: [--fix]
+    - id: ruff-format
+```
+
+To install and use:
+
+```bash
+pre-commit install
+git commit -m "Test commit"  # Automatically runs checks
+```
+
+## Summary
+
+In this section, you learned how to:
+
+- Configure and use Ruff for linting and formatting
+- Set up Pyright for static type checking
+- Automate checks with pre-commit hooks
+
+These tools help maintain code quality and catch errors early in development.
+
+## Next steps
+
+- [Configure GitHub Actions](configure-github-actions.md) to run these checks automatically
+- Customize linting rules to match your team's style preferences
+- Explore advanced type checking features
