Tooltron

"""Package resource API

--------------------

A resource is a logical file contained within a package, or a logical

subdirectory thereof.  The package resource API expects resource names

to have their path parts separated with ``/``, *not* whatever the local

path separator is.  Do not use os.path operations to manipulate resource

names being passed into the API.

The package resource API is designed to work with normal filesystem packages,

.egg files, and unpacked .egg files.  It can also work in a limited way with

.zip files and with custom PEP 302 loaders that support the ``get_data()``

method.

"""

import sys, os, zipimport, time, re, imp, types

from urlparse import urlparse, urlunparse

try:

    frozenset

except NameError:

    from sets import ImmutableSet as frozenset

# capture these to bypass sandboxing

from os import utime

try:

    from os import mkdir, rename, unlink

    WRITE_SUPPORT = True

except ImportError:

    # no write support, probably under GAE

    WRITE_SUPPORT = False

from os import open as os_open

from os.path import isdir, split

# This marker is used to simplify the process that checks is the

# setuptools package was installed by the Setuptools project

# or by the Distribute project, in case Setuptools creates

# a distribution with the same version.

#

# The bootstrapping script for instance, will check if this

# attribute is present to decide wether to reinstall the package

_distribute = True

def _bypass_ensure_directory(name, mode=0777):

    # Sandbox-bypassing version of ensure_directory()

    if not WRITE_SUPPORT:

        raise IOError('"os.mkdir" not supported on this platform.')

    dirname, filename = split(name)

    if dirname and filename and not isdir(dirname):

        _bypass_ensure_directory(dirname)

        mkdir(dirname, mode)

_state_vars = {}

def _declare_state(vartype, **kw):

    g = globals()

    for name, val in kw.iteritems():

        g[name] = val

        _state_vars[name] = vartype

def __getstate__():

    state = {}

    g = globals()

    for k, v in _state_vars.iteritems():

        state[k] = g['_sget_'+v](g[k])

    return state

def __setstate__(state):

    g = globals()

    for k, v in state.iteritems():

        g['_sset_'+_state_vars[k]](k, g[k], v)

    return state

def _sget_dict(val):

    return val.copy()

def _sset_dict(key, ob, state):

    ob.clear()

    ob.update(state)

def _sget_object(val):

    return val.__getstate__()

def _sset_object(key, ob, state):

    ob.__setstate__(state)

_sget_none = _sset_none = lambda *args: None

def get_supported_platform():

    """Return this platform's maximum compatible version.

    distutils.util.get_platform() normally reports the minimum version

    of Mac OS X that would be required to *use* extensions produced by

    distutils.  But what we want when checking compatibility is to know the

    version of Mac OS X that we are *running*.  To allow usage of packages that

    explicitly require a newer version of Mac OS X, we must also know the

    current version of the OS.

    If this condition occurs for any other platform with a version in its

    platform strings, this function should be extended accordingly.

    """

    plat = get_build_platform(); m = macosVersionString.match(plat)

    if m is not None and sys.platform == "darwin":

        try:

            plat = 'macosx-%s-%s' % ('.'.join(_macosx_vers()[:2]), m.group(3))

        except ValueError:

            pass    # not Mac OS X

    return plat

__all__ = [

    # Basic resource access and distribution/entry point discovery

    'require', 'run_script', 'get_provider',  'get_distribution',

    'load_entry_point', 'get_entry_map', 'get_entry_info', 'iter_entry_points',

    'resource_string', 'resource_stream', 'resource_filename',

    'resource_listdir', 'resource_exists', 'resource_isdir',

    # Environmental control

    'declare_namespace', 'working_set', 'add_activation_listener',

    'find_distributions', 'set_extraction_path', 'cleanup_resources',

    'get_default_cache',

    # Primary implementation classes

    'Environment', 'WorkingSet', 'ResourceManager',

    'Distribution', 'Requirement', 'EntryPoint',

    # Exceptions

    'ResolutionError','VersionConflict','DistributionNotFound','UnknownExtra',

    'ExtractionError',

    # Parsing functions and string utilities

    'parse_requirements', 'parse_version', 'safe_name', 'safe_version',

    'get_platform', 'compatible_platforms', 'yield_lines', 'split_sections',

    'safe_extra', 'to_filename',

    # filesystem utilities

    'ensure_directory', 'normalize_path',

    # Distribution "precedence" constants

    'EGG_DIST', 'BINARY_DIST', 'SOURCE_DIST', 'CHECKOUT_DIST', 'DEVELOP_DIST',

    # "Provider" interfaces, implementations, and registration/lookup APIs

    'IMetadataProvider', 'IResourceProvider', 'FileMetadata',

    'PathMetadata', 'EggMetadata', 'EmptyProvider', 'empty_provider',

    'NullProvider', 'EggProvider', 'DefaultProvider', 'ZipProvider',

    'register_finder', 'register_namespace_handler', 'register_loader_type',

    'fixup_namespace_packages', 'get_importer',

    # Deprecated/backward compatibility only

    'run_main', 'AvailableDistributions',

]

