Suggest cache clear after fresh package info from --no-cache resolves installation candidate problems

[MadLittleMods]

Suggest cache clear after fresh package info from --no-cache resolves installation candidate problems.

For example, using poetry update --no-cache {package.name} will fetch fresh package info and update the poetry.lock file as expected. But then if you later run poetry lock again, it will use the stale cache data and revert those changes (unexpected). It's necessary to clear the cache to get in a consistent state again.

Ideally, this kind of behavior would be automatic and part of --no-cache or some sort of new option like --prefer-online but there isn't buy-in from maintainers yet. See #10584

Based on another existing message in the help log output for another problem,

poetry/src/poetry/installation/chooser.py

Line 248 in 17db1da

"If any of those solutions worked, you will have to clear your caches using (<c1>poetry cache clear --all CACHE_NAME</>)."

This also matches the wisdom in the docs:

poetry/docs/repositories.md

Lines 580 to 589 in 17db1da

	## Debugging Issues
	If you encounter issues with package sources, one of the simplest steps you might take to debug an issue is rerunning
	your command with the `--no-cache` flag.
	```bash
	poetry --no-cache add pycowsay
	```
	If this solves your issue, you can consider clearing your cache using the [`cache`]({{< relref "cli#cache-clear" >}})
	command.

Dev notes

Install and use local version of Poetry based on this PR:

poetry/docs/contributing.md

Lines 238 to 262 in 6ace575

	#### Multiple versions
	When trying to reproduce issues, you often want to use multiple versions of Poetry at the same time.
	[pipx](https://pypa.github.io/pipx/) makes this easy to do:
	```sh
	pipx install --suffix @1.2.1 'poetry==1.2.1'
	pipx install --suffix @1.3.0rc1 'poetry==1.3.0rc1'
	pipx install --suffix @main 'poetry @ git+https://github.com/python-poetry/poetry'
	pipx install --suffix @local '/path/to/local/clone/of/poetry'
	# now you can use any of the chosen versions of Poetry with their configured suffix, e.g.
	poetry@main --version
	```
	{{% note %}}
	Do not forget to `pipx upgrade poetry@main` before using it, to make sure you have the latest changes.
	{{% /note %}}
	{{% note %}}
	This mechanism can also be used to test pull requests by using GitHub's pull request remote refs:
	```sh
	pipx install --suffix @pr1234 git+https://github.com/python-poetry/poetry.git@refs/pull/1234/head
	```
	{{% /note %}}

pipx install --suffix @local /home/eric/Documents/github/poetry

# Then to get the latest changes from your local edits
pipx upgrade poetry@local

Pull Request Check List

Resolves: #10584

• Added tests for changed code.
• Updated documentation for changed code.
  • Documenation already exists at docs/repositories.md#L580-L589

Summary by Sourcery

Enhance the installation chooser error message to recommend running poetry cache clear --all . when stale caches persist after using no-cache options and note a future improvement for targeted cache clearing.

Enhancements:

• Suggest clearing the Poetry cache in the no-links-found error message after using --no-cache commands
• Add a FIXME note pointing to issue poetry cache clear should be able to clear all information for a single package #4438 for a future targeted cache-clearing command

Summary by Sourcery

Enhance the error message shown when no installation candidates are found after using --no-cache to recommend clearing the Poetry cache, and update tests to verify this new suggestion.

Enhancements:

• Suggest running poetry cache clear --all . in the no-links-found error after using --no-cache to refresh package info
• Add a FIXME note pointing to issue poetry cache clear should be able to clear all information for a single package #4438 for a future targeted cache-clearing command

Tests:

• Update chooser error tests to expect the new cache clear suggestion message

[sourcery-ai]

Reviewer's guide (collapsed on small PRs)

Reviewer's Guide

Enhance the installation chooser’s no-links-found error flow to recommend running poetry cache clear --all . after using --no-cache, note a future targeted cache-clear improvement, and update unit tests to verify this new suggestion.

Sequence diagram for enhanced error message suggesting cache clear after no-links-found

sequenceDiagram
actor User
participant "Poetry CLI"
participant "Chooser (_no_links_found_error)"
User->>"Poetry CLI": Run install/update with --no-cache
"Poetry CLI"->>"Chooser (_no_links_found_error)": No installation candidates found
"Chooser (_no_links_found_error)"->>User: Show error message with cache clear suggestion ("poetry cache clear --all .")

Loading

Class diagram for updated _no_links_found_error method in Chooser

classDiagram
class Chooser {
  +_no_links_found_error(package, source_hint)
}
Chooser : +Suggests cache clear command in error message
Chooser : +Notes future targeted cache clear improvement (FIXME)

Loading

File-Level Changes

Change	Details	Files
Augment no-links-found error message with cache-clear guidance and FIXME	Append suggestion to clear all caches via poetry cache clear --all . Insert FIXME referencing issue poetry cache clear should be able to clear all information for a single package #4438 for future per-package cache clearing	src/poetry/installation/chooser.py
Revise tests to assert the new cache-clear recommendation	Add lines in both occurrences of test_chooser_no_links_found_error to expect the cache-clear suggestion	tests/installation/test_chooser_errors.py

---

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 and they look great!

---

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

[radoering]

I just noticed that you propose poetry cache clear --all . and had a "Wait what? That works?!" moment.

After some digging I think using . is a bug and not a feature. It just works due to an implementation detail and will probably break if we change something, e.g. make cache names case insensitive. In other words, we should not propose it here. Apart from that I think it makes sense to have an option to clear all caches but that should be implemented in a decent way. At the moment, there does not seem to be any official cli option to clear all caches.

[MadLittleMods]

I just noticed that you propose poetry cache clear --all . and had a "Wait what? That works?!" moment.

After some digging I think using . is a bug and not a feature. It just works due to an implementation detail and will probably break if we change something, e.g. make cache names case insensitive.

I'm pretty sure I didn't make it up but I also don't see it in the docs today (trying to look with some hindsight).

I see that I first used it in #10304

It's mentioned in a ton of issues:

• cache:clear arguments are confusing #521 (comment)
• “poetry cache clear” failed to remove corrupted artifacts #6151
• Insufficient cache invalidation after Poetry upgrade causes lockfile diffs #7224
• Provide more information regarding --no-cache flag #6445 (comment)
• Intermittent Hash Validation Failures #7881
• Different lockfiles on different systems #10466 (comment)
• Poetry fails with GIT dependencies #10218 (comment)
• Unable to find installation candidates for <package name> #9832
• Cannot modify pyproject.toml: list index out of range #9781
• All poetry commands fail with [Errno 2] No such file or directory: 'python' #9461 (comment)
• Cannot install torch on MacOS: poetry selects 2.3.0 which is not available on Apple Silicon #9442 (comment)
• poetry can't find pyzmq #9325 (comment)
• Dependency resolution using Azure Package Feed no longer operates correctly #9301 (comment)
• (this list isn't exhaustive)

#9366 is in a similar vein

[radoering]

Thanks for listing all the mentions. I was not aware of that. Perhaps, we should pay attention not to break this workaround if it does not hurt too much. I will try to take a look if I can implement a more obvious solution to remove all caches, e.g. just call poetry cache clear --all without a specific cache.

[radoering]

@MadLittleMods With #10627 we can now just run poetry cache clear --all (without a trailing dot).

[MadLittleMods]

Thanks for the review and merge @radoering 🐏