docs: def get_package_as_folder(dependency):
      """ This function downloads the given package / dependency and extracts
          the raw contents into a folder.
  
          Afterwards, it returns a tuple with the type of distribution obtained,
          and the temporary folder it extracted to. It is the caller's
          responsibility to delete the returned temp folder after use.
  
          Examples of returned values:
  
          ("source", "/tmp/pythonpackage-venv-e84toiwjw")
          ("wheel", "/tmp/pythonpackage-venv-85u78uj")
  
          What the distribution type will be depends on what pip decides to
          download.
      """
  
      venv_parent = tempfile.mkdtemp(
          prefix="pythonpackage-venv-"
      )
      try:
          # Create a venv to install into:
          try:
              if int(sys.version.partition(".")[0]) < 3:
                  # Python 2.x has no venv.
                  subprocess.check_output([
                      sys.executable,  # no venv conflict possible,
                                       # -> no need to use system python
                      "-m", "virtualenv",
                      "--python=" + _get_system_python_executable(),
                      os.path.join(venv_parent, 'venv')
                  ], cwd=venv_parent)
              else:
                  # On modern Python 3, use venv.
                  subprocess.check_output([
                      _get_system_python_executable(), "-m", "venv",
                      os.path.join(venv_parent, 'venv')
                  ], cwd=venv_parent)
          except subprocess.CalledProcessError as e:
              output = e.output.decode('utf-8', 'replace')
              raise ValueError(
                  'venv creation unexpectedly ' +
                  'failed. error output: ' + str(output)
              )
          venv_path = os.path.join(venv_parent, "venv")
  
          # Update pip and wheel in venv for latest feature support:
          try:
              filenotfounderror = FileNotFoundError
          except NameError:  # Python 2.
              filenotfounderror = OSError
          try:
              subprocess.check_output([
                  os.path.join(venv_path, "bin", "pip"),
                  "install", "-U", "pip", "wheel",
              ])
          except filenotfounderror:
              raise RuntimeError(
                  "venv appears to be missing pip. "
                  "did we fail to use a proper system python??\n"
                  "system python path detected: {}\n"
                  "os.environ['PATH']: {}".format(
                      _get_system_python_executable(),
                      os.environ.get("PATH", "")
                  )
              )
  
          # Create download subfolder:
          os.mkdir(os.path.join(venv_path, "download"))
  
          # Write a requirements.txt with our package and download:
          with open(os.path.join(venv_path, "requirements.txt"),
                    "w", encoding="utf-8"
                   ) as f:
              def to_unicode(s):  # Needed for Python 2.
                  try:
                      return s.decode("utf-8")
                  except AttributeError:
                      return s
              f.write(to_unicode(transform_dep_for_pip(dependency)))
          try:
              subprocess.check_output(
                  [
                      os.path.join(venv_path, "bin", "pip"),
                      "download", "--no-deps", "-r", "../requirements.txt",
                      "-d", os.path.join(venv_path, "download")
                  ],
                  stderr=subprocess.STDOUT,
                  cwd=os.path.join(venv_path, "download")
              )
          except subprocess.CalledProcessError as e:
              raise RuntimeError("package download failed: " + str(e.output))
  
          if len(os.listdir(os.path.join(venv_path, "download"))) == 0:
              # No download. This can happen if the dependency has a condition
              # which prohibits install in our environment.
              # (the "package ; ... conditional ... " type of condition)
              return (None, None)
  
          # Get the result and make sure it's an extracted directory:
          result_folder_or_file = os.path.join(
              venv_path, "download",
              os.listdir(os.path.join(venv_path, "download"))[0]
          )
          dl_type = "source"
          if not os.path.isdir(result_folder_or_file):
              # Must be an archive.
              if result_folder_or_file.endswith((".zip", ".whl")):
                  if result_folder_or_file.endswith(".whl"):
                      dl_type = "wheel"
                  with zipfile.ZipFile(result_folder_or_file) as f:
                      f.extractall(os.path.join(venv_path,
                                                "download", "extracted"
                                               ))
                      result_folder_or_file = os.path.join(
                          venv_path, "download", "extracted"
                      )
              elif result_folder_or_file.find(".tar.") > 0:
                  # Probably a tarball.
                  with tarfile.open(result_folder_or_file) as f:
                      f.extractall(os.path.join(venv_path,
                                                "download", "extracted"
                                               ))
                      result_folder_or_file = os.path.join(
                          venv_path, "download", "extracted"
                      )
              else:
                  raise RuntimeError(
                      "unknown archive or download " +
                      "type: " + str(result_folder_or_file)
                  )
  
          # If the result is hidden away in an additional subfolder,
          # descend into it:
          while os.path.isdir(result_folder_or_file) and \
                  len(os.listdir(result_folder_or_file)) == 1 and \
                  os.path.isdir(os.path.join(
                      result_folder_or_file,
                      os.listdir(result_folder_or_file)[0]
                  )):
              result_folder_or_file = os.path.join(
                  result_folder_or_file,
                  os.listdir(result_folder_or_file)[0]
              )
  
          # Copy result to new dedicated folder so we can throw away
          # our entire virtualenv nonsense after returning:
          result_path = tempfile.mkdtemp()
          shutil.rmtree(result_path)
          shutil.copytree(result_folder_or_file, result_path)
          return (dl_type, result_path)
      finally:
          shutil.rmtree(venv_parent)