Explain in which cases `packages` are automatically detected #10680

nothing-991 · 2026-01-02T08:18:55Z

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.

sourcery-ai · 2026-01-02T08:19:03Z

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Updates 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 rules

graph 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

Change	Details	Files
Clarify automatic package/module detection rules and supported layouts in pyproject documentation, and reword guidance about when to configure [tool.poetry.packages].	Reword the description of when to use [tool.poetry.packages] to refer to cases where packages are not automatically detected rather than vaguely "differing from the standard" structure. Add a note explaining that Poetry auto-detects a single module or package whose name matches the normalized project name (with dashes replaced by underscores). Document the allowed locations for the auto-detected module/package: at the same level as pyproject.toml (flat layout) or under src/ (src layout).	`docs/pyproject.md`

Tips and commands

Interacting with Sourcery

Trigger a new review: Comment @sourcery-ai review on the pull request.
Continue discussions: Reply directly to Sourcery's review comments.
Generate a GitHub issue from a review comment: Ask Sourcery to create an
issue from a review comment by replying to it. You can also reply to a
review comment with @sourcery-ai issue to create an issue from it.
Generate a pull request title: Write @sourcery-ai anywhere in the pull
request title to generate a title at any time. You can also comment
@sourcery-ai title on the pull request to (re-)generate the title at any time.
Generate a pull request summary: Write @sourcery-ai summary anywhere in
the pull request body to generate a PR summary at any time exactly where you
want it. You can also comment @sourcery-ai summary on the pull request to
(re-)generate the summary at any time.
Generate reviewer's guide: Comment @sourcery-ai guide on the pull
request to (re-)generate the reviewer's guide at any time.
Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
pull request to resolve all Sourcery comments. Useful if you've already
addressed all the comments and don't want to see them anymore.
Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
request to dismiss all existing Sourcery reviews. Especially useful if you
want to start fresh with a new review - don't forget to comment
@sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

Enable or disable review features such as the Sourcery-generated pull request
summary, the reviewer's guide, and others.
Change the review language.
Add, remove or edit custom review instructions.
Adjust other review settings.

Getting Help

Contact our support team for questions or feedback.
Visit our documentation for detailed guides and information.
Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

sourcery-ai

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 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.

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.

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

nothing-991 · 2026-01-02T08:24:47Z

Added the snippet detailing the Standard Project Structure in the [tool.poetry.packages] section.
This clarifies when Poetry can auto-detect packages vs. when explicit entries are required.
Updated the PR for review.

docs/pyproject.md

nothing-991 · 2026-01-02T10:58:12Z

Hi @radoering, I’ve updated the packages section as suggested:
Replaced “If your project structure differs from the standard one” with “If packages are not automatically detected”.
Added clarification about when Poetry can auto-detect packages.
Kept examples for packages, exclude/include, and extras updated for clarity.
All changes are now committed and pushed. Thanks for reviewing!

nothing-991 · 2026-01-04T05:56:02Z

Hi @radoering,
I just wanted to clarify that this PR (docs-standard-project-structure) only contains changes related to the standard project structure documentation.
All commits have been reviewed and cleaned up.
There are no unrelated changes from the contributor guide or other PRs in this branch.
The branch has been force-pushed to remove any accidental commits that were previously present.
Everything in this PR is fully aligned with the intended scope: standard project layout, package auto-detection, and related notes.
Please let me know if you notice anything else that needs adjustment — everything else should be ready for review.
Thanks! 🙏

radoering · 2026-01-04T09:06:40Z

Everything in this PR is fully aligned with the intended scope: standard project layout, package auto-detection, and related notes.

It looks like something went wrong. https://github.com/python-poetry/poetry/pull/10680/changes only shows a Contributing to an Existing Poetry Project section in basic-usage.md, which clearly belongs to another PR.

nothing-991 · 2026-01-08T06:15:25Z

Hey
I just force-pushed the branch so it now only includes docs/pyproject.md. All other unrelated stuff has been removed—this PR now matches the intended scope. Thanks for taking a look!

radoering · 2026-01-10T07:03:31Z

Please always double-check the diff view. Now, almost all explanation about tool.poetry.packages got deleted.

nothing-991 · 2026-01-13T07:19:56Z

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.
The previous wording around “standard project structure” has been removed to avoid over-constraining supported layouts, and the existing configuration examples and notes were kept intact.
Please let me know if you’d like the detection criteria or wording refined further.

