How to Structure a Python Project: Best Practices and Example

To structure a Python project, organize your code inside a main package folder with an __init__.py file, include a setup.py or pyproject.toml for packaging, and separate tests in a tests/ folder. Use folders like docs/ for documentation and scripts/ for helper scripts to keep your project clean and maintainable.

Syntax

A typical Python project structure includes these parts:

• project_name/: Main folder containing your package code.
• project_name/__init__.py: Marks the folder as a Python package.
• setup.py or pyproject.toml: Defines how to install your package.
• tests/: Folder for test code.
• docs/: Documentation files.
• scripts/: Helper scripts for tasks like setup or data processing.
• README.md: Project overview and instructions.
• .gitignore: Files to ignore in version control.

plaintext

project_name/
├── project_name/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── tests/
│   ├── test_module1.py
│   └── test_module2.py
├── docs/
│   └── usage.md
├── scripts/
│   └── setup_db.py
├── setup.py
├── README.md
└── .gitignore

Example

This example shows a simple Python project with a package, a test, and a setup file to install the package.

python

# project_name/project_name/__init__.py

def greet(name):
    return f"Hello, {name}!"


# project_name/tests/test_greet.py

import unittest
from project_name import greet

class TestGreet(unittest.TestCase):
    def test_greet(self):
        self.assertEqual(greet('Alice'), 'Hello, Alice!')


# project_name/setup.py

from setuptools import setup, find_packages

setup(
    name='project_name',
    version='0.1',
    packages=find_packages(),
    description='A simple greeting package',
    author='Your Name',
)


# To run tests, use:
# python -m unittest discover tests

# To install package locally, use:
# pip install -e .

Output

Ran 1 test in 0.001s

OK

Common Pitfalls

Common mistakes when structuring Python projects include:

• Not including an __init__.py file, so Python does not recognize the folder as a package.
• Putting tests inside the main package folder instead of a separate tests/ folder.
• Missing a setup.py or pyproject.toml, making installation and distribution harder.
• Ignoring .gitignore, which can clutter version control with unwanted files.

plaintext

# Wrong: No __init__.py
project_name/
└── module1.py

# Right: Add __init__.py
project_name/
├── __init__.py
└── module1.py

Quick Reference

Keep these tips in mind:

• Use a clear folder structure separating code, tests, docs, and scripts.
• Include __init__.py to mark packages.
• Use setup.py or pyproject.toml for packaging.
• Write a README.md to explain your project.
• Use .gitignore to keep your repo clean.

Key Takeaways

Organize your Python project with separate folders for code, tests, docs, and scripts.

Always include an __init__.py file to make Python treat folders as packages.

Use setup.py or pyproject.toml to enable easy installation and distribution.

Keep tests outside the main package in a dedicated tests folder.

Maintain a README.md and .gitignore for clarity and clean version control.