🎓 A1Learner
🔍

Python Project Structure

A layout is the way a project's files and folders are arranged. Two standard layouts are the flat layout and the src layout.

The flat layout

The package sits at the top of the project. This is a file tree, not code.

textstats-project/
    textstats/
        __init__.py
    tests/
        test_core.py
    README.md

The src layout

Here the package moves down into a src folder. The tests stay outside it.

textstats-project/
    src/
        textstats/
            __init__.py
    tests/
        test_core.py
    README.md

The ID card (config)

This config file is a pyproject.toml. The [build-system] table names the build tool, and the [project] table names the project and the Python it needs.

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "textstats"
version = "0.1.0"
description = "Count words and sentences in text."
requires-python = ">=3.10"

The front door

A README starts with the project's name. One plain line says what it does.

# textstats

Count words and sentences in any text.

Example

from pathlib import Path

root = Path("textstats-project")
files = {
    "pyproject.toml": "[project]\nname = \"textstats\"\n",
    "README.md": "# textstats\n",
    "LICENSE": "MIT\n",
    "src/textstats/__init__.py": "",
    "src/textstats/core.py": "# word counting lives here\n",
    "tests/test_core.py": "# tests live here\n",
}

for name, text in files.items():
    path = root / name
    path.parent.mkdir(parents=True, exist_ok=True)
    path.write_text(text)

for path in sorted(root.rglob("*")):
    label = path.relative_to(root).as_posix()
    if path.is_dir():
        label += "/"
    print(label)

Key points

  • Layout: the way a project's files and folders are arranged
  • Flat layout: the package folder sits at the top, next to the tests
  • Src layout: the package folder sits inside a src folder
  • Tests live outside the package, usually in their own tests folder
  • pyproject.toml: the project's ID card.
  • It names the project and tells tools how to build it
  • README.md: the front door.
  • It says what the project does and how to use it
  • LICENSE: the file that says what other people may do with your code

In this example, the program builds the whole textstats project, file by file. The files dict maps each file's path to its small contents. The first loop makes each parent folder, then writes the file. The project uses the src layout, so the package lives under src/textstats. The tests sit in their own tests folder. The second loop walks the finished tree with rglob. sorted puts every path in a fixed order. Each path prints relative to the project root, and folders get a trailing slash.

Note

With a flat layout, Python can import your package straight from the project folder, even before it is installed.

The src layout stops that accident, so your tests check the installed package.

Try it Yourself

Edit the code, then press Run.

Running is simulated · Python Playground

Exercise

A teammate opens your project for the first time. Which file names the project, its version, and the Python version it needs?