github-copilot-instructions python.instructions.md

Python Coding Conventions & Style Guide

0. Overview

This document outlines the coding conventions and style guidelines for Python projects. It covers Python version policies, project structure, type hinting, coding practices, testing, and practical examples.

1. Python Version Policy

• Minimum Supported Version: Python 3.10
• Recommended Version: Python 3.11 or later
• Deprecated Versions: Python 3.9 and earlier
• Unsupported Versions: Python 2.x
• MUST NOT use deprecated or obsolete Python features.

---

2. Default Coding Style: Google Python Style Guide

• Follow the Google Python Style Guide as the baseline for coding style.
• If there are conflicts between Google Style and Other Guidelines, prefer Google Style unless there is a compelling reason not to.

---

3. Project Structure & Packaging

Project Structure

• PEP 420: Use implicit namespace packages for multi-directory packages.

Project Packaging

• PEP 517/518: Use pyproject.toml for build system configuration.
  • Use uv and hatchling for building and packaging.
• PEP 621: Use pyproject.toml for project metadata (name, version, description, authors, license, dependencies).
• PEP 561: For libraries, include type information by adding a py.typed file in the package directory.

Single application Example

For a single application, the project name should be the same as the package name. For example, a project named myapp would have the following structure:

myapp/                       # Project root, `myapp` is the project name
├── src/                     # Source code directory
│   └── myapp/               # Package namespace from project name
│       ├── __init__.py      # Package initializer
│       ├── main.py          # Main application module
│       └── py.typed         # Marker file for type information
├── tests/                   # Tests directory
│   ├── __init__.py          # Test package initializer
│   └── test_main.py         # Example test module
└── pyproject.toml           # Build system and project metadata