Improve error message for invalid virtualenvs.prompt config by aryanyk · Pull Request #10649 · python-poetry/poetry

aryanyk · 2025-12-09T17:27:54Z

Pull Request Check List

Resolves: #Resolves: #10635

Summary

Improve error message when an invalid template variable is used in
virtualenvs.prompt configuration.

Details

Previously an invalid placeholder such as {python-version} resulted in
a cryptic KeyError. This change catches the error and raises a clearer
PoetryError explaining the config source and how to fix it.

Testing

Reproduced and validated locally using WSL (Ubuntu)

Summary by Sourcery

Bug Fixes:

Prevent cryptic KeyError when virtualenv prompt configuration contains an unknown template variable by raising a descriptive PoetryError instead.

sourcery-ai · 2025-12-09T17:28:00Z

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Improves handling of invalid template variables in the virtualenv prompt configuration by converting a raw KeyError into a clearer, user-facing PoetryError with guidance on how to fix the configuration.

Sequence diagram for handling invalid virtualenvs.prompt template variables

sequenceDiagram
    actor User
    participant PoetryCLI
    participant EnvManager
    participant PythonFormatEngine

    User->>PoetryCLI: Run_command_that_creates_virtualenv
    PoetryCLI->>EnvManager: create_venv(venv_prompt)

    alt venv_prompt_is_not_none
        EnvManager->>PythonFormatEngine: venv_prompt.format(project_name, python_version)
        alt template_variable_is_valid
            PythonFormatEngine-->>EnvManager: formatted_prompt
            EnvManager-->>PoetryCLI: virtualenv_created_with_custom_prompt
            PoetryCLI-->>User: Command_succeeds
        else template_variable_is_invalid
            PythonFormatEngine-->>EnvManager: KeyError
            EnvManager-->>PoetryCLI: PoetryError_invalid_template_variable
            PoetryCLI-->>User: Clear_error_message_with_config_guidance
        end
    else venv_prompt_is_none
        EnvManager-->>PoetryCLI: virtualenv_created_with_default_prompt
        PoetryCLI-->>User: Command_succeeds
    end

File-Level Changes

Change	Details	Files
Add defensive error handling around virtualenv prompt formatting to surface clearer configuration errors to users.	Wrap the venv_prompt.format(...) call in a try/except block to intercept KeyError caused by unknown template variables. On KeyError, raise a PoetryError instead of letting the KeyError propagate, preserving the original exception as the cause. Include the invalid template variable name and the configuration option path (virtualenvs.prompt) in the PoetryError message, with guidance to check the Poetry configuration file.	`src/poetry/utils/env/env_manager.py`

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#10635	Provide a clear and descriptive error message when an invalid template variable is used in the `virtualenvs.prompt` configuration (e.g., `{python-version}` instead of `{python_version}`).	✅
#10635	Ensure the error message indicates that the problem originates from the global Poetry configuration (`virtualenvs.prompt`), not from Python or the local `pyproject.toml`.	✅

Possibly linked issues

Error message for incorrect configs is unclear #10635: PR catches KeyError from invalid virtualenvs.prompt and raises a clear PoetryError, matching the issue’s request.

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 there - I've reviewed your changes - here's some feedback:

Consider including the list of supported template variables (e.g. project_name, python_version) in the error message so users immediately know what they can use instead of the invalid placeholder.
If possible, reference the concrete config file path or source (e.g. poetry config --list or the actual file location) in the error message rather than the generic 'Poetry configuration file' to make it easier for users to locate and fix the setting.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Consider including the list of supported template variables (e.g. `project_name`, `python_version`) in the error message so users immediately know what they can use instead of the invalid placeholder.
- If possible, reference the concrete config file path or source (e.g. `poetry config --list` or the actual file location) in the error message rather than the generic 'Poetry configuration file' to make it easier for users to locate and fix the setting.

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

aryanyk · 2025-12-09T17:32:48Z

Thanks for the feedback! Makes sense — I’ll update the error message to include the supported template variables and reference the concrete config source so it’s easier for users to fix. Will push an update shortly.

aryanyk · 2025-12-09T17:45:06Z

I’ve updated the error message to include the supported template variables and more concrete config hints, and applied Ruff formatting. Let me know if you’d like the wording tweaked further.

aryanyk · 2025-12-10T12:46:05Z

Hi @radoering ,

I’ve pushed the requested changes and all CI checks are green now ✅
Could you please review the PR when you get a chance?

Thanks for your time and guidance!

radoering

Unfortunately, someone else created a similar PR shortly before you: #10648.

Since that PR covers an additional error, adds tests and was the first one, I tend to prefer it - if the author addresses the review feedback.

Thank you anyway.

radoering · 2025-12-14T06:01:48Z

src/poetry/utils/env/env_manager.py

+            except KeyError as e:
+                raise PoetryError(
+                    f'Invalid template variable "{e.args[0]}" in '
+                    'global configuration option "virtualenvs.prompt".\n\n'


It is not necessarily in the global configuration. It can also be in the local configuration.

radoering · 2025-12-14T06:07:48Z

src/poetry/utils/env/env_manager.py

+                    'global configuration option "virtualenvs.prompt".\n\n'
+                    "Supported variables are: project_name, python_version.\n"
+                    "You can update this setting via:\n"
+                    "  - ~/.config/pypoetry/config.toml\n"


That is only the path for Linux and only the global configuration. It probably makes more sense to recommend setting it via poetry config [--local] virtualenvs.prompt <value>.

github-actions · 2026-01-20T00:36:36Z

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.

Improve error message for invalid virtualenvs.prompt config

0c5a150

sourcery-ai bot reviewed Dec 9, 2025

View reviewed changes

Refine virtualenvs.prompt error message and apply formatting

e9151f9

Merge branch 'main' into fix-invalid-virtualenv-prompt-error

af2a64e

radoering mentioned this pull request Dec 14, 2025

Fix: Improve error message for invalid template variables in virtualenvs.prompt #10648

Merged

radoering reviewed Dec 14, 2025

View reviewed changes

radoering closed this in #10648 Dec 20, 2025

github-actions bot locked as resolved and limited conversation to collaborators Jan 20, 2026

Comments

Conversation

aryanyk commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Check List

Summary

Details

Testing

Summary by Sourcery

Uh oh!

sourcery-ai bot commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Reviewer's Guide

Sequence diagram for handling invalid virtualenvs.prompt template variables

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!

aryanyk commented Dec 9, 2025

Uh oh!

aryanyk commented Dec 9, 2025

Uh oh!

aryanyk commented Dec 10, 2025

Uh oh!

radoering left a comment

Choose a reason for hiding this comment

Uh oh!

radoering Dec 14, 2025

Choose a reason for hiding this comment

Uh oh!

radoering Dec 14, 2025

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Jan 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

aryanyk commented Dec 9, 2025 •

edited

Loading

sourcery-ai bot commented Dec 9, 2025 •

edited

Loading