Setting Up Python Projects

Project Layout

project/
├── src/appname/
│   ├── __init__.py           # __version__ = "0.1.0"
│   ├── __main__.py           # Entry point
│   ├── constants.py          # Shared constants
│   ├── core/                 # Business logic
│   │   ├── models.py         # Data types (dataclasses)
│   │   ├── manager.py        # Business operations
│   │   └── exceptions.py     # Custom exception hierarchy
│   ├── cli/                  # CLI interface
│   │   ├── commands.py       # Command implementations
│   │   ├── parser.py         # Argument parsing
│   │   └── output.py         # Formatted output helpers
│   ├── ui/                   # Qt GUI (if applicable)
│   │   ├── main_window.py
│   │   ├── dialogs/
│   │   └── widgets/
│   ├── utils/                # Stateless utilities
│   │   ├── paths.py
│   │   └── logging.py
│   ├── wrappers/             # Third-party lib wrappers
│   │   └── some_wrapper.py
│   └── stubs/                # Type stubs for untyped libs
├── tests/
│   ├── unit/
│   ├── integration/
│   ├── fixtures/
│   └── conftest.py
├── scripts/                  # Dev utilities
│   ├── bootstrap.py          # Setup script
│   └── check_type_ignore.py
├── docs/
│   ├── coding_rules.md       # Copy from rules/coding_rules.md
│   └── PHILOSOPHY.md          # Copy from PHILOSOPHY.md
├── shared/                   # Cross-cutting (logging, shortcuts)
├── AGENTS.md                 # Copy from templates/AGENTS.md, customize
├── CLAUDE.md                 # Symlink → AGENTS.md
├── pyproject.toml            # Copy from templates/pyproject.toml, customize
├── .pre-commit-config.yaml   # Copy from templates/pre-commit-config.yaml
├── .gitignore                # Copy from templates/gitignore
└── .vscode/
    ├── settings.json         # Copy from templates/vscode_settings.json
    └── extensions.json       # Copy from templates/vscode_extensions.json

Setup Checklist

1. Create directory structure:

   mkdir -p src/APPNAME tests/unit tests/integration tests/fixtures scripts docs .vscode

2. Copy template and reference files:

   • templates/pyproject.toml

     →

     pyproject.toml

     (update

     [project]

     section)

   • templates/AGENTS.md

     →

     AGENTS.md

     (fill TODO sections)

   • templates/pre-commit-config.yaml

     →

     .pre-commit-config.yaml

   • templates/gitignore

     →

     .gitignore

   • templates/vscode_settings.json

     →

     .vscode/settings.json

   • templates/vscode_extensions.json

     →

     .vscode/extensions.json

   • rules/coding_rules.md

     →

     docs/coding_rules.md

   • PHILOSOPHY.md

     →

     docs/PHILOSOPHY.md

   • Create symlink:

     ln -s AGENTS.md CLAUDE.md

3. Create entry points:
   python

   # src/APPNAME/__init__.py
   __version__ = "0.1.0"
   
   # src/APPNAME/__main__.py
   import sys
   
   def main() -> int:
       if len(sys.argv) > 1:
           return cli_main()  # CLI mode
       return gui_main()      # GUI mode (if applicable)
   
   if __name__ == "__main__":
       sys.exit(main())

4. Create initial test:
   python

   # tests/test_main.py
   from APPNAME.__main__ import main
   
   def test_main_runs(capsys: pytest.CaptureFixture[str]) -> None:
       assert main() == 0

5. Initialize environment:
   bash

   git init
   uv sync --all-extras --group dev
   uv run pre-commit install
   uv run poe lint_full
   uv run poe test

6. Verify everything works:

   • uv run poe app

     runs the application

   • uv run poe lint_full

     passes with 0 errors

   • uv run poe test

     passes

Bootstrap Script

# scripts/bootstrap.py
"""Set up development environment."""
import subprocess

def main() -> None:
    subprocess.run(["uv", "sync", "--all-extras", "--group", "dev"], check=True)
    subprocess.run(["uv", "run", "pre-commit", "install"], check=True)
    print("Development environment ready.")

if __name__ == "__main__":
    main()

Adapt to Tech Stack & Domain

docs/PHILOSOPHY.md

What to adapt

cli/

ui/

wrappers/

shared/

pipelines/

schemas/

extractors/

routes/

middleware/

repositories/

type: ignore

Research before building

1. Research the domain's conventions — look up how well-maintained projects in the same space are structured
2. Check library compatibility — verify libraries work together and with basedpyright strict mode (some libraries have poor type stubs; plan wrappers early)
3. Identify domain-specific tooling — some domains have their own linters, formatters, or validation tools that complement the base toolchain
4. Check for basedpyright known issues — some libraries (numpy, pandas, SQLAlchemy) need specific configuration or stub packages to work cleanly in strict mode

Quick customization checklist

• Directory layout matches the domain, not the generic template
• Dependencies are domain-appropriate (researched, not guessed)
• AGENTS.md describes this project, not a generic Python project
• coding_rules.md has domain-specific additions if needed
• Test structure reflects what matters most for this project
• basedpyright config accounts for domain-specific library quirks