Standard Python Project Structure and Code Style Guidelines (PEP 8)

In Python development, a well‑structured project and consistent code style improve readability and team efficiency. A chaotic layout can cause maintenance difficulties, collaboration obstacles, and deployment problems.

1. Python Project Standard Structure

A typical Python project follows this layout:

my_project/
│
├── docs/            # documentation (e.g., Sphinx)
├── tests/           # unit and integration tests
│   ├── __init__.py
│   └── test_module.py
├── src/             # source code (core logic)
│   ├── __init__.py
│   ├── module1/
│   │   ├── __init__.py
│   │   └── core.py
│   └── module2/
│       ├── __init__.py
│       └── utils.py
├── scripts/         # executable scripts (e.g., CLI tools)
│   └── run.py
├── requirements.txt # pip dependencies
├── setup.py         # packaging configuration (setuptools)
├── .gitignore       # files to ignore in Git
├── README.md        # project description
└── LICENSE          # open‑source license

Key Files

__init__.py : makes a directory a Python package (optional for Python 3.3+ but recommended).

requirements.txt : lists dependencies; install with pip install -r requirements.txt .

setup.py : defines metadata; install locally with pip install . .

.gitignore : prevents committing temporary files such as __pycache__/ .

2. Python Code Conventions (PEP 8)

Follow the official style guide, which includes naming conventions and formatting rules.

2.1 Naming Conventions

Type

Convention

Example

Module name

lowercase_with_underscores

data_loader.py

Class name

CapWords

ClassName

Function/variable

lowercase_with_underscores

def calculate_sum()

Constant

UPPERCASE_WITH_UNDERSCORES

MAX_LIMIT = 100

2.2 Formatting

Indentation: 4 spaces (no tabs).

Line length: ≤ 79 characters (comments/docstrings ≤ 72).

Spaces: around operators ( x = y + 1 ), after commas ( [1, 2, 3] ), and between function arguments ( def func(a, b, c) ).

2.3 Import Order

# 1. Standard library
import os
import sys

# 2. Third‑party libraries
import numpy as np
from flask import Flask

# 3. Local modules
from .utils import helper

3. Automated Code‑Check Tools

Manual style checks are tedious; use these tools:

3.1 Flake8 (PEP 8 checking)

pip install flake8
flake8 src/  # check code against PEP 8

3.2 Black (auto‑formatting)

pip install black
black src/  # automatically format code

3.3 isort (import sorting)

pip install isort
isort src/  # reorder imports automatically

4. Hands‑On: Build a Conforming Project

4.1 Initialise the Structure

mkdir my_project && cd my_project
mkdir -p src/module1 tests docs scripts
touch src/__init__.py src/module1/core.py
touch tests/test_core.py README.md requirements.txt

4.2 Write PEP 8‑Compliant Code

File src/module1/core.py :

def calculate_sum(a: int, b: int) -> int:
    """Calculate the sum of two integers (PEP 8‑compliant function)."""
    return a + b

File tests/test_core.py :

import unittest
from src.module1.core import calculate_sum

class TestCore(unittest.TestCase):
    def test_sum(self):
        self.assertEqual(calculate_sum(2, 3), 5)

if __name__ == "__main__":
    unittest.main()

4.3 Run Tests & Code Checks

python -m pytest tests/   # run tests
flake8 src/                # lint code
black src/                 # format code

5. Summary

A standard project layout makes code easier to maintain.

PEP 8 conventions improve readability and reduce collaboration friction.

Automation tools (Flake8, Black, isort) help keep code consistent.