Docs: Specify the types of requirement pip supports (internal details)

What’s the problem this feature will solve? At the moment, there are a lot of subtle edge cases in what pip will accept as a “requirement” that are not well documented and/or are special cased in the code. There are a lot of adhoc terms (e.g., “direct requirement” and “unnamed requirement”) used in the code, and it is sometimes difficult to track down precise meanings.

Describe the solution you’d like Ideally, there should be a section in the documentation (or somewhere) that classifies all of the various “types” of thing that pip can be asked to install, and how they map to specific “requirement types” - part of the goal here should be to establish more consistent terminology, and have a central place where these terms are explained.

As noted above, terms like “direct requirement” and “unnamed requirement” would be good examples of terms that need clarification. Also, adding more clarity around how the requirement types pip handles map back to PEP 440 concepts would make it easier to reason about pip’s standards compliance.

Alternative Solutions Continue to document such details in the code, and/or infer behaviour from the code.

Additional context When building the new resolver, the interface will necessarily be based around passing a set of requirements from pip to the resolver. At the moment, a pip RequirementSet contains a lot of internal specifics, which would not make sense to include in an API that could be passed to a general resolver. Ideally the resolver API could be specified purely in terms of PEP 440 concepts (specifiers of the form NAME OP VERSION and direct references, NAME @ URL), but to do that we would need a clear mapping between pip’s concepts and the PEP’s.

This issue is intended as a place for discussion on how to model pip’s idea of requirements in a standards-compliant way.

[pfmoore]

Hmm, checking up on ResolveLib, which was on my TODO list of things to read up on, it looks like it fleshes out some of these abstractions already.

[pfmoore]

IMO if the source code is aligned with that model then it will be essentially self-documenting

Well, we should include the graph in our docs somewhere, at least - if only to help out people like me who can’t hold the full object graph in our heads 😉