refactor much of RequirementPreparer and add lengthy docs

Author: cosmicexplorer

src/pip/_internal/distributions/__init__.py

@@ -8,7 +8,14 @@
 def make_distribution_for_install_requirement(
     install_req: InstallRequirement,
 ) -> AbstractDistribution:
-    """Returns a Distribution for the given InstallRequirement"""
+    """Returns an AbstractDistribution for the given InstallRequirement.
+
+    As AbstractDistribution only covers installable artifacts, this method may only be
+    invoked at the conclusion of a resolve, when the RequirementPreparer has downloaded
+    the file corresponding to the resolved dist. Commands which intend to consume
+    metadata-only resolves without downloading should not call this method or
+    consume AbstractDistribution objects.
+    """
     # Only pre-installed requirements will have a .satisfied_by dist.
     if install_req.satisfied_by:
         return InstalledDistribution(install_req)