I had the experience of upgrading Python in the projects from 3.8 to 3.12 in one step, and I realized that keeping the Python versions up to date is just as critical as keeping the dependencies up to date. Maintenance should not be a separate task, it should be part of all the other tasks. If you can check and update package versions in a timely manner, you don’t have to tell anyone that it’s going to hold up your business in the future.

Of course, there are exceptions to this rule. Suppose you need NumPy for completing a task, you also noticed that the required numbering types1 are not defined in the version what you used in a project. It’s a good time to make the major update in NumPy dependency, right? On the other side, Python version of the project prevents you to update the package. Also, if you drop the old Python version support from the projects, you see that some web services will not work because of version mismatching or your some teammates are still working with the older version of Python and you don’t want to break their development environments without letting them know. I can think of so many example scenarios like this one.

I suggest you to prepare a guideline document and start by convincing your teammates to comply with this document. And in the Acceptance Criteria section of the tasks, there will be a new secret clause like checking code coverage in the unit tests: Guideline document compliance will be reviewed.

The guideline should include the following sections:

  1. Introduction about the document. Also share the preferred Python version and distribution.

  2. Pre-requirements for the development environment.

  3. Development in the existing projects. This section should include the repository access, environment setup, task management, and CI/CD access.

  4. Starting a new project. This section should include the template repositories and how to create a new project.

  5. Style guide. This section should include the code style, docstrings, imports, type hints, testing, and documentation.

  6. History. This section should include the date, version, and description of the changes of the guideline document.

  7. Sources. This section should include the sources of the guideline document.

I asked Claude AI to generate a template for the guideline. It turned out to be a pretty good example, almost perfect. Copy this template and modify it according to your needs. You can also use it as a starting point and add more sections if you need.

Python Project Development Guide

This document provides guidelines to maintain technical stack consistency across Python projects within our organization. Following these standards ensures all developers can easily work on different projects, reduces onboarding time, and improves code quality and maintainability.

Python DistributionCPython is the standard implementation.
PyPy is supported for performance-critical applications.
Supported Python VersionsMinimum: v3.10
Maximum: v3.13
Default: v3.12
Package Manageruv (v0.6.0+)
Minimum Supported DependenciesDependabot is mandatory for all our projects. We also follow SPEC 0.

Pre-Requirements

Before starting development on any project, ensure you have the following tools installed:

  • pipx: For installing and running Python applications in isolated environments.
  • uv: Fast Python package installer and resolver.
  • pre-commit: Framework for managing git hooks.
  • AWS CLI: For accessing CodeArtifact and other AWS resources.

You can install all the required tools using pipx:

brew install pipx
pipx install uv pre-commit awscli

Development in the Existing Projects

  1. Repository Access:

    • Clone the repository using: git clone <repository-url>
    • Configure AWS credentials for CodeArtifact access: aws configure

  2. Environment Setup:

    # Install the required Python version
uv python install 3.12
uv pin 3.12  # if there's no `.python-version` file

# Create a virtual environment
uv sync

# Test the environment
uv run main.py

# Initialize pre-commit hooks
pre-commit install

  3. Task Management:

    • All projects use GitHub Issues for task tracking
    • Pull requests require a linked issue and at least one reviewer approval
    • Commit messages should follow Conventional Commits format

  4. CI/CD Access:

    • CI/CD pipelines run on GitHub Actions
    • Pipeline configurations are stored in .github/workflows/
    • AWS deployment credentials are managed via GitHub Secrets

Starting a New Project

When creating a new project, use one of our template repositories2:

To create a new project:

  1. Navigate to the template repository on GitHub
  2. Click “Use this template” > “Create a new repository”
  3. Follow the setup instructions in the generated README.md
  4. Update the project metadata in pyproject.toml
  5. Commit and push your initial changes

Style Guide

Our code style is enforced through pre-commit hooks. All projects should include the following .pre-commit-config.yaml:

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: "v4.3.0"
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-toml
      - id: check-added-large-files
      - id: check-docstring-first

  - repo: https://github.com/Lucas-C/pre-commit-hooks
    rev: "v1.3.1"
    hooks:
      - id: forbid-crlf
      - id: remove-crlf

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: "v0.982"
    hooks:
      - id: mypy
        args:
          - --strict
          - --ignore-missing-imports
        additional_dependencies:
          - types-click
          - types-python-dateutil
        exclude: ^tests/

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: "v0.11.0"
    hooks:
      - id: ruff
        args: [ --fix ]
      - id: ruff-format

Additional style guidelines:

  1. Docstrings: Use Google-style docstrings
  2. Imports: Group imports in the following order: standard library, third-party packages, local modules
  3. Type Hints: All code should use type hints
  4. Testing: Minimum 80% code coverage required
  5. Documentation: All public APIs must have documentation

History

DateVersionDescription
2025-03-301.0.0Initial document creation

Sources

Our guidelines are based on the following resources:

  1. np.int is deprecated ↩︎

  2. GitHub Template Repository ↩︎