Skip to content

Generated Project Structure

This page documents the complete structure of projects generated by this cookiecutter template, explaining the purpose of each file and directory.

Complete Directory Structure

your-project/
├── .github/                    # GitHub-specific files
│   ├── workflows/
│   │   ├── ci.yml             # Continuous Integration workflow
│   │   ├── release.yml        # Release automation workflow
│   │   └── docs.yml           # Documentation deployment (if enabled)
│   ├── dependabot.yml         # Dependency update configuration (if enabled)
│   ├── ISSUE_TEMPLATE/        # Issue templates
│   └── PULL_REQUEST_TEMPLATE.md # PR template
├── .vscode/                   # VS Code configuration (if enabled)
│   ├── settings.json          # Editor settings
│   ├── launch.json            # Debug configurations
│   └── extensions.json        # Recommended extensions
├── src/
│   └── your_project/
│       ├── __init__.py        # Package initialization
│       ├── core.py            # Main functionality
│       ├── cli.py             # Command-line interface (if enabled)
│       ├── exceptions.py      # Custom exceptions
│       └── py.typed           # Type checking marker
├── tests/
│   ├── __init__.py
│   ├── conftest.py            # Shared test fixtures
│   ├── test_core.py           # Core functionality tests
│   ├── test_cli.py            # CLI tests (if enabled)
│   └── integration/           # Integration tests
│       └── test_integration.py
├── docs/                      # Documentation
│   ├── index.md               # Documentation homepage
│   ├── api/                   # API documentation
│   ├── user-guide/            # User guides
│   └── development/           # Development documentation
├── scripts/                   # Development and utility scripts
│   ├── lint.sh               # Linting script
│   ├── test.sh               # Testing script
│   └── release.sh            # Release script
├── .devcontainer/            # Development container (if enabled)
│   ├── devcontainer.json     # Container configuration
│   └── Dockerfile            # Development Dockerfile
├── .gitignore                # Git ignore patterns
├── .gitattributes            # Git attributes
├── .pre-commit-config.yaml   # Pre-commit hooks (if enabled)
├── .ruff.toml               # Ruff configuration
├── .bandit                   # Bandit security scan config (if enabled)
├── pyproject.toml            # Project configuration (PEP 621)
├── README.md                 # Project documentation
├── CHANGELOG.md              # Change log (if enabled)
├── CONTRIBUTING.md           # Contribution guidelines (if enabled)
├── LICENSE                   # License file
├── MANIFEST.in               # Package manifest (if needed)
├── tox.ini                   # Tox configuration (if enabled)
├── noxfile.py               # Nox configuration (if enabled)
├── Dockerfile               # Production container (if enabled)
├── docker-compose.yml       # Docker Compose config (if enabled)
└── mkdocs.yml               # MkDocs configuration (if enabled)

File-by-File Explanation

Root Configuration Files

pyproject.toml

Purpose: Modern Python project configuration (PEP 621) Contains: - Project metadata (name, version, description) - Dependencies and optional dependencies - Build system configuration - Tool configurations (ruff, mypy, pytest, etc.)

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "your-project"
description = "Project description"
readme = "README.md"
# ... more configuration

.gitignore

Purpose: Specifies files Git should ignore Includes: - Python bytecode files (.pyc, pycache) - Virtual environments (venv/, .env) - IDE files (.vscode/, .idea/) - Build artifacts (build/, dist/, .egg-info/) - OS-specific files (.DS_Store, Thumbs.db)

README.md

Purpose: Project overview and quick start guide Sections: - Project description - Installation instructions - Basic usage examples - Links to documentation - Badges showing project status

LICENSE

Purpose: Legal license for the project Options: MIT, Apache-2.0, BSD-3-Clause, GPL-3.0, etc.

Source Code Structure

src/your_project/init.py

Purpose: Package initialization and public API 

"""Your Project - Package description."""

from .core import MainClass, main_function
from .exceptions import YourProjectError

__version__ = "0.1.0"
__all__ = ["MainClass", "main_function", "YourProjectError"]

src/your_project/core.py

Purpose: Main package functionality Contains: - Core classes and functions - Business logic - Primary package features

src/your_project/cli.py (if CLI enabled)

Purpose: Command-line interface Framework options: - Typer (modern, type-based) - Click (mature, decorator-based) - Argparse (standard library)

src/your_project/exceptions.py

Purpose: Custom exception classes 

class YourProjectError(Exception):
    """Base exception for your project."""
    pass

class ValidationError(YourProjectError):
    """Raised when validation fails."""
    pass

