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

[JaviMaligno]

Fixes #10635

Summary by Sourcery

Improve validation and error reporting for virtual environment prompt templates when creating virtualenvs.

Bug Fixes:

• Raise a clear PoetryRuntimeError when the virtualenvs.prompt template contains unknown variables instead of failing with a generic KeyError.

Tests:

• Add a regression test verifying that an invalid virtualenvs.prompt template variable produces a descriptive error message including the invalid name and config key.

[sourcery-ai[bot]]

Reviewer's Guide

Improves handling of invalid template variables in the virtualenv prompt configuration by validating the format string and raising a clearer PoetryRuntimeError, and adds a test to cover this behavior.

Sequence diagram for handling invalid virtualenvs.prompt template variables

sequenceDiagram
    actor User
    participant EnvManager
    participant PythonVersion
    participant PoetryRuntimeError

    User->>EnvManager: create_venv(venv_prompt)
    alt venv_prompt is not None
        EnvManager->>PythonVersion: minor_version.to_string()
        PythonVersion-->>EnvManager: python_version
        EnvManager->>EnvManager: venv_prompt.format(project_name, python_version)
        alt format raises KeyError
            EnvManager->>PoetryRuntimeError: construct with invalid template variable message
            PoetryRuntimeError-->>EnvManager: PoetryRuntimeError instance
            EnvManager-->>User: raise PoetryRuntimeError
        else format succeeds
            EnvManager-->>User: continue venv creation with formatted prompt
        end
    else venv_prompt is None
        EnvManager-->>User: continue venv creation without custom prompt
    end

Class diagram for EnvManager create_venv with improved error handling

classDiagram
    class EnvManager {
        +create_venv(venv_prompt, create_venv)
    }

    class PoetryRuntimeError {
        +PoetryRuntimeError(message)
    }

    class Package {
        +name
    }

    class Poetry {
        +package : Package
    }

    class PythonVersion {
        +minor_version : PythonVersion
        +to_string() string
    }

    EnvManager --> Poetry : uses
    EnvManager --> PythonVersion : uses
    EnvManager --> PoetryRuntimeError : raises

    %% Internal logic of create_venv
    class CreateVenvFlow {
        +if venv_prompt is not None
        +try venv_prompt.format(project_name, python_version)
        +except KeyError -> raise PoetryRuntimeError
    }

    EnvManager ..> CreateVenvFlow : implements logic

File-Level Changes

Change	Details	Files
Guard virtualenv prompt formatting with explicit error handling and raise a descriptive runtime error when an invalid template variable is used.	Wrap the venv_prompt.format call in a try/except block to catch KeyError caused by unknown template variables. On KeyError, import PoetryRuntimeError and raise it with a message that includes the invalid key, the setting name, and the list of valid variables. Document the valid template variables in the error message: {project_name} and {python_version}.	src/poetry/utils/env/env_manager.py
Add a regression test ensuring that an invalid virtualenv prompt template variable results in the new descriptive error message.	Configure the test environment with an invalid variable in the virtualenvs.prompt setting. Create a virtualenv and assert that a PoetryRuntimeError is raised. Verify that the error message contains the generic invalid-template text, the invalid variable name, and the 'virtualenvs.prompt' setting reference.	tests/utils/env/test_env_manager.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
https://github.com/python-poetry/poetry/issues/10635	Provide a clear, descriptive error message when virtualenvs.prompt contains an invalid template variable, including the invalid variable name and the setting key.	✅
https://github.com/python-poetry/poetry/issues/10635	Indicate the origin of the misconfiguration (e.g. which config file or whether it is from global configuration) when virtualenvs.prompt has an invalid template variable.	❌	The new error message states that the error is in the 'virtualenvs.prompt' setting and lists valid variables, but it does not specify which configuration file (such as ~/.config/pypoetry/config.toml) or whether the setting is from global vs local configuration.

Possibly linked issues

• #10635: PR adds a clear PoetryRuntimeError for invalid virtualenvs.prompt variables, directly addressing the unclear config error issue.

---

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.

[aryanyk]

Hey @JaviMaligno! 👋
Thanks for jumping in.

I’ve already opened a PR for this issue and am working through the review feedback right now. To avoid overlapping work, it might be easier to tackle another open issue unless the maintainers prefer otherwise.

Appreciate the enthusiasm!