init: only add readme key if README file exists #10679

ammargit93 · 2026-01-01T13:35:56Z

Problem

When running poetry init, the generated pyproject.toml always includes a readme key, even if there is no README file in the project.
This can cause poetry install to fail, forcing the user to either create a README file or manually remove the key.

Solution

Check if the README file exists before adding the readme key in pyproject.toml.

If README.md (or the specified format) exists, the readme key is added.
If not, the key is omitted.

This change fixes Issue #10217.

Impact

Minimal: only affects newly created projects with poetry init.
Does not change behavior for existing projects or other keys.

Testing

Added unit tests in tests/layouts/test_layout.py:

test_readme_key_present_if_readme_exists
test_readme_key_removed_if_readme_missing

All tests pass locally on Windows.

Workarounds

Before this fix, users had to manually remove the readme key after running poetry init.

Summary by Sourcery

Conditionally include the readme entry in newly generated pyproject.toml files based on the presence of a README file in the project directory.

Bug Fixes:

Prevent poetry init from generating a readme key when no README file exists, avoiding subsequent installation failures.

Tests:

Add layout tests to verify the readme key is omitted when the README file is missing and present when it exists.

sourcery-ai · 2026-01-01T13:36:02Z

Reviewer's Guide

Conditionally include the readme key in newly generated pyproject.toml only when a README file actually exists, and add layout-level tests that verify both presence and absence behaviors based on the filesystem state.

Sequence diagram for conditional readme key generation in poetry init

sequenceDiagram
    actor Developer
    participant PoetryCLI
    participant Layout
    participant FileSystem
    participant TOMLDocument

    Developer->>PoetryCLI: run poetry init
    PoetryCLI->>Layout: generate_project_content()
    Layout->>TOMLDocument: build base project_content
    Layout->>FileSystem: exists(basedir/README.<format>)
    alt README exists
        FileSystem-->>Layout: true
        Layout->>TOMLDocument: set readme = README.<format>
    else README missing
        FileSystem-->>Layout: false
        Layout->>TOMLDocument: remove readme key if present
    end
    Layout-->>PoetryCLI: TOMLDocument with conditional readme
    PoetryCLI-->>Developer: write pyproject.toml

Class diagram for Layout.generate_project_content readme handling

classDiagram
    class Layout {
        Path basedir
        str _readme_format
        str _license
        str _python
        generate_project_content() TOMLDocument
    }

    class TOMLDocument {
        setitem(key, value) void
        remove(key) void
        pop(key, default) Any
    }

    class FileSystem {
        exists(path) bool
    }

    Layout ..> TOMLDocument : generates
    Layout ..> FileSystem : checks_exists

File-Level Changes

Change	Details	Files
Make the `readme` key in generated project metadata conditional on the existence of the README file.	Replace unconditional assignment of the `readme` field with a filesystem existence check using the layout base directory and configured README format. If a matching README file exists, set the `readme` key to the corresponding filename in the generated project content. If no README file exists, remove any existing `readme` key from the project content to avoid invalid configuration.	`src/poetry/layouts/layout.py`
Add tests to validate `readme` key behavior with and without a README file present.	Introduce a `DummyLayout` subclass that allows injecting a temporary base directory for testing. Add a test that asserts the `readme` key is absent from generated project metadata when no README file exists in the base directory. Add a test that asserts the `readme` key is correctly set when a `README` file with the expected extension exists in the base directory.	`tests/layouts/test_layout.py`

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#10217	Modify `poetry init` project generation so that the `readme` key is only added to `pyproject.toml` when a README file (e.g. `README.md`) actually exists in the project directory.	✅
#10217	Add or update automated tests to cover the presence/absence of the `readme` key based on whether a README file exists.	✅

Possibly linked issues

Make poetry init not add readme section if it doesn't detect a readme #10217: The PR implements existence checks so poetry init only adds the readme key when a README file exists.

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:

In generate_project_content, prefer using the existing basedir/Path API (e.g. self.basedir / f"README.{self._readme_format}").exists() rather than os.path.exists and avoid mixing Path with the / operator on non-Paths.
Instead of project_content.pop("readme", None), consider using the same removal mechanism as for license (e.g. project_content.remove("readme")) for consistency with the TOMLDocument API.
In tests/layouts/test_layout.py, clean up duplicate imports and unused imports (e.g. pytest, second Path/Layout import) to keep the test module minimal and focused.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- In `generate_project_content`, prefer using the existing `basedir`/`Path` API (e.g. `self.basedir / f"README.{self._readme_format}"`).`exists()` rather than `os.path.exists` and avoid mixing `Path` with the `/` operator on non-Paths.
- Instead of `project_content.pop("readme", None)`, consider using the same removal mechanism as for `license` (e.g. `project_content.remove("readme")`) for consistency with the `TOMLDocument` API.
- In `tests/layouts/test_layout.py`, clean up duplicate imports and unused imports (e.g. `pytest`, second `Path`/`Layout` import) to keep the test module minimal and focused.

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

