Conventions and workflows for this Python project using Black, Pyright (strict), and pytest, with a feature-first layout
Help the agent work within this project in a way that respects its structure, typing rules, and tooling, so the project stays clean and maintainable.
PACKAGE_NAMEsrc/PACKAGE_NAMEsrc/PACKAGE_NAME/feat1/src/PACKAGE_NAME/feat2/poethepoet tasks under [tool.poe.tasks]src/PACKAGE_NAME/<feature_name>/.Use a feature-first approach:
src/PACKAGE_NAME/<feature_name>/.src/PACKAGE_NAME/feature/feature.pysrc/PACKAGE_NAME/feature/feature_test.pyExample of a feature structure
src/PACKAGE_NAME/feature/
main.pymain_test.pytypes.py (optional, may contain additional types used in the feature)api/
entity_api.py (e.g fetching an endpoint)models/
entity.py (e.g. Pydantic models)entity_test.py (may contain or import mocks to test the model)services/
entity_service.pyentity_service_test.pyDo not create a separate top-level tests folder.
Keep module and test names descriptive and consistent.
utilsutils
web/
parser.pyparser_test.pywebdriver.pywebdriver_test.pydict, list, tuple, set.dict[str, str], list[int], tuple[str, int], etc.None or if the function has sound typing and is well-named.isinstance checks) over # type: ignore.# type: ignore as a last resort, with a short comment explaining why.types-… distributions) when available.src/typings for the used parts of the API.if __name__ == "__main__": pattern.main()) inside a module.[project.scripts] so it becomes a CLI entrypoint.[tool.poe.tasks] with an appropriate name.feature.py → feature_test.py in the same feature directory.test_my_feature() when testing my_feature() in feature.py.src, matching *_test.py.When proposing changes, the agent should keep these commands in mind:
uv run poe test → run pytest tests.uv run poe lint → run Black in check mode.uv run poe lint-fix → format code with Black.uv run poe typecheck → run Pyright on ./src.