sources: allow to configure the priority of PyPI

[radoering]

Pull Request Check List

Related to: #6713
Closes: #7430

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

Allow to configure the priority of PyPI (e.g. poetry source add pypi --priority explicit) and add a warning that PyPI will be disabled - or maybe set to explicit (the difference is only subtle) - automatically in a future version of Poetry if there is at least one custom source with another priority than explicit configured and that PyPI should be configured explicitly with a certain priority for forward compatibility in that case. (If there are no other sources configured nothing changes. You don't have to always configure PyPI explicitly.)

Target image

This goes beyond this PR, but helps to understand it.

In a future version of Poetry, PyPI will be disabled automatically if there is at least one custom source configured with another priority than explicit.

If you don't want PyPI to be disabled, you have to add it explicitly (poetry add source pypi). This adds PyPI to your pyproject.toml like any other source except that it's not allowed to define a url because its url is implicit and fix. You can set a certain priority.

Priority default will be removed since it is superfluous.

This PR

This PR allows to add PyPI explicitly via poetry add source pypi. (You can also give a certain priority.) You can make PyPI the highest priority, lowest priority or anything in between. You can also effectively disable it by adding it with priority explicit.

In pyproject.toml an explicitly configured PyPI looks the same as any other source except it has no url, e.g.:

[[tool.poetry.source]]
name = "PyPI"
priority = "primary"

If we detect a custom source with another priority than explicit and there is no source with priority default (i.e. if PyPI would be enabled implicitly despite of other sources), a deprecation warning is printed that gives the target image and what to do for now to avoid a breaking change:

                        "Warning: In a future version of Poetry, PyPI will be disabled"
                        " automatically if at least one custom source is configured"
                        " with another priority than 'explicit'. In order to avoid"
                        " a breaking change and make your pyproject.toml forward"
                        " compatible, add PyPI explicitly via 'poetry source add pypi'."
                        " By the way, this has the advantage that you can set the"
                        " priority of PyPI as with any other source."

This PR does NOT deprecate the priority default yet. Later, when we will have made the warning become true, we can deprecate default because it only influences the implicit PyPI like any other primary source and makes a source the first primary one. In other words, the priority default becomes absolutely superfluous.

I think I really like the target image (way better than #7430) and the clear transition, which should be as smooth as possible.

[radoering]

I also tried some fancy anyOf not pattern magic, which worked correctly, but always gave the following message for invalid combinations: [source.0] {'name': 'x'} is not valid under any of the given schemas

Thus, I decided to be permissive here and check for invalid combinations in create_package_source() in factory.py. This way, we get way better error messages if there is a PyPI with a url or another source without a url.

[github-actions]

Deploy preview for website ready!

✅ Preview
https://website-brxldqe1w-python-poetry.vercel.app

Built with commit e421c3a.
This pull request is being automatically deployed with vercel-action

[Secrus]

LGTM, some small nitpicks only

[github-actions]

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.