docs: clarify configuration source precedence by mitre88 · Pull Request #10757 · python-poetry/poetry

mitre88 · 2026-03-05T20:11:07Z

Summary

Document configuration source precedence in docs/configuration.md.
Clarify that environment variables override local config, global config, and default values.
Add a note that credential values may also be read from auth.toml and keyring, while environment variables still override file-based values.

Resolves: #5029

Added tests for changed code.
Updated documentation for changed code.

Summary by Sourcery

Clarify configuration source precedence and credential lookup behavior in the configuration documentation.

Documentation:

Document the precedence order between environment variables, local configuration, global configuration, and default values in the configuration guide.
Explain how repository credentials can be sourced from auth.toml and the system keyring, while environment variables still take precedence.

Add a section to configuration docs that explains precedence among environment variables, local config, global config, and defaults.

sourcery-ai · 2026-03-05T20:11:13Z

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Documents configuration source precedence in configuration.md, explicitly listing the order of precedence across environment variables, local and global configuration files, and defaults, and clarifies how repository credentials interact with auth.toml and the system keyring.

Flow diagram for configuration source precedence lookup

flowchart TD
    A[Start configuration lookup] --> B{Is environment variable set?}
    B -- Yes --> C[Use environment variable value]
    B -- No --> D{Is value set in local poetry.toml?}
    D -- Yes --> E[Use local poetry.toml value]
    D -- No --> F{Is value set in global config.toml?}
    F -- Yes --> G[Use global config.toml value]
    F -- No --> H[Use default value]

    subgraph Credentials_sources
        I[Repository credentials setting<br/>http-basic.* or pypi-token.*] --> J{Is environment variable set?}
        J -- Yes --> K[Use environment variable value]
        J -- No --> L{Is value in auth.toml or keyring?}
        L -- Yes --> M[Use auth.toml or keyring value]
        L -- No --> N[Fall back to other configuration sources<br/>or default]
    end

File-Level Changes

Change	Details	Files
Document configuration source precedence and credential lookup behavior in the configuration guide.	Add a dedicated 'Configuration sources' section describing precedence from environment variables down to default values. Clarify that local poetry.toml overrides global config.toml, which in turn overrides default settings. Document that repository credentials can also be read from auth.toml and the system keyring, but that environment variables still override any file-based values. Ensure examples use an explicit environment variable name (POETRY_VIRTUALENVS_CREATE) to illustrate precedence.	`docs/configuration.md`

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#5029	Document the precedence order of configuration sources (environment variables, local poetry.toml, global config.toml, and defaults) in the configuration documentation.	✅
#5029	Clarify how repository credentials are sourced (auth.toml and keyring) and how their precedence relates to environment variables and other configuration files.	✅

Possibly linked issues

[docs] configuration documentation does not specify the precedence of each method #5029: They’re directly related; the PR explicitly documents precedence between local and global configs and other sources.

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 found 1 issue, and left some high level feedback:

Consider clarifying the relative precedence between auth.toml, the system keyring, and the regular config files so readers understand the complete ordering for credential lookup, not just that env vars win over file-based values.
It may be helpful to explicitly link or refer back to the earlier note about local vs global configuration precedence so readers don’t have to infer how that section aligns with the new, more detailed precedence list.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Consider clarifying the relative precedence between `auth.toml`, the system keyring, and the regular config files so readers understand the complete ordering for credential lookup, not just that env vars win over file-based values.
- It may be helpful to explicitly link or refer back to the earlier note about local vs global configuration precedence so readers don’t have to infer how that section aligns with the new, more detailed precedence list.

## Individual Comments

### Comment 1
<location path="docs/configuration.md" line_range="58" />
<code_context>
+precedence over file-based values.
+
 {{% warning %}}
 Be mindful when checking in this file into your repository since it may contain user-specific or sensitive information.
 {{% /warning %}}
</code_context>
<issue_to_address>
**issue (typo):** Consider fixing the grammar in this sentence by removing the extra "in".

The current wording is a bit awkward. Consider either "checking this file into your repository" or "checking in this file to your repository" to avoid the duplicated preposition.

```suggestion
Be mindful when checking this file into your repository since it may contain user-specific or sensitive information.
```
</issue_to_address>

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

sourcery-ai · 2026-03-05T20:11:48Z

docs/configuration.md

+precedence over file-based values.
+
 {{% warning %}}
 Be mindful when checking in this file into your repository since it may contain user-specific or sensitive information.


issue (typo): Consider fixing the grammar in this sentence by removing the extra "in".

The current wording is a bit awkward. Consider either "checking this file into your repository" or "checking in this file to your repository" to avoid the duplicated preposition.

Suggested change

Be mindful when checking in this file into your repository since it may contain user-specific or sensitive information.

Be mindful when checking this file into your repository since it may contain user-specific or sensitive information.

radoering · 2026-03-15T14:19:03Z

docs/configuration.md

 the local/project configuration takes precedence over the global configuration.
 {{% /note %}}

+## Configuration sources


I wonder if this section should be placed after "Using environment variables" because here environment variables were not even introduced.

By the way, the section is placed in the middle of another section at the moment. The warning that follows belongs to "Local configuration".

radoering · 2026-03-15T14:23:05Z

docs/configuration.md

+4. The setting's default value
+
+For repository credentials (`http-basic.*`, `pypi-token.*`), Poetry may also read
+from `auth.toml` and the system keyring. Environment variables still take


We should add a link to where this is explained like:

Suggested change

from `auth.toml` and the system keyring. Environment variables still take

from `auth.toml` and the system keyring - for details see <link>. Environment variables still take

docs: clarify configuration source precedence

da78792

Add a section to configuration docs that explains precedence among environment variables, local config, global config, and defaults.

sourcery-ai bot reviewed Mar 5, 2026

View reviewed changes

radoering requested changes Mar 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: clarify configuration source precedence#10757

docs: clarify configuration source precedence#10757
mitre88 wants to merge 1 commit intopython-poetry:mainfrom
mitre88:patch-1

mitre88 commented Mar 5, 2026 •

edited by sourcery-ai bot

Loading

Uh oh!

sourcery-ai bot commented Mar 5, 2026 •

edited

Loading

Reviewer's Guide

Flow diagram for configuration source precedence lookup

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

Uh oh!

sourcery-ai bot Mar 5, 2026

Uh oh!

radoering Mar 15, 2026

Uh oh!

radoering Mar 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	Be mindful when checking in this file into your repository since it may contain user-specific or sensitive information.
	Be mindful when checking this file into your repository since it may contain user-specific or sensitive information.

	from `auth.toml` and the system keyring. Environment variables still take
	from `auth.toml` and the system keyring - for details see <link>. Environment variables still take

Conversation

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

Uh oh!

Summary

Summary by Sourcery

Uh oh!

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

Uh oh!

Reviewer's Guide

Flow diagram for configuration source precedence lookup

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!

sourcery-ai bot Mar 5, 2026

Choose a reason for hiding this comment

Uh oh!

radoering Mar 15, 2026

Choose a reason for hiding this comment

Uh oh!

radoering Mar 15, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mitre88 commented Mar 5, 2026 •

edited by sourcery-ai bot

Loading

sourcery-ai bot commented Mar 5, 2026 •

edited

Loading