diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index cbccd4a51b2..8cf40e78013 100644 --- 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 index 221c540f1ed..6489a6d67d1 100644 --- 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 index a513e930674..45f969cd57a 100644 --- 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 index daff59ba69e..f53be97a2db 100644 --- 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 index 24c73832b79..7a8b5b2bd84 100644 --- 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 new file mode 100644 index 00000000000..a96aead3530 --- /dev/null +++ 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 \ No newline at end of file