class ResolutionError(Exception):

    """Abstract base for dependency resolution errors"""

    def __repr__(self):

        return self.__class__.__name__+repr(self.args)

class VersionConflict(ResolutionError):

    """An already-installed version conflicts with the requested version"""

class DistributionNotFound(ResolutionError):

    """A requested distribution was not found"""

class UnknownExtra(ResolutionError):

    """Distribution doesn't have an "extra feature" of the given name"""

_provider_factories = {}

PY_MAJOR = sys.version[:3]

EGG_DIST    = 3

BINARY_DIST = 2

SOURCE_DIST = 1

CHECKOUT_DIST = 0

DEVELOP_DIST = -1

def register_loader_type(loader_type, provider_factory):

    """Register `provider_factory` to make providers for `loader_type`

    `loader_type` is the type or class of a PEP 302 ``module.__loader__``,

    and `provider_factory` is a function that, passed a *module* object,

    returns an ``IResourceProvider`` for that module.

    """

    _provider_factories[loader_type] = provider_factory

def get_provider(moduleOrReq):

    """Return an IResourceProvider for the named module or requirement"""

    if isinstance(moduleOrReq,Requirement):

        return working_set.find(moduleOrReq) or require(str(moduleOrReq))[0]

    try:

        module = sys.modules[moduleOrReq]

    except KeyError:

        __import__(moduleOrReq)

        module = sys.modules[moduleOrReq]

    loader = getattr(module, '__loader__', None)

    return _find_adapter(_provider_factories, loader)(module)

def _macosx_vers(_cache=[]):

    if not _cache:

        import platform

        version = platform.mac_ver()[0]

        # fallback for MacPorts

        if version == '':

            import plistlib

            plist = '/System/Library/CoreServices/SystemVersion.plist'

            if os.path.exists(plist):

                if hasattr(plistlib, 'readPlist'):

                    plist_content = plistlib.readPlist(plist)

                    if 'ProductVersion' in plist_content:

                        version = plist_content['ProductVersion']

        _cache.append(version.split('.'))

    return _cache[0]

def _macosx_arch(machine):

    return {'PowerPC':'ppc', 'Power_Macintosh':'ppc'}.get(machine,machine)

def get_build_platform():

    """Return this platform's string for platform-specific distributions

    XXX Currently this is the same as ``distutils.util.get_platform()``, but it

    needs some hacks for Linux and Mac OS X.

    """

    try:

        from distutils.util import get_platform

    except ImportError:

        from sysconfig import get_platform

    plat = get_platform()

    if sys.platform == "darwin" and not plat.startswith('macosx-'):

        try:

            version = _macosx_vers()

            machine = os.uname()[4].replace(" ", "_")

            return "macosx-%d.%d-%s" % (int(version[0]), int(version[1]),

                _macosx_arch(machine))

        except ValueError:

            # if someone is running a non-Mac darwin system, this will fall

            # through to the default implementation

            pass

    return plat

macosVersionString = re.compile(r"macosx-(\d+)\.(\d+)-(.*)")

darwinVersionString = re.compile(r"darwin-(\d+)\.(\d+)\.(\d+)-(.*)")

get_platform = get_build_platform   # XXX backward compat

