Add explanation of standard project structure (#8713) #10680
Conversation
Reviewer's guide (collapsed on small PRs)Reviewer's GuideDocuments Poetry’s expected “standard project structure” in the pyproject configuration docs, clarifying when packages can be auto-detected vs. when [tool.poetry.packages] must be explicitly configured. Flow diagram for Poetry package auto-detection vs explicit configurationflowchart TD
A[Start_project_configuration] --> B[Project_matches_standard_structure]
B -->|Yes| C[Poetry_auto_detects_main_package]
B -->|No| D[Manually_configure_tool_poetry_packages]
C --> E[No_need_to_list_packages_in_tool_poetry_packages]
D --> F[Explicitly_list_all_packages_to_include]
E --> G[Build_distribution]
F --> G[Build_distribution]
G --> H[Verify_included_packages]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- The
bash code block for the directory tree isn’t closed before the explanatory sentences and Hugo note/warning shortcodes, so those lines will render as part of the code block instead of normal text and shortcodes—add a closingafter the tree and then keep the prose and shortcodes outside. - Consider adding a blank line between the directory tree code block and the following explanatory sentences to match the surrounding markdown style and improve readability.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The ```bash code block for the directory tree isn’t closed before the explanatory sentences and Hugo note/warning shortcodes, so those lines will render as part of the code block instead of normal text and shortcodes—add a closing ``` after the tree and then keep the prose and shortcodes outside.
- Consider adding a blank line between the directory tree code block and the following explanatory sentences to match the surrounding markdown style and improve readability.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
|
Added the snippet detailing the Standard Project Structure in the [tool.poetry.packages] section. |
docs/pyproject.md
Outdated
| ```bash | ||
| project_name/ | ||
| ├── pyproject.toml | ||
| ├── README.md | ||
| ├── project_name/ | ||
| │ └── __init__.py | ||
| └── tests/ | ||
| └── __init__.py | ||
| This layout assumes: | ||
| The top-level directory contains pyproject.toml and README.md. | ||
| The main package directory matches the name field in pyproject.toml (or a snake_case variant). | ||
| Tests go in a separate tests/ directory. |
There was a problem hiding this comment.
On the one side this is incomplete - this is not the only supported layout -, on the other side it contains dispensable information - it does not matter where tests are or if there is a readme).
Here is the code for automatically detecting packages: https://github.com/python-poetry/poetry-core/blob/2548a4c47e172d298c2c34d0e511e5c589397de5/src/poetry/core/masonry/utils/module.py#L38-L70
In words: There must be either a module or a package with the project name (canonicalized and dashes replaced by underscores). This module or package must either be on the level of the pyproject.toml (flat layout) or in a src directory (src layout). Both are "standard layouts" (cf https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/).
We should probably replace
If your project structure differs from the standard one
with
If packages are not automatically detected
and explain in which cases they are automatically detected.
|
Hi @radoering, I’ve updated the packages section as suggested: |
nothing-991
force-pushed
the
docs-standard-project-structure
branch
from
79434ab to
a74ceed
Compare
|
Hi @radoering, |
It looks like something went wrong. https://github.com/python-poetry/poetry/pull/10680/changes only shows a |
nothing-991
force-pushed
the
docs-standard-project-structure
branch
from
b229569 to
2527119
Compare
|
Hey |
2 participants
Standard Project Structure
Poetry considers a "standard project structure" to be:
project_name/ ├── pyproject.toml ├── README.md ├── project_name/ │ └── __init__.py └── tests/ └── __init__.py The top-level directory contains pyproject.toml and README.md. The main package directory matches the name field in pyproject.toml (or a snake_case variant). Tests go in a separate tests/ directory. {{% note %}} If your project matches this layout, Poetry will auto-detect your main package, and you do not need to list it in [tool.poetry.packages]. {{% /note %}} {{% warning %}} If your project differs from this standard layout — for example, packages inside a lib/ directory, or the top-level package name doesn’t match name in pyproject.toml — you must explicitly list them in [tool.poetry.packages] to include them in your distribution. {{% /warning %}} ## Summary by Sourcery Documentation: - Add a section describing the recommended standard project layout, including package and tests placement and when explicit [tool.poetry.packages] configuration is required.