docs: clarify configuration source precedence

[mitre88]

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.

[sourcery-ai]

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

Loading

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 ✨

• X
• Mastodon
• LinkedIn
• Facebook

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

[mitre88]

Gentle ping — this PR is ready for review. All CI checks pass. Would appreciate a look when possible. Thanks!

[radoering]

@mitre88 Do you see my review feedback from March 15?

[mitre88]

Hi @radoering — sorry for the delay! I've addressed your review feedback:

1. Moved 'Configuration sources' section after 'Using environment variables' so the precedence order is clear
2. Moved the warning back under 'Local configuration' where it belongs
3. Added a link to the Repositories docs for auth.toml/keyring details

Please take another look when you get a chance. Thanks!

[github-actions]

Deploy preview for website ready!

Project:	website
Status:	✅  Deploy successful!
Preview URL:	https://website-nkd6apwxm-python-poetry.vercel.app
Latest Commit:	2dca96d

Deployed with vercel-action