def compatible_platforms(provided,required):

    """Can code for the `provided` platform run on the `required` platform?

    Returns true if either platform is ``None``, or the platforms are equal.

    XXX Needs compatibility checks for Linux and other unixy OSes.

    """

    if provided is None or required is None or provided==required:

        return True     # easy case

    # Mac OS X special cases

    reqMac = macosVersionString.match(required)

    if reqMac:

        provMac = macosVersionString.match(provided)

        # is this a Mac package?

        if not provMac:

            # this is backwards compatibility for packages built before

            # setuptools 0.6. All packages built after this point will

            # use the new macosx designation.

            provDarwin = darwinVersionString.match(provided)

            if provDarwin:

                dversion = int(provDarwin.group(1))

                macosversion = "%s.%s" % (reqMac.group(1), reqMac.group(2))

                if dversion == 7 and macosversion >= "10.3" or \

                    dversion == 8 and macosversion >= "10.4":

                    #import warnings

                    #warnings.warn("Mac eggs should be rebuilt to "

                    #    "use the macosx designation instead of darwin.",

                    #    category=DeprecationWarning)

                    return True

            return False    # egg isn't macosx or legacy darwin

        # are they the same major version and machine type?

        if provMac.group(1) != reqMac.group(1) or \

            provMac.group(3) != reqMac.group(3):

            return False

        # is the required OS major update >= the provided one?

        if int(provMac.group(2)) > int(reqMac.group(2)):

            return False

        return True

    # XXX Linux and other platforms' special cases should go here

    return False

def run_script(dist_spec, script_name):

    """Locate distribution `dist_spec` and run its `script_name` script"""

    ns = sys._getframe(1).f_globals

    name = ns['__name__']

    ns.clear()

    ns['__name__'] = name

    require(dist_spec)[0].run_script(script_name, ns)

run_main = run_script   # backward compatibility

def get_distribution(dist):

    """Return a current distribution object for a Requirement or string"""

    if isinstance(dist,basestring): dist = Requirement.parse(dist)

    if isinstance(dist,Requirement): dist = get_provider(dist)

    if not isinstance(dist,Distribution):

        raise TypeError("Expected string, Requirement, or Distribution", dist)

    return dist

def load_entry_point(dist, group, name):

    """Return `name` entry point of `group` for `dist` or raise ImportError"""

    return get_distribution(dist).load_entry_point(group, name)

def get_entry_map(dist, group=None):

    """Return the entry point map for `group`, or the full entry map"""

    return get_distribution(dist).get_entry_map(group)

def get_entry_info(dist, group, name):

    """Return the EntryPoint object for `group`+`name`, or ``None``"""

    return get_distribution(dist).get_entry_info(group, name)

class IMetadataProvider:

    def has_metadata(name):

        """Does the package's distribution contain the named metadata?"""

    def get_metadata(name):

        """The named metadata resource as a string"""

    def get_metadata_lines(name):

        """Yield named metadata resource as list of non-blank non-comment lines

       Leading and trailing whitespace is stripped from each line, and lines

       with ``#`` as the first non-blank character are omitted."""

    def metadata_isdir(name):

        """Is the named metadata a directory?  (like ``os.path.isdir()``)"""

    def metadata_listdir(name):

        """List of metadata names in the directory (like ``os.listdir()``)"""

    def run_script(script_name, namespace):

        """Execute the named script in the supplied namespace dictionary"""

class IResourceProvider(IMetadataProvider):

    """An object that provides access to package resources"""

    def get_resource_filename(manager, resource_name):

        """Return a true filesystem path for `resource_name`

        `manager` must be an ``IResourceManager``"""

    def get_resource_stream(manager, resource_name):

        """Return a readable file-like object for `resource_name`

        `manager` must be an ``IResourceManager``"""

    def get_resource_string(manager, resource_name):

        """Return a string containing the contents of `resource_name`

        `manager` must be an ``IResourceManager``"""

    def has_resource(resource_name):

        """Does the package contain the named resource?"""

    def resource_isdir(resource_name):

        """Is the named resource a directory?  (like ``os.path.isdir()``)"""

    def resource_listdir(resource_name):

        """List of resource names in the directory (like ``os.listdir()``)"""