src/your_project/py.typed

Purpose: Indicates package supports type checking Content: Empty file that signals to type checkers that this package includes type information

Testing Structure

tests/conftest.py

Purpose: Shared test fixtures and configuration 

import pytest

@pytest.fixture
def sample_data():
    """Provide sample data for tests."""
    return {"key": "value"}

tests/test_core.py

Purpose: Tests for core functionality Structure: - Test classes for each main class - Individual test methods for each function - Parametrized tests for multiple inputs - Error condition testing

tests/integration/

Purpose: Integration and end-to-end tests Contains: Tests that verify multiple components working together

Documentation Structure

docs/index.md (if MkDocs enabled)

Purpose: Documentation homepage Content: - Project overview - Quick start guide - Navigation to other documentation

mkdocs.yml (if MkDocs enabled)

Purpose: MkDocs configuration Contains: - Site metadata - Theme configuration - Navigation structure - Plugin configuration

GitHub Integration

.github/workflows/ci.yml

Purpose: Continuous Integration workflow Features: - Multi-Python version testing - Cross-platform testing (Linux, Windows, macOS) - Code quality checks - Test coverage reporting

name: CI
on: [push, pull_request]
jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        python-version: ["3.9", "3.10", "3.11", "3.12"]
    # ... job steps

.github/dependabot.yml (if enabled)

Purpose: Automated dependency updates Features: - Weekly dependency scans - Automatic pull requests for updates - Security vulnerability alerts

Development Tools Configuration

.pre-commit-config.yaml (if enabled)

Purpose: Pre-commit hook configuration Hooks: - Code formatting (Ruff) - Linting (Ruff) - Type checking (MyPy) - Security scanning (Bandit) - General checks (trailing whitespace, etc.)

tox.ini (if enabled)

Purpose: Multi-environment testing configuration 

[tox]
envlist = py39,py310,py311,py312,lint,type

[testenv]
deps = pytest
commands = pytest {posargs}

[testenv:lint]
deps = ruff
commands = ruff check src tests

noxfile.py (if enabled)

Purpose: Flexible task automation (Python-based alternative to Tox) 

import nox

@nox.session(python=["3.9", "3.10", "3.11", "3.12"])
def tests(session):
    session.install("pytest")
    session.install("-e", ".")
    session.run("pytest")

Container Support

Dockerfile (if enabled)

Purpose: Production container configuration Features: - Multi-stage build - Optimized for production - Security best practices

.devcontainer/ (if enabled)

Purpose: VS Code development container Benefits: - Consistent development environment - Pre-configured tools and extensions - Easy onboarding for contributors

Tool-Specific Files

.bandit (if Bandit enabled)

Purpose: Security scanning configuration Content: Rules to skip, directories to exclude

MANIFEST.in (if needed)

Purpose: Controls which files are included in source distributions 

include README.md
include LICENSE
include CHANGELOG.md
recursive-include src *.py
global-exclude *.pyc

Generated File Patterns

Based on Tool Selection

Tool Generated Files
Ruff .ruff.toml, ruff config in pyproject.toml
MyPy MyPy config in pyproject.toml
pytest tests/ directory, pytest config in pyproject.toml
pre-commit .pre-commit-config.yaml
Bandit .bandit, bandit config in pyproject.toml
GitHub Actions .github/workflows/ci.yml
Dependabot .github/dependabot.yml
MkDocs mkdocs.yml, docs/ directory
Sphinx docs/conf.py, docs/source/ directory
Docker Dockerfile, .dockerignore
Dev Container .devcontainer/devcontainer.json

Based on CLI Choice

CLI Framework Generated Files
Typer Enhanced cli.py with Typer imports
Click Enhanced cli.py with Click decorators
Argparse Basic cli.py with argparse
None No cli.py file

Customization Points

Optional Directories

  • examples/ - Usage examples (if include_examples = true)
  • scripts/ - Development scripts (if include_scripts = true)
  • notebooks/ - Jupyter notebooks (if include_notebooks = true)

Conditional Files

Files are only generated if specific tools are enabled: - Documentation files only if use_mkdocs or use_sphinx is true - CI/CD files only if use_github_actions is true - Security configs only if use_bandit or use_safety is true

Platform-Specific Files

  • .gitattributes - Git line ending configuration
  • Windows-specific entries in .gitignore
  • Cross-platform scripts in scripts/ directory

This structure ensures that your generated project follows Python packaging best practices while remaining flexible enough to adapt to different project needs and team preferences.