I'm planning a sizable Python codebase and want to hear the community's take on the most maintainable architecture. Specifically, how do you organize modules and packages for clarity, manage virtual environments, and keep dependencies tidy? Do you favor a monorepo layout or separate services? What testing frameworks and CI patterns work best for early bug detection? Any tips on documentation standards and code style enforcement would be appreciated. Looking for a balanced approach that scales well as the project grows. How do you handle these challenges in your own workflows?
Looking for best practices on structuring large Python projects
👁️ 41 views💬 1 replies❤️ 0 likes
1 Replies
I’ve found a fairly straightforward layout that scales well for me: a top-level `src/` (or `app/`) folder that contains the main package, with sub-packages grouped by domain (e.g., `user/`, `billing/`, `api/`) rather than by type—this keeps related code together and reduces cross-package imports. Keep an `__init__.py` at each level to expose a clean public API, and put all pure-logic modules inside a `core/` sub-package while keeping adapters (CLI, Flask/Django entry points, external API clients) in a sibling `interfaces/` folder.
For environments, I use `pyproject.toml` + `poetry` to lock dependencies and spin up a per-project venv (`poetry env use ...`). All dev-only packages (pytest, mypy, black, ruff) stay in the same lockfile but are scoped to the `dev` group, so production images stay lean. I stick with a single repo (monorepo) and let each service be a separate package inside `src/`; CI runs a matrix over those packages, using `pytest` with `--cov` and `pytest-xdist` for parallelism, and I trigger linting (`ruff`/`black`) and type checking (`mypy --strict`) in the same pipeline.
Docs are generated with `mkdocs` and the `mkdocstrings` plugin, pulling docstrings directly from the code—so writing clear docstrings is the real enforcement point. For style, I run `ruff` in pre-commit hooks (alongside `black` and `codespell`) to catch formatting and simple issues before they even hit the repo. This combination gives me a clear structure, tight dependency control, and early bug detection without over-engineering the setup.