Skip to content

Commit a30fb9e

Browse files
estebanx64estebanx64
authored
EDIT: Update python code guide and include linting, formatting and type checking (#22737)
## 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
1 parent 77924e0 commit a30fb9e

6 files changed

Lines changed: 172 additions & 16 deletions

File tree

‎_vale/config/vocabularies/Docker/accept.txt‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
(?i)[A-Z]{2,}'?s
22
Amazon
33
Anchore
4+
Aleksandrov
45
Apple
56
Artifactory
67
Azure
@@ -73,6 +74,7 @@ Intune
7374
iptables
7475
IPv[46]
7576
IPvlan
77+
isort
7678
Jamf
7779
JetBrains
7880
JFrog
@@ -124,6 +126,8 @@ PKG
124126
Postgres
125127
PowerShell
126128
Python
129+
Pyright
130+
pyright
127131
rollback
128132
rootful
129133
runc

‎content/guides/python/_index.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,17 @@ params:
1515
time: 20 minutes
1616
---
1717

18+
> **Acknowledgment**
19+
>
20+
> This guide is a community contribution. Docker would like to thank
21+
> [Esteban Maya](https://www.linkedin.com/in/esteban-x64/) and [Igor Aleksandrov](https://www.linkedin.com/in/igor-aleksandrov/) for their contribution
22+
> to this guide.
23+
1824
The Python language-specific guide teaches you how to containerize a Python application using Docker. In this guide, you’ll learn how to:
1925

2026
- Containerize and run a Python application
2127
- Set up a local environment to develop a Python application using containers
28+
- Lint, format, typing and best practices
2229
- Configure a CI/CD pipeline for a containerized Python application using GitHub Actions
2330
- Deploy your containerized Python application locally to Kubernetes to test and debug your deployment
2431

‎content/guides/python/configure-github-actions.md‎

Lines changed: 28 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Automate your builds with GitHub Actions
33
linkTitle: Automate your builds with GitHub Actions
4-
weight: 20
4+
weight: 40
55
keywords: ci/cd, github actions, python, flask
66
description: Learn how to configure CI/CD using GitHub Actions for your Python application.
77
aliases:
@@ -60,6 +60,27 @@ on:
6060
- main
6161

6262
jobs:
63+
lint-test:
64+
runs-on: ubuntu-latest
65+
steps:
66+
- uses: actions/checkout@v4
67+
68+
- name: Set up Python
69+
uses: actions/setup-python@v5
70+
with:
71+
python-version: '3.12'
72+
73+
- name: Install dependencies
74+
run: |
75+
python -m pip install --upgrade pip
76+
pip install -r requirements.txt
77+
78+
- name: Run pre-commit hooks
79+
run: pre-commit run --all-files
80+
81+
- name: Run pyright
82+
run: pyright
83+
6384
build_and_push:
6485
runs-on: ubuntu-latest
6586
steps:
@@ -97,7 +118,11 @@ When the workflow is complete, go to your [repositories on Docker Hub](https://h
97118

98119
## Summary
99120

100-
In this section, you learned how to set up a GitHub Actions workflow for your Python application.
121+
In this section, you learned how to set up a GitHub Actions workflow for your Python application that includes:
122+
123+
- Running pre-commit hooks for linting and formatting
124+
- Static type checking with Pyright
125+
- Building and pushing Docker images
101126

102127
Related information:
103128

@@ -107,5 +132,5 @@ Related information:
107132

108133
## Next steps
109134

110-
In the next section, you'll learn how you can develop your application using containers.
135+
In the next section, you'll learn how you can develop locally using kubernetes.
111136

‎content/guides/python/containerize.md‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,7 @@ This utility will walk you through creating the following files with sensible de
5858
Let's get started!
5959

6060
? What application platform does your project use? Python
61-
? What version of Python do you want to use? 3.11.4
61+
? What version of Python do you want to use? 3.12
6262
? What port do you want your app to listen on? 8000
6363
? What is the command to run your app? python3 -m uvicorn app:app --host=0.0.0.0 --port=8000
6464
```
@@ -139,8 +139,8 @@ Create a file named `Dockerfile` with the following contents.
139139

140140
# Want to help us make this template better? Share your feedback here: https://forms.gle/ybq9Krt8jtBL3iCk7
141141

142-
ARG PYTHON_VERSION=3.11.4
143-
FROM python:${PYTHON_VERSION}-slim AS base
142+
ARG PYTHON_VERSION=3.12
143+
FROM python:${PYTHON_VERSION}-slim
144144

145145
# Prevents Python from writing pyc files.
146146
ENV PYTHONDONTWRITEBYTECODE=1
@@ -181,7 +181,7 @@ COPY . .
181181
EXPOSE 8000
182182

183183
# Run the application.
184-
CMD python3 -m uvicorn app:app --host=0.0.0.0 --port=8000
184+
CMD ["python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8000"]
185185
```
186186

187187
Create a file named `compose.yaml` with the following contents.
@@ -375,6 +375,4 @@ Related information:
375375

376376
## Next steps
377377

378-
In the next section, you'll take a look at how to set up a CI pipeline using GitHub Actions.
379-
380-
378+
In the next section, you'll take a look at how to set up a local development environment using Docker containers.

‎content/guides/python/develop.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Use containers for Python development
33
linkTitle: Develop your app
4-
weight: 40
4+
weight: 15
55
keywords: python, local, development
66
description: Learn how to develop your Python application locally.
77
aliases:
@@ -51,7 +51,7 @@ You'll need to clone a new repository to get a sample application that includes
5151
Let's get started!
5252

5353
? What application platform does your project use? Python
54-
? What version of Python do you want to use? 3.11.4
54+
? What version of Python do you want to use? 3.12
5555
? What port do you want your app to listen on? 8001
5656
? What is the command to run your app? python3 -m uvicorn app:app --host=0.0.0.0 --port=8001
5757
```
@@ -132,8 +132,8 @@ You'll need to clone a new repository to get a sample application that includes
132132

133133
# Want to help us make this template better? Share your feedback here: https:// forms.gle/ybq9Krt8jtBL3iCk7
134134

135-
ARG PYTHON_VERSION=3.11.4
136-
FROM python:${PYTHON_VERSION}-slim as base
135+
ARG PYTHON_VERSION=3.12
136+
FROM python:${PYTHON_VERSION}-slim
137137

138138
# Prevents Python from writing pyc files.
139139
ENV PYTHONDONTWRITEBYTECODE=1
@@ -174,7 +174,7 @@ You'll need to clone a new repository to get a sample application that includes
174174
EXPOSE 8001
175175

176176
# Run the application.
177-
CMD python3 -m uvicorn app:app --host=0.0.0.0 --port=8001
177+
CMD ["python3", "-m", "uvicorn", "app:app", "--host=0.0.0.0", "--port=8001"]
178178
```
179179

180180
Create a file named `compose.yaml` with the following contents.
@@ -569,4 +569,4 @@ Related information:
569569

570570
## Next steps
571571

572-
In the next section, you'll learn how you can locally test and debug your workloads on Kubernetes before deploying.
572+
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.

‎content/guides/python/lint-format-typing.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
---
2+
title: Linting, formatting, and type checking for Python
3+
linkTitle: Linting and typing
4+
weight: 25
5+
keywords: Python, linting, formatting, type checking, ruff, pyright
6+
description: Learn how to set up linting, formatting and type checking for your Python application.
7+
aliases:
8+
- /language/python/lint-format-typing/
9+
---
10+
11+
## Prerequisites
12+
13+
Complete [Develop your app](develop.md).
14+
15+
## Overview
16+
17+
In this section, you'll learn how to set up code quality tools for your Python application. This includes:
18+
19+
- Linting and formatting with Ruff
20+
- Static type checking with Pyright
21+
- Automating checks with pre-commit hooks
22+
23+
## Linting and formatting with Ruff
24+
25+
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.
26+
27+
Create a `pyproject.toml` file:
28+
29+
```toml
30+
[tool.ruff]
31+
target-version = "py312"
32+
33+
[tool.ruff.lint]
34+
select = [
35+
"E", # pycodestyle errors
36+
"W", # pycodestyle warnings
37+
"F", # pyflakes
38+
"I", # isort
39+
"B", # flake8-bugbear
40+
"C4", # flake8-comprehensions
41+
"UP", # pyupgrade
42+
"ARG001", # unused arguments in functions
43+
]
44+
ignore = [
45+
"E501", # line too long, handled by black
46+
"B008", # do not perform function calls in argument defaults
47+
"W191", # indentation contains tabs
48+
"B904", # Allow raising exceptions without from e, for HTTPException
49+
]
50+
```
51+
52+
### Using Ruff
53+
54+
Run these commands to check and format your code:
55+
56+
```bash
57+
# Check for errors
58+
ruff check .
59+
60+
# Automatically fix fixable errors
61+
ruff check --fix .
62+
63+
# Format code
64+
ruff format .
65+
```
66+
67+
## Type checking with Pyright
68+
69+
Pyright is a fast static type checker for Python that works well with modern Python features.
70+
71+
Add `Pyright` configuration in `pyproject.toml`:
72+
73+
```toml
74+
[tool.pyright]
75+
typeCheckingMode = "strict"
76+
pythonVersion = "3.12"
77+
exclude = [".venv"]
78+
```
79+
80+
### Running Pyright
81+
82+
To check your code for type errors:
83+
84+
```bash
85+
pyright
86+
```
87+
88+
## Setting up pre-commit hooks
89+
90+
Pre-commit hooks automatically run checks before each commit. The following `.pre-commit-config.yaml` snippet sets up Ruff:
91+
92+
```yaml
93+
https: https://github.com/charliermarsh/ruff-pre-commit
94+
rev: v0.2.2
95+
hooks:
96+
- id: ruff
97+
args: [--fix]
98+
- id: ruff-format
99+
```
100+
101+
To install and use:
102+
103+
```bash
104+
pre-commit install
105+
git commit -m "Test commit" # Automatically runs checks
106+
```
107+
108+
## Summary
109+
110+
In this section, you learned how to:
111+
112+
- Configure and use Ruff for linting and formatting
113+
- Set up Pyright for static type checking
114+
- Automate checks with pre-commit hooks
115+
116+
These tools help maintain code quality and catch errors early in development.
117+
118+
## Next steps
119+
120+
- [Configure GitHub Actions](configure-github-actions.md) to run these checks automatically
121+
- Customize linting rules to match your team's style preferences
122+
- Explore advanced type checking features

0 commit comments

Comments
 (0)