Explain in which cases packages are automatically detected
#10680
Conversation
Reviewer's guide (collapsed on small PRs)Reviewer's GuideUpdates the pyproject documentation to clarify how Poetry auto-detects packages/modules and when explicit [tool.poetry.packages] configuration is needed, including supported layouts and name normalization rules. Flow diagram for Poetry package auto-detection rulesgraph TD
A[Start: Project setup] --> B[Read project name from pyproject.toml]
B --> C[Normalize project name
replace - with _]
C --> D{Is there a matching
module or package?}
D -->|Yes| E{Location of matching
module or package}
D -->|No| H[Packages are not auto-detected
User must configure tool.poetry.packages]
E --> F{Is it at same level
as pyproject.toml?}
E --> G{Is it inside src/ directory?}
F -->|Yes| I[Auto-detect package/module
using flat layout]
F -->|No| G
G -->|Yes| J[Auto-detect package/module
using src layout]
G -->|No| H
I --> K[Poetry includes detected
package in distribution]
J --> K
H --> L[Poetry includes only packages
listed in tool.poetry.packages]
K --> M[End]
L --> M
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. |
|
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 |
|
Please always double-check the diff view. Now, almost all explanation about |
|
I’ve reworked the packages section to clearly describe when Poetry automatically detects packages (module/package name matching the project name, flat or src/ layout) and when explicit configuration is required. |
radoering
force-pushed
the
docs-standard-project-structure
branch
from
351e745 to
8071422
Compare
|
@sourcery-ai review |
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- The new note describes auto-detection rules but doesn’t mention how this interacts with the earlier “standard project structure” guidance (e.g., package dir matching the project name, tests/ placement); consider aligning or cross-referencing these sections so users don’t get conflicting mental models.
- It may help to explicitly call out common non-standard layouts that won’t be auto-detected (e.g., multiple top-level packages, namespace packages, or packages under lib/), so readers know when they must fall back to [tool.poetry.packages].
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The new note describes auto-detection rules but doesn’t mention how this interacts with the earlier “standard project structure” guidance (e.g., package dir matching the project name, tests/ placement); consider aligning or cross-referencing these sections so users don’t get conflicting mental models.
- It may help to explicitly call out common non-standard layouts that won’t be auto-detected (e.g., multiple top-level packages, namespace packages, or packages under lib/), so readers know when they must fall back to [tool.poetry.packages].Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
|
Deploy preview for website ready! ✅ Preview Built with commit 8071422. |
radoering
changed the title
packages are automatically detected
2 participants
Resolves: #8713
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: - Document automatic package detection rules based on normalized project name and supported flat/src layouts in pyproject.md.