docs: def transform_binary_dist(self, archive_path):
          """
          Transform binary distributions into a form that can be cached for future use.
  
          :param archive_path: The pathname of the original binary distribution archive.
          :returns: An iterable of tuples with two values each:
  
                    1. A :class:`tarfile.TarInfo` object.
                    2. A file-like object.
  
          This method transforms a binary distribution archive created by
          :func:`build_binary_dist()` into a form that can be cached for future
          use. This comes down to making the pathnames inside the archive
          relative to the `prefix` that the binary distribution was built for.
          """
          # Copy the tar archive file by file so we can rewrite the pathnames.
          logger.debug("Transforming binary distribution: %s.", archive_path)
          archive = tarfile.open(archive_path, 'r')
          for member in archive.getmembers():
              # Some source distribution archives on PyPI that are distributed as ZIP
              # archives contain really weird permissions: the world readable bit is
              # missing. I've encountered this with the httplib2 (0.9) and
              # google-api-python-client (1.2) packages. I assume this is a bug of
              # some kind in the packaging process on "their" side.
              if member.mode & stat.S_IXUSR:
                  # If the owner has execute permissions we'll give everyone read and
                  # execute permissions (only the owner gets write permissions).
                  member.mode = 0o755
              else:
                  # If the owner doesn't have execute permissions we'll give everyone
                  # read permissions (only the owner gets write permissions).
                  member.mode = 0o644
              # In my testing the `dumb' tar files created with the `python
              # setup.py bdist' and `python setup.py bdist_dumb' commands contain
              # pathnames that are relative to `/' in one way or another:
              #
              #  - In almost all cases the pathnames look like this:
              #
              #      ./home/peter/.virtualenvs/pip-accel/lib/python2.7/site-packages/pip_accel/__init__.py
              #
              #  - After working on pip-accel for several years I encountered
              #    a pathname like this (Python 2.6 on Mac OS X 10.10.5):
              #
              #      Users/peter/.virtualenvs/pip-accel/lib/python2.6/site-packages/pip_accel/__init__.py
              #
              # Both of the above pathnames are relative to `/' but in different
              # ways :-). The following normpath(join('/', ...))) pathname
              # manipulation logic is intended to handle both cases.
              original_pathname = member.name
              absolute_pathname = os.path.normpath(os.path.join('/', original_pathname))
              if member.isdev():
                  logger.warn("Ignoring device file: %s.", absolute_pathname)
              elif not member.isdir():
                  modified_pathname = os.path.relpath(absolute_pathname, self.config.install_prefix)
                  if os.path.isabs(modified_pathname):
                      logger.warn("Failed to transform pathname in binary distribution"
                                  " to relative path! (original: %r, modified: %r)",
                                  original_pathname, modified_pathname)
                  else:
                      # Rewrite /usr/local to /usr (same goes for all prefixes of course).
                      modified_pathname = re.sub('^local/', '', modified_pathname)
                      # Rewrite /dist-packages/ to /site-packages/. For details see
                      # https://wiki.debian.org/Python#Deviations_from_upstream.
                      if self.config.on_debian:
                          modified_pathname = modified_pathname.replace('/dist-packages/', '/site-packages/')
                      # Enable operators to debug the transformation process.
                      logger.debug("Transformed %r -> %r.", original_pathname, modified_pathname)
                      # Get the file data from the input archive.
                      handle = archive.extractfile(original_pathname)
                      # Yield the modified metadata and a handle to the data.
                      member.name = modified_pathname
                      yield member, handle
          archive.close()