ammargit93 · 2026-01-01T16:00:04Z

Hi
I wanted to note that after implementing the change to conditionally add the readme key only if a README file exists, I ran into a large number of test failures. Even though the code change itself is small, many existing tests—especially in tests/console/commands/test_init.py and tests/console/commands/test_new.py—assume that the readme key always exists after poetry init.

After modifying the test_init.py i reduced the failed tests from 34 to 15, any help on this matter would be greatly appreciated.

radoering · 2026-01-02T09:51:52Z

Even though the code change itself is small, many existing tests—especially in tests/console/commands/test_init.py and tests/console/commands/test_new.py—assume that the readme key always exists after poetry init.

It makes sense that (many) tests in test_init.py have to be adapted. If there is no such test yet, a test with an existing readme should be added so that a project.toml with an readme entry is still created in at least one test.

As far as I know, poetry new creates a readme file so that the readme entry in the pyproject.toml should still be created. If the check for an existing readme happens before the readme file is created and thus the readme entry in the pyproject.toml file is not created that would be a bug that should be fixed. If this still works, it might just be an issue of the tests.

ammargit93 · 2026-01-03T13:25:33Z

Hello @radoering, really sorry for the messy commit history. The important changes in this PR are:

4d5e1de — updated and wrote tests to respect updated init behavior
fb66c1d — apply pre-commit fixes

Regarding the code:

I considered that poetry new creates a README file, so the readme entry in pyproject.toml should still be created.
Introduced a command_name parameter in generate_project_content(self, command_name: str | None = None) to check if the command is 'new' or 'init'.

The other commits are mainly minor formatting/linting adjustments from pre-commit.

Environment:
Windows 11

Could you please review this PR? Thanks!

src/poetry/layouts/layout.py

tests/console/commands/test_init.py

tests/console/commands/test_new.py

.gitignore

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 1, 2026

View reviewed changes

ammargit93 force-pushed the bugfix/init-readme-key branch from b345884 to f7173ce Compare January 3, 2026 12:14

ammargit93 added 4 commits January 3, 2026 18:32

fix(init): only add readme key if README file exists

7308d7b

fix(init): only add readme key if README file exists

4864981

updated tests to respect updated init behavior

4d5e1de

apply pre-commit fixes

fb66c1d

ammargit93 force-pushed the bugfix/init-readme-key branch from f7173ce to fb66c1d Compare January 3, 2026 13:04

radoering requested changes Jan 4, 2026

View reviewed changes

src/poetry/layouts/layout.py Outdated Show resolved Hide resolved

tests/console/commands/test_init.py Outdated Show resolved Hide resolved

tests/console/commands/test_new.py Outdated Show resolved Hide resolved

.gitignore Outdated Show resolved Hide resolved

fix(init):Fix readme key handling on init/new commands

9a32477

ammargit93 requested a review from radoering January 4, 2026 17:13

radoering added 3 commits January 5, 2026 16:37

revert unrelated changes

a855fda

move fixture to related fixtures

334afa6

make test more robust

88602c7

radoering changed the title ~~Only add readme key if README file exists~~ init: only add readme key if README file exists Jan 5, 2026

radoering approved these changes Jan 5, 2026

View reviewed changes

radoering enabled auto-merge (squash) January 5, 2026 16:02

radoering merged commit cc1d791 into python-poetry:main Jan 5, 2026
54 checks passed

ammargit93 deleted the bugfix/init-readme-key branch January 12, 2026 10:53

radoering mentioned this pull request Jan 17, 2026

release: bump version to 2.3.0 #10695

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

init: only add readme key if README file exists #10679

init: only add readme key if README file exists #10679

ammargit93 commented Jan 1, 2026 •

edited by sourcery-ai bot

Loading

Uh oh!

sourcery-ai bot commented Jan 1, 2026 •

edited

Loading

Interacting with Sourcery

Customizing Your Experience

Getting Help

Uh oh!

sourcery-ai bot left a comment

Uh oh!

ammargit93 commented Jan 1, 2026

Uh oh!

radoering commented Jan 2, 2026

Uh oh!

ammargit93 commented Jan 3, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

init: only add readme key if README file exists #10679

init: only add readme key if README file exists #10679

Conversation

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

Uh oh!

Problem

Solution

Impact

Testing

Workarounds

Summary by Sourcery

Uh oh!

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

Uh oh!

Reviewer's Guide

Sequence diagram for conditional readme key generation in poetry init

Class diagram for Layout.generate_project_content readme handling

File-Level Changes

Assessment against linked issues

Possibly linked issues

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!

ammargit93 commented Jan 1, 2026

Uh oh!

radoering commented Jan 2, 2026

Uh oh!

ammargit93 commented Jan 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ammargit93 commented Jan 1, 2026 •

edited by sourcery-ai bot

Loading

sourcery-ai bot commented Jan 1, 2026 •

edited

Loading

ammargit93 commented Jan 3, 2026 •

edited

Loading