parameters: (dist_path, fix_zipimporter_caches)
docstring: Fix any globally cached `dist_path` related data
  
      `dist_path` should be a path of a newly installed egg distribution (zipped
      or unzipped).
  
      sys.path_importer_cache contains finder objects that have been cached when
      importing data from the original distribution. Any such finders need to be
      cleared since the replacement distribution might be packaged differently,
      e.g. a zipped egg distribution might get replaced with an unzipped egg
      folder or vice versa. Having the old finders cached may then cause Python
      to attempt loading modules from the replacement distribution using an
      incorrect loader.
  
      zipimport.zipimporter objects are Python loaders charged with importing
      data packaged inside zip archives. If stale loaders referencing the
      original distribution, are left behind, they can fail to load modules from
      the replacement distribution. E.g. if an old zipimport.zipimporter instance
      is used to load data from a new zipped egg archive, it may cause the
      operation to attempt to locate the requested data in the wrong location -
      one indicated by the original distribution's zip archive directory
      information. Such an operation may then fail outright, e.g. report having
      read a 'bad local file header', or even worse, it may fail silently &
      return invalid data.
  
      zipimport._zip_directory_cache contains cached zip archive directory
      information for all existing zipimport.zipimporter instances and all such
      instances connected to the same archive share the same cached directory
      information.
  
      If asked, and the underlying Python implementation allows it, we can fix
      all existing zipimport.zipimporter instances instead of having to track
      them down and remove them one by one, by updating their shared cached zip
      archive directory information. This, of course, assumes that the
      replacement distribution is packaged as a zipped egg.
  
      If not asked to fix existing zipimport.zipimporter instances, we still do
      our best to clear any remaining zipimport.zipimporter related cached data
      that might somehow later get used when attempting to load data from the new
      distribution and thus cause such load operations to fail. Note that when
      tracking down such remaining stale data, we can not catch every conceivable
      usage from here, and we clear only those that we know of and have found to
      cause problems if left alive. Any remaining caches should be updated by
      whomever is in charge of maintaining them, i.e. they should be ready to
      handle us replacing their zip archives with new distributions at runtime.
docstring_summary: Fix any globally cached `dist_path` related data
docstring_tokens: Fix any globally cached dist_path related data
function: def update_dist_caches(dist_path, fix_zipimporter_caches):
      """
      Fix any globally cached `dist_path` related data
  
      `dist_path` should be a path of a newly installed egg distribution (zipped
      or unzipped).
  
      sys.path_importer_cache contains finder objects that have been cached when
      importing data from the original distribution. Any such finders need to be
      cleared since the replacement distribution might be packaged differently,
      e.g. a zipped egg distribution might get replaced with an unzipped egg
      folder or vice versa. Having the old finders cached may then cause Python
      to attempt loading modules from the replacement distribution using an
      incorrect loader.
  
      zipimport.zipimporter objects are Python loaders charged with importing
      data packaged inside zip archives. If stale loaders referencing the
      original distribution, are left behind, they can fail to load modules from
      the replacement distribution. E.g. if an old zipimport.zipimporter instance
      is used to load data from a new zipped egg archive, it may cause the
      operation to attempt to locate the requested data in the wrong location -
      one indicated by the original distribution's zip archive directory
      information. Such an operation may then fail outright, e.g. report having
      read a 'bad local file header', or even worse, it may fail silently &
      return invalid data.
  
      zipimport._zip_directory_cache contains cached zip archive directory
      information for all existing zipimport.zipimporter instances and all such
      instances connected to the same archive share the same cached directory
      information.
  
      If asked, and the underlying Python implementation allows it, we can fix
      all existing zipimport.zipimporter instances instead of having to track
      them down and remove them one by one, by updating their shared cached zip
      archive directory information. This, of course, assumes that the
      replacement distribution is packaged as a zipped egg.
  
      If not asked to fix existing zipimport.zipimporter instances, we still do
      our best to clear any remaining zipimport.zipimporter related cached data
      that might somehow later get used when attempting to load data from the new
      distribution and thus cause such load operations to fail. Note that when
      tracking down such remaining stale data, we can not catch every conceivable
      usage from here, and we clear only those that we know of and have found to
      cause problems if left alive. Any remaining caches should be updated by
      whomever is in charge of maintaining them, i.e. they should be ready to
      handle us replacing their zip archives with new distributions at runtime.
  
      """
      # There are several other known sources of stale zipimport.zipimporter
      # instances that we do not clear here, but might if ever given a reason to
      # do so:
      # * Global setuptools pkg_resources.working_set (a.k.a. 'master working
      # set') may contain distributions which may in turn contain their
      #   zipimport.zipimporter loaders.
      # * Several zipimport.zipimporter loaders held by local variables further
      #   up the function call stack when running the setuptools installation.
      # * Already loaded modules may have their __loader__ attribute set to the
      #   exact loader instance used when importing them. Python 3.4 docs state
      #   that this information is intended mostly for introspection and so is
      #   not expected to cause us problems.
      normalized_path = normalize_path(dist_path)
      _uncache(normalized_path, sys.path_importer_cache)
      if fix_zipimporter_caches:
          _replace_zip_directory_cache_data(normalized_path)
      else:
          # Here, even though we do not want to fix existing and now stale
          # zipimporter cache information, we still want to remove it. Related to
          # Python's zip archive directory information cache, we clear each of
          # its stale entries in two phases:
          #   1. Clear the entry so attempting to access zip archive information
          #      via any existing stale zipimport.zipimporter instances fails.
          #   2. Remove the entry from the cache so any newly constructed
          #      zipimport.zipimporter instances do not end up using old stale
          #      zip archive directory information.
          # This whole stale data removal step does not seem strictly necessary,
          # but has been left in because it was done before we started replacing
          # the zip archive directory information cache content if possible, and
          # there are no relevant unit tests that we can depend on to tell us if
          # this is really needed.
          _remove_and_clear_zip_directory_cache_data(normalized_path)
function_tokens: def update_dist_caches ( dist_path , fix_zipimporter_caches ) : # There are several other known sources of stale zipimport.zipimporter # instances that we do not clear here, but might if ever given a reason to # do so: # * Global setuptools pkg_resources.working_set (a.k.a. 'master working # set') may contain distributions which may in turn contain their #   zipimport.zipimporter loaders. # * Several zipimport.zipimporter loaders held by local variables further #   up the function call stack when running the setuptools installation. # * Already loaded modules may have their __loader__ attribute set to the #   exact loader instance used when importing them. Python 3.4 docs state #   that this information is intended mostly for introspection and so is #   not expected to cause us problems. normalized_path = normalize_path ( dist_path ) _uncache ( normalized_path , sys . path_importer_cache ) if fix_zipimporter_caches : _replace_zip_directory_cache_data ( normalized_path ) else : # Here, even though we do not want to fix existing and now stale # zipimporter cache information, we still want to remove it. Related to # Python's zip archive directory information cache, we clear each of # its stale entries in two phases: #   1. Clear the entry so attempting to access zip archive information #      via any existing stale zipimport.zipimporter instances fails. #   2. Remove the entry from the cache so any newly constructed #      zipimport.zipimporter instances do not end up using old stale #      zip archive directory information. # This whole stale data removal step does not seem strictly necessary, # but has been left in because it was done before we started replacing # the zip archive directory information cache content if possible, and # there are no relevant unit tests that we can depend on to tell us if # this is really needed. _remove_and_clear_zip_directory_cache_data ( normalized_path )