Poetry currently will look up packages in every source, even when unnecessary due to a source = constraint on a dependency, or if the dependency was already found. This behavior often surprises users (though it was originally modeled on pip). Ostensibly, secondary is the solution to this -- however, it merely pushes the repository further back in the search order and does little to address the user complaints/confusion. As such, we should deprecate it and replace it with new options that better match user expectations.

I think, to preserve backwards compatibility, the long-term path forward is probably two different options (in my example, supplemental and private). I would propose something like the following, as an overview of behaviors:

• No options means that the repository overlays PyPI, but we will still fall back to PyPI if necessary (e.g. suitable for internal mirrors), pip --extra-index-url-style. This is known internally as primary, and is the current behavior.
• default = true means that the repository replaces PyPI, pip --index-url-style. This is the current behavior.
• supplemental = true means that this source is only consulted after a lookup in the default (implicitly PyPI unless configured otherwise) and primary sources fail.
• private = true means that the repo will only be considered for packages that are explicitly configured with source =, and should be preferred by users for private packages to avoid dependency confusion attacks.

secondary = true would be kept around as a deprecated option (likely with a warning), and would maintain the legacy behavior of being searched exhaustively for backwards compatibility.

Originally #5984 (comment)