https://github.com/sglbl/sg_project_template

  1. Data classes | Everything must be object-oriented
  2. Input data | Read everything at the beginning
  3. Decide to file to use: json, csv or excel. If csv, reach a consensus about delimiter
  4. Using lowercase names for everything when we read from excel / csv
  5. Sheet column names: English/Spanish
  6. Date format: Use the same date format
  7. Try to draw a graph to see the relation between different attributes of the project
  8. If you need a folder on github, add .gitkeep. And put the right files to .gitignore.

image.png

1. Project mode: application mode (not package mode)

The template /Users/sglbl/codes/sg_project_template/src/ is application mode — a flat folder of modules, NOT an installable package.

Package mode ❌ (we tried, was wrong) Application mode ✅
Layout <project>/my_pkg/ with __init__.py <project>/src/ with no same-named subfolder
pyproject.toml Has [build-system], [project.scripts], console-script entry Has only [project].dependencies + [dependency-groups].dev, no build-system
Run command prom-export ... (after pip install) python -m src.main ... (or python src/main.py ...)
Console script Yes, via [project.scripts] No
Files at root requirements.txt, requirements-dev.txt Just pyproject.toml, uv.lock, README.md
Installation step uv sync then binary works uv sync only sets up the .venv; you still run via python -m

If you ever say "app mode" or "application mode" or reference the template, I mean this. Do NOT propose a wheel, do NOT add [project.scripts], do NOT create requirements.txt.

2. Directory layout

<project>/
├── pyproject.toml          # dev tools only (no [build-system])
├── uv.lock
├── README.md
├── .env                    # canonical config source
├── tests/
│   ├── conftest.py         # adds project root to sys.path
│   └── unit/
├── examples/
└── src/                    # NO __init__.py here, no `src/<pkgname>/`
    ├── main.py             # entry point
    ├── __main__.py         # `python -m src` → calls main
    ├── version.py          # `__version__ = "..."` (NOT __version__.py)
    ├── config.py
    ├── application/        # business logic, no __init__.py
    ├── domain/             # data shapes, no __init__.py
    ├── infra/              # external I/O, no __init__.py
    └── presentation/       # CLI, no __init__.py

Rule: src/ is a namespace package. NO __init__.py files anywhere. Not at src/, not at subfolders. Modern Python (3.3+) supports this and the template uses this pattern.