radoering · 2026-01-16T16:00:47Z

@sourcery-ai review

sourcery-ai

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].

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

github-actions · 2026-01-16T16:02:14Z

Deploy preview for website ready!

✅ Preview
https://website-ip427xbm0-python-poetry.vercel.app

Built with commit 8071422.
This pull request is being automatically deployed with vercel-action

This PR contains the following updates: | Package | Update | Change | |---|---|---| | [poetry](https://github.com/python-poetry/poetry) ([changelog](https://python-poetry.org/history/)) | minor | ` 2.2.1` -> `2.3.0` | --- ### Release Notes <details> <summary>python-poetry/poetry (poetry)</summary> ### [`v2.3.0`](https://github.com/python-poetry/poetry/blob/HEAD/CHANGELOG.md#230---2026-01-18) [Compare Source](python-poetry/poetry@2.2.1...2.3.0) ##### Added - **Add support for exporting `pylock.toml` files with `poetry-plugin-export`** ([#10677](python-poetry/poetry#10677)). - Add support for specifying build constraints for dependencies ([#10388](python-poetry/poetry#10388)). - Add support for publishing artifacts whose version is determined dynamically by the build-backend ([#10644](python-poetry/poetry#10644)). - Add support for editable project plugins ([#10661](python-poetry/poetry#10661)). - Check `requires-poetry` before any other validation ([#10593](python-poetry/poetry#10593)). - Validate the content of `project.readme` when running `poetry check` ([#10604](python-poetry/poetry#10604)). - Add the option to clear all caches by making the cache name in `poetry cache clear` optional ([#10627](python-poetry/poetry#10627)). - Automatically update the cache for packages where the locked files differ from cached files ([#10657](python-poetry/poetry#10657)). - Suggest to clear the cache if running a command with `--no-cache` solves an issue ([#10585](python-poetry/poetry#10585)). - Propose `poetry init` when trying `poetry new` for an existing directory ([#10563](python-poetry/poetry#10563)). - Add support for `poetry publish --skip-existing` for new Nexus OSS versions ([#10603](python-poetry/poetry#10603)). - Show Poetry's own Python's path in `poetry debug info` ([#10588](python-poetry/poetry#10588)). ##### Changed - **Drop support for Python 3.9** ([#10634](python-poetry/poetry#10634)). - **Change the default of `installer.re-resolve` from `true` to `false`** ([#10622](python-poetry/poetry#10622)). - **PEP 735 dependency groups are considered in the lock file hash** ([#10621](python-poetry/poetry#10621)). - Deprecate `poetry.utils._compat.metadata`, which is sometimes used in plugins, in favor of `importlib.metadata` ([#10634](python-poetry/poetry#10634)). - Improve managing free-threaded Python versions with `poetry python` ([#10606](python-poetry/poetry#10606)). - Prefer JSON API to HTML API in legacy repositories ([#10672](python-poetry/poetry#10672)). - When running `poetry init`, only add the readme field in the `pyproject.toml` if the readme file exists ([#10679](python-poetry/poetry#10679)). - Raise an error if no hash can be determined for any distribution link of a package ([#10673](python-poetry/poetry#10673)). - Require `dulwich>=0.25.0` ([#10674](python-poetry/poetry#10674)). ##### Fixed - Fix an issue where `poetry remove` did not work for PEP 735 dependency groups with `include-group` items ([#10587](python-poetry/poetry#10587)). - Fix an issue where `poetry remove` caused dangling `include-group` references in PEP 735 dependency groups ([#10590](python-poetry/poetry#10590)). - Fix an issue where `poetry add` did not work for PEP 735 dependency groups with `include-group` items ([#10636](python-poetry/poetry#10636)). - Fix an issue where PEP 735 dependency groups were not considered in the lock file hash ([#10621](python-poetry/poetry#10621)). - Fix an issue where wrong markers were locked for a dependency that was required by several groups with different markers ([#10613](python-poetry/poetry#10613)). - Fix an issue where non-deterministic markers were created in a method used by `poetry-plugin-export` ([#10667](python-poetry/poetry#10667)). - Fix an issue where wrong wheels were chosen for installation in free-threaded Python environments if Poetry itself was not installed with free-threaded Python ([#10614](python-poetry/poetry#10614)). - Fix an issue where `poetry publish` used the metadata of the project instead of the metadata of the build artifact ([#10624](python-poetry/poetry#10624)). - Fix an issue where `poetry env use` just used another Python version instead of failing when the requested version was not supported by the project ([#10685](python-poetry/poetry#10685)). - Fix an issue where `poetry env activate` returned the wrong command for `dash` ([#10696](python-poetry/poetry#10696)). - Fix an issue where `data-dir` and `python.installation-dir` could not be set ([#10595](python-poetry/poetry#10595)). - Fix an issue where Python and pip executables were not correctly detected on Windows ([#10645](python-poetry/poetry#10645)). - Fix an issue where invalid template variables in `virtualenvs.prompt` caused an incomprehensible error message ([#10648](python-poetry/poetry#10648)). ##### Docs - Add a warning about `~/.netrc` for Poetry credential configuration ([#10630](python-poetry/poetry#10630)). - Clarify that the local configuration takes precedence over the global configuration ([#10676](python-poetry/poetry#10676)). - Add an explanation in which cases `packages` are automatically detected ([#10680](python-poetry/poetry#10680)). ##### poetry-core ([`2.3.0`](https://github.com/python-poetry/poetry-core/releases/tag/2.3.0)) - Normalize versions ([#893](python-poetry/poetry-core#893)). - Fix an issue where unsatisfiable requirements did not raise an error ([#891](python-poetry/poetry-core#891)). - Fix an issue where the implicit main group did not exist if it was explicitly declared as not having any dependencies ([#892](python-poetry/poetry-core#892)). - Fix an issue where `python_full_version` markers with pre-release versions were parsed incorrectly ([#893](python-poetry/poetry-core#893)). </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this PR, check this box --- This PR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).  Reviewed-on: https://git.walbeck.it/walbeck-it/docker-python-poetry/pulls/1654 Co-authored-by: renovate-bot <[email protected]> Co-committed-by: renovate-bot <[email protected]>

sourcery-ai bot reviewed Jan 2, 2026

View reviewed changes

radoering reviewed Jan 2, 2026

View reviewed changes

docs/pyproject.md Outdated Show resolved Hide resolved

nothing-991 force-pushed the docs-standard-project-structure branch from 79434ab to a74ceed Compare January 4, 2026 05:49

nothing-991 force-pushed the docs-standard-project-structure branch from b229569 to 2527119 Compare January 8, 2026 06:09

nothing-991 and others added 3 commits January 16, 2026 16:59

docs: clarify automatic package detection

07f7994

docs: clarify when packages are automatically detected

3b19b4c

use note instead of header; reword and add link

8071422

radoering force-pushed the docs-standard-project-structure branch from 351e745 to 8071422 Compare January 16, 2026 15:59

radoering added the impact/docs Contains or requires documentation changes label Jan 16, 2026

sourcery-ai bot reviewed Jan 16, 2026

View reviewed changes

radoering changed the title ~~Add explanation of standard project structure (#8713)~~ Explain in which cases packages are automatically detected Jan 16, 2026

radoering approved these changes Jan 16, 2026

View reviewed changes

radoering merged commit 91fb81b into python-poetry:main Jan 16, 2026
57 checks passed

nothing-991 deleted the docs-standard-project-structure branch January 16, 2026 16:08

radoering mentioned this pull request Jan 17, 2026

release: bump version to 2.3.0 #10695

Merged

Explain in which cases packages are automatically detected #10680

Explain in which cases packages are automatically detected #10680

Uh oh!

Conversation

nothing-991 commented Jan 2, 2026 • edited by radoering Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Standard Project Structure

Uh oh!

sourcery-ai bot commented Jan 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviewer's Guide

Flow diagram for Poetry package auto-detection rules

File-Level Changes

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

sourcery-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

nothing-991 commented Jan 2, 2026

Uh oh!

Uh oh!

nothing-991 commented Jan 2, 2026

Uh oh!

nothing-991 commented Jan 4, 2026

Uh oh!

radoering commented Jan 4, 2026

Uh oh!

nothing-991 commented Jan 8, 2026

Uh oh!

radoering commented Jan 10, 2026

Uh oh!

nothing-991 commented Jan 13, 2026

Uh oh!

radoering commented Jan 16, 2026

Uh oh!

sourcery-ai bot left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jan 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Explain in which cases `packages` are automatically detected #10680

Explain in which cases `packages` are automatically detected #10680

nothing-991 commented Jan 2, 2026 •

edited by radoering

Loading

sourcery-ai bot commented Jan 2, 2026 •

edited

Loading