| Category | File / Directory | Purpose |
|---|---|---|
| Configuration & Build | .gitignore |
Specifies files/folders Git should ignore. |
| Configuration & Build | .pre-commit-config.yaml |
Defines linting/formatting hooks for pre-commit. |
| Configuration & Build | .pylintrc |
Config file for pylint (style/linting rules). |
| Configuration & Build | tox.ini |
Automates testing across multiple environments. |
| Configuration & Build | pyproject.toml |
Defines packaging, dependencies, and build system. |
| Configuration & Build | Dockerfile |
Provides containerized build/runtime environment. |
| Configuration & Build | autoformat.sh |
Shell script for automated code formatting. |
| Documentation & Metadata | README.md |
Project overview, installation, and usage guide. |
| Documentation & Metadata | LICENSE |
Specifies the project’s license (Apache-2.0). |
| Documentation & Metadata | CONTRIBUTING.md |
Guidelines for contributing to the project. |
| Documentation & Metadata | COMMUNITY_PROVIDERS.md |
Documents supported community providers. |
| Documentation & Metadata | CITATION.cff |
Provides citation metadata for academic use. |
| Testing | tests/ |
Contains test suites for verification and validation. |
| CI/CD & Repo Management | .github/ |
Stores GitHub Actions workflows and repo-specific templates. |
Here’s the clean, no-nonsense breakdown.
Setuptools vs. Poetry
Dimension setuptools Poetry What it is Build backend and packager. Classic, ubiquitous. Project manager: dependencies, virtualenvs, builds, publishing. Uses its own build backend (poetry-core). Primary file pyproject.toml (modern) or legacy setup.py/setup.cfg. pyproject.toml as single source of truth. Dependency management Typically via requirements.txt or pip-tools. No native resolver. Built-in resolver: poetry add X. Groups (dev/test/docs). Lockfile No native lockfile (use pip-tools to pin). poetry.lock for reproducible installs. Virtualenvs Managed externally (venv/conda/pipenv). Managed for you (can disable). Build & publish python -m build; twine upload. poetry build; poetry publish. Config for tools Scattered: tox.ini, .pylintrc, etc. Some can live in pyproject.toml. Often centralized in pyproject.toml, but can still mix. Monorepo/multi-project Flexible, but manual wiring. Possible; smoother with workspaces (still maturing). Ecosystem maturity Very mature, minimal magic, everywhere supported. Opinionated workflow, faster onboarding, strong DX. When it shines You want maximum control, standard tools, custom builds, or existing CI patterns. You want one tool to handle deps + envs + publishing with reproducibility out of the box.
⸻
Mental model • setuptools = “Bring your own tools.” It builds your package; you assemble the rest (envs, lock, publish) with separate utilities. • Poetry = “Batteries included.” It decides conventions and smooths the whole lifecycle.
⸻
Minimal examples
setuptools (modern pyproject.toml)
[build-system] requires = ["setuptools>=61", "wheel"] build-backend = "setuptools.build_meta"
[project] name = "mypkg" version = "0.1.0" dependencies = ["requests>=2"]
Poetry
[build-system] requires = ["poetry-core>=1.0.0"] build-backend = "poetry.core.masonry.api"
[tool.poetry] name = "mypkg" version = "0.1.0" authors = ["You [email protected]"]
[tool.poetry.dependencies] python = "^3.11" requests = "^2.32"
curl -sSL https://install.python-poetry.org | python -
⸻
Pragmatic guidance • Choose setuptools if you: • Integrate with existing corporate CI or distro packaging. • Need custom build steps, extensions, or nonstandard layouts. • Prefer explicit control with pip-tools/tox. • Choose Poetry if you: • Want fast, reproducible setup for apps/libs. • Value a single command surface for add/install/build/publish. • Onboard contributors who may not know Python packaging well.
⸻
Common hybrid • Use setuptools + pip-tools (pip-compile) for deterministic pins. • Keep tool configs in pyproject.toml where possible; leave heavy test matrices in tox.ini.
If you share your repo’s pyproject.toml snippet, I’ll label exactly which model it uses and suggest the leanest workflow for it.