class WorkingSet(object):

    """A collection of active distributions on sys.path (or a similar list)"""

    def __init__(self, entries=None):

        """Create working set from list of path entries (default=sys.path)"""

        self.entries = []

        self.entry_keys = {}

        self.by_key = {}

        self.callbacks = []

        if entries is None:

            entries = sys.path

        for entry in entries:

            self.add_entry(entry)

    def add_entry(self, entry):

        """Add a path item to ``.entries``, finding any distributions on it

        ``find_distributions(entry,True)`` is used to find distributions

        corresponding to the path entry, and they are added.  `entry` is

        always appended to ``.entries``, even if it is already present.

        (This is because ``sys.path`` can contain the same value more than

        once, and the ``.entries`` of the ``sys.path`` WorkingSet should always

        equal ``sys.path``.)

        """

        self.entry_keys.setdefault(entry, [])

        self.entries.append(entry)

        for dist in find_distributions(entry, True):

            self.add(dist, entry, False)

    def __contains__(self,dist):

        """True if `dist` is the active distribution for its project"""

        return self.by_key.get(dist.key) == dist

    def find(self, req):

        """Find a distribution matching requirement `req`

        If there is an active distribution for the requested project, this

        returns it as long as it meets the version requirement specified by

        `req`.  But, if there is an active distribution for the project and it

        does *not* meet the `req` requirement, ``VersionConflict`` is raised.

        If there is no active distribution for the requested project, ``None``

        is returned.

        """

        dist = self.by_key.get(req.key)

        if dist is not None and dist not in req:

            raise VersionConflict(dist,req)     # XXX add more info

        else:

            return dist

    def iter_entry_points(self, group, name=None):

        """Yield entry point objects from `group` matching `name`

        If `name` is None, yields all entry points in `group` from all

        distributions in the working set, otherwise only ones matching

        both `group` and `name` are yielded (in distribution order).

        """

        for dist in self:

            entries = dist.get_entry_map(group)

            if name is None:

                for ep in entries.values():

                    yield ep

            elif name in entries:

                yield entries[name]

    def run_script(self, requires, script_name):

        """Locate distribution for `requires` and run `script_name` script"""

        ns = sys._getframe(1).f_globals

        name = ns['__name__']

        ns.clear()

        ns['__name__'] = name

        self.require(requires)[0].run_script(script_name, ns)

    def __iter__(self):

        """Yield distributions for non-duplicate projects in the working set

        The yield order is the order in which the items' path entries were

        added to the working set.

        """

        seen = {}

        for item in self.entries:

            for key in self.entry_keys[item]:

                if key not in seen:

                    seen[key]=1

                    yield self.by_key[key]

    def add(self, dist, entry=None, insert=True):

        """Add `dist` to working set, associated with `entry`

        If `entry` is unspecified, it defaults to the ``.location`` of `dist`.

        On exit from this routine, `entry` is added to the end of the working

        set's ``.entries`` (if it wasn't already present).

        `dist` is only added to the working set if it's for a project that

        doesn't already have a distribution in the set.  If it's added, any

        callbacks registered with the ``subscribe()`` method will be called.

        """

        if insert:

            dist.insert_on(self.entries, entry)

        if entry is None:

            entry = dist.location

        keys = self.entry_keys.setdefault(entry,[])

        keys2 = self.entry_keys.setdefault(dist.location,[])

        if dist.key in self.by_key:

            return      # ignore hidden distros

        self.by_key[dist.key] = dist

        if dist.key not in keys:

            keys.append(dist.key)

        if dist.key not in keys2:

            keys2.append(dist.key)

        self._added_new(dist)

    def resolve(self, requirements, env=None, installer=None, replacement=True):

        """List all distributions needed to (recursively) meet `requirements`

        `requirements` must be a sequence of ``Requirement`` objects.  `env`,

        if supplied, should be an ``Environment`` instance.  If

        not supplied, it defaults to all distributions available within any

        entry or distribution in the working set.  `installer`, if supplied,

        will be invoked with each requirement that cannot be met by an

        already-installed distribution; it should return a ``Distribution`` or

        ``None``.

        """

        requirements = list(requirements)[::-1]  # set up the stack

        processed = {}  # set of processed requirements

        best = {}  # key -> dist

        to_activate = []

        while requirements:

            req = requirements.pop(0)   # process dependencies breadth-first

            if _override_setuptools(req) and replacement:

                req = Requirement.parse('distribute')

            if req in processed:

                # Ignore cyclic or redundant dependencies

                continue

            dist = best.get(req.key)

            if dist is None:

                # Find the best distribution and add it to the map

                dist = self.by_key.get(req.key)

                if dist is None:

                    if env is None:

                        env = Environment(self.entries)

                    dist = best[req.key] = env.best_match(req, self, installer)

                    if dist is None:

                        #msg = ("The '%s' distribution was not found on this "

                        #       "system, and is required by this application.")

                        #raise DistributionNotFound(msg % req)

                        # unfortunately, zc.buildout uses a str(err)

                        # to get the name of the distribution here..

                        raise DistributionNotFound(req)

                to_activate.append(dist)

            if dist not in req:

                # Oops, the "best" so far conflicts with a dependency

                raise VersionConflict(dist,req) # XXX put more info here

            requirements.extend(dist.requires(req.extras)[::-1])

            processed[req] = True

        return to_activate    # return list of distros to activate

    def find_plugins(self,

        plugin_env, full_env=None, installer=None, fallback=True

    ):

        """Find all activatable distributions in `plugin_env`

        Example usage::

            distributions, errors = working_set.find_plugins(

                Environment(plugin_dirlist)

            )

            map(working_set.add, distributions)  # add plugins+libs to sys.path

            print 'Could not load', errors        # display errors

        The `plugin_env` should be an ``Environment`` instance that contains

        only distributions that are in the project's "plugin directory" or

        directories. The `full_env`, if supplied, should be an ``Environment``

        contains all currently-available distributions.  If `full_env` is not

        supplied, one is created automatically from the ``WorkingSet`` this

        method is called on, which will typically mean that every directory on

        ``sys.path`` will be scanned for distributions.

        `installer` is a standard installer callback as used by the

        ``resolve()`` method. The `fallback` flag indicates whether we should

        attempt to resolve older versions of a plugin if the newest version

        cannot be resolved.

        This method returns a 2-tuple: (`distributions`, `error_info`), where

        `distributions` is a list of the distributions found in `plugin_env`

        that were loadable, along with any other distributions that are needed

        to resolve their dependencies.  `error_info` is a dictionary mapping

        unloadable plugin distributions to an exception instance describing the

        error that occurred. Usually this will be a ``DistributionNotFound`` or

        ``VersionConflict`` instance.

        """

        plugin_projects = list(plugin_env)

        plugin_projects.sort()  # scan project names in alphabetic order

        error_info = {}

        distributions = {}

        if full_env is None:

            env = Environment(self.entries)

            env += plugin_env

        else:

            env = full_env + plugin_env

        shadow_set = self.__class__([])

        map(shadow_set.add, self)   # put all our entries in shadow_set

        for project_name in plugin_projects:

            for dist in plugin_env[project_name]:

                req = [dist.as_requirement()]

                try:

                    resolvees = shadow_set.resolve(req, env, installer)

                except ResolutionError,v:

                    error_info[dist] = v    # save error info

                    if fallback:

                        continue    # try the next older version of project

                    else:

                        break       # give up on this project, keep going

                else:

                    map(shadow_set.add, resolvees)

                    distributions.update(dict.fromkeys(resolvees))

                    # success, no need to try any more versions of this project

                    break

        distributions = list(distributions)

        distributions.sort()

        return distributions, error_info

    def require(self, *requirements):

        """Ensure that distributions matching `requirements` are activated

        `requirements` must be a string or a (possibly-nested) sequence

        thereof, specifying the distributions and versions required.  The

        return value is a sequence of the distributions that needed to be

        activated to fulfill the requirements; all relevant distributions are

        included, even if they were already activated in this working set.

        """

        needed = self.resolve(parse_requirements(requirements))

        for dist in needed:

            self.add(dist)

        return needed

    def subscribe(self, callback):

        """Invoke `callback` for all distributions (including existing ones)"""

        if callback in self.callbacks:

            return

        self.callbacks.append(callback)

        for dist in self:

            callback(dist)

    def _added_new(self, dist):

        for callback in self.callbacks:

            callback(dist)

    def __getstate__(self):

        return (self.entries[:], self.entry_keys.copy(), self.by_key.copy(),

                self.callbacks[:])

    def __setstate__(self, (entries, keys, by_key, callbacks)):

        self.entries = entries[:]

        self.entry_keys = keys.copy()

        self.by_key = by_key.copy()

        self.callbacks = callbacks[:]

class Environment(object):

    """Searchable snapshot of distributions on a search path"""

    def __init__(self, search_path=None, platform=get_supported_platform(), python=PY_MAJOR):

        """Snapshot distributions available on a search path

        Any distributions found on `search_path` are added to the environment.

        `search_path` should be a sequence of ``sys.path`` items.  If not

        supplied, ``sys.path`` is used.

        `platform` is an optional string specifying the name of the platform

        that platform-specific distributions must be compatible with.  If

        unspecified, it defaults to the current platform.  `python` is an

        optional string naming the desired version of Python (e.g. ``'2.4'``);

        it defaults to the current version.

        You may explicitly set `platform` (and/or `python`) to ``None`` if you

        wish to map *all* distributions, not just those compatible with the

        running platform or Python version.

        """

        self._distmap = {}

        self._cache = {}

        self.platform = platform

        self.python = python

        self.scan(search_path)

    def can_add(self, dist):

        """Is distribution `dist` acceptable for this environment?

        The distribution must match the platform and python version

        requirements specified when this environment was created, or False

        is returned.

        """

        return (self.python is None or dist.py_version is None

            or dist.py_version==self.python) \

           and compatible_platforms(dist.platform,self.platform)

    def remove(self, dist):

        """Remove `dist` from the environment"""

        self._distmap[dist.key].remove(dist)

    def scan(self, search_path=None):

        """Scan `search_path` for distributions usable in this environment

        Any distributions found are added to the environment.

        `search_path` should be a sequence of ``sys.path`` items.  If not

        supplied, ``sys.path`` is used.  Only distributions conforming to

        the platform/python version defined at initialization are added.

        """

        if search_path is None:

            search_path = sys.path

        for item in search_path:

            for dist in find_distributions(item):

                self.add(dist)

    def __getitem__(self,project_name):

        """Return a newest-to-oldest list of distributions for `project_name`

        """

        try:

            return self._cache[project_name]

        except KeyError:

            project_name = project_name.lower()

            if project_name not in self._distmap:

                return []

        if project_name not in self._cache:

            dists = self._cache[project_name] = self._distmap[project_name]

            _sort_dists(dists)

        return self._cache[project_name]

    def add(self,dist):

        """Add `dist` if we ``can_add()`` it and it isn't already added"""

        if self.can_add(dist) and dist.has_version():

            dists = self._distmap.setdefault(dist.key,[])

            if dist not in dists:

                dists.append(dist)

                if dist.key in self._cache:

                    _sort_dists(self._cache[dist.key])

    def best_match(self, req, working_set, installer=None):

        """Find distribution best matching `req` and usable on `working_set`

        This calls the ``find(req)`` method of the `working_set` to see if a

        suitable distribution is already active.  (This may raise

        ``VersionConflict`` if an unsuitable version of the project is already

        active in the specified `working_set`.)  If a suitable distribution

        isn't active, this method returns the newest distribution in the

        environment that meets the ``Requirement`` in `req`.  If no suitable

        distribution is found, and `installer` is supplied, then the result of

        calling the environment's ``obtain(req, installer)`` method will be

        returned.

        """

        dist = working_set.find(req)

        if dist is not None:

            return dist

        for dist in self[req.key]:

            if dist in req:

                return dist

        return self.obtain(req, installer) # try and download/install

    def obtain(self, requirement, installer=None):

        """Obtain a distribution matching `requirement` (e.g. via download)

        Obtain a distro that matches requirement (e.g. via download).  In the

        base ``Environment`` class, this routine just returns

        ``installer(requirement)``, unless `installer` is None, in which case

        None is returned instead.  This method is a hook that allows subclasses

        to attempt other ways of obtaining a distribution before falling back

        to the `installer` argument."""

        if installer is not None:

            return installer(requirement)

    def __iter__(self):

        """Yield the unique project names of the available distributions"""

        for key in self._distmap.keys():

            if self[key]: yield key

    def __iadd__(self, other):

        """In-place addition of a distribution or environment"""

        if isinstance(other,Distribution):

            self.add(other)

        elif isinstance(other,Environment):

            for project in other: