def _verify(self, file_location, target, all_chksums=True, handlers=None):
        """
        Internal function for derivatives.

        Digs through chksums, and either returns None, or throws an
        errors.FetchFailed exception.
          - -2: file doesn't exist.
          - -1: if (size chksum is available, and
                file is smaller than stated chksum)
          - 0:  if all chksums match
          - 1:  if file is too large (if size chksums are available)
                or else size is right but a chksum didn't match.

        if all_chksums is True, all chksums must be verified; if false, all
        a handler can be found for are used.
        """

        nondefault_handlers = handlers
        if handlers is None:
            try:
                handlers = get_handlers(target.chksums)
            except KeyError, e:
                compatibility.raise_from(
                    errors.FetchFailed(file_location,
                        "Couldn't find a required checksum handler"))

    def __init__(self, location, cache_location=None, repo_id='vdb',
                 disable_cache=False):
        prototype.tree.__init__(self, frozen=False)
        self.repo_id = repo_id
        self.location = location
        if disable_cache:
            cache_location = None
        elif cache_location is None:
            cache_location = pjoin("/var/cache/edb/dep", location.lstrip("/"))
        self.cache_location = cache_location
        self._versions_tmp_cache = {}
        try:
            st = os.stat(self.location)
            if not stat.S_ISDIR(st.st_mode):
                raise errors.InitializationError(
                    "base not a dir: %r" % self.location)
            elif not st.st_mode & (os.X_OK|os.R_OK):
                raise errors.InitializationError(
                    "base lacks read/executable: %r" % self.location)

        except OSError as e:
            if e.errno != errno.ENOENT:
                compatibility.raise_from(errors.InitializationError(
                    "lstat failed on base %r" % self.location))

        self.package_class = self.package_factory(self)

    def _check_magic(self, fd):
        fd.seek(-16, 2)
        try:
            pre, size, post = self.trailer.read(fd)
            if pre != self.trailer_pre_magic or post != self.trailer_post_magic:
                raise MalformedXpak(
                    "not an xpak segment, trailer didn't match: %r" % fd)
        except struct.error:
            raise_from(MalformedXpak(
                "not an xpak segment, failed parsing trailer: %r" % fd))

        # this is a bit daft, but the format seems to intentionally
        # have an off by 8 in the offset address. presumably cause the
        # header was added after the fact, either way we go +8 to
        # check the header magic.
        fd.seek(-(size + 8), 2)
        self.xpak_start = fd.tell()
        try:
            pre, index_len, data_len = self.header.read(fd)
            if pre != self.header_pre_magic:
                raise MalformedXpak(
                    "not an xpak segment, header didn't match: %r" % fd)
        except struct.error:
            raise_from(MalformedXpak(
                "not an xpak segment, failed parsing header: %r" % fd))

        return self.xpak_start + self.header.size, index_len, data_len

    def get_default(self, type_name):
        """Finds the configuration specified default obj of type_name.

        Returns C{None} if no defaults.
        """
        try:
            defaults = self.types.get(type_name, {}).iteritems()
        except compatibility.IGNORED_EXCEPTIONS:
            raise
        except Exception:
            compatibility.raise_from(errors.ConfigurationError(
                "Collapsing defaults for %r" % (type_name,)))
        defaults = [(name, section) for name, section in defaults if section.default]

        if not defaults:
            return None

        if len(defaults) > 1:
            defaults = sorted([x[0] for x in defaults])
            raise errors.ConfigurationError(
                'type %s incorrectly has multiple default sections: %s'
                    % (type_name, ', '.join(map(repr, defaults))))

        try:
            return defaults[0][1].instantiate()
        except compatibility.IGNORED_EXCEPTIONS:
            raise
        except Exception:
            compatibility.raise_from(errors.ConfigurationError(
                "Failed instantiating default %s %r" % (type_name, defaults[0][0])))
        return None

def add_profile(config, base_path, user_profile_path=None, profile_override=None):
    if profile_override is None:
        profile = _find_profile_link(base_path)
    else:
        profile = normpath(abspath(profile_override))
        if not os.path.exists(profile):
            raise_from(errors.ComplexInstantiationError(
                "%s doesn't exist" % (profile,)))

    paths = profiles.OnDiskProfile.split_abspath(profile)
    if paths is None:
        raise errors.ComplexInstantiationError(
            '%s expands to %s, but no profile detected' %
            (pjoin(base_path, 'make.profile'), profile))

    if os.path.isdir(user_profile_path):
        config["profile"] = basics.AutoConfigSection({
            "class": "pkgcore.ebuild.profiles.UserProfile",
            "parent_path": paths[0],
            "parent_profile": paths[1],
            "user_path": user_profile_path,
        })
    else:
        config["profile"] = basics.AutoConfigSection({
            "class": "pkgcore.ebuild.profiles.OnDiskProfile",
            "basepath": paths[0],
            "profile": paths[1],
        })

    def collapse_named_section(self, name, raise_on_missing=True):
        """Collapse a config by name, possibly returning a cached instance.

        @returns: :obj:`CollapsedConfig`.

        If there is no section with this name a ConfigurationError is raised,
        unless raise_on_missing is False in which case None is returned.
        """
        if name in self._refs:
            raise errors.ConfigurationError(
                'Reference to %r is recursive' % (name,))
        self._refs.add(name)
        try:
            result = self.rendered_sections.get(name)
            if result is not None:
                return result
            section_stack = self.sections_lookup.get(name)
            if section_stack is None:
                if not raise_on_missing:
                    return None
                raise errors.ConfigurationError(
                   'no section called %r' % (name,))
            try:
                result = self.collapse_section(section_stack, name)
                result.name = name
            except compatibility.IGNORED_EXCEPTIONS:
                raise
            except Exception:
                compatibility.raise_from(errors.ConfigurationError(
                    "Collapsing section named %r" % (name,)))
            self.rendered_sections[name] = result
            return result
        finally:
            self._refs.remove(name)

    def reconstruct_eclasses(self, cpv, eclass_string):
        """Turn a string from :obj:`serialize_eclasses` into a dict."""
        if not isinstance(eclass_string, basestring):
            raise TypeError("eclass_string must be basestring, got %r" %
                eclass_string)
        eclass_data = eclass_string.strip().split(self.eclass_splitter)
        if eclass_data == [""]:
            # occasionally this occurs in the fs backends.  they suck.
            return []

        l = len(eclass_data)
        chf_funcs = self.eclass_chf_deserializers
        tuple_len = len(chf_funcs) + 1
        if len(eclass_data) % tuple_len:
             raise errors.CacheCorruption(
                 cpv, "_eclasses_ was of invalid len %i"
                 "(must be mod %i)" % (len(eclass_data), tuple_len))

        i = iter(eclass_data)
        # roughly; deserializer grabs the values it needs, resulting
        # in a sequence of key/tuple pairs for each block of chfs;
        # this is in turn fed into the dict kls which converts it
        # to the dict.
        # Finally, the first item, and that chain, is zipped into
        # a dict; in effect, if 2 chfs, this results in a stream of-
        # (eclass_name, ((chf1,chf1_val), (chf2, chf2_val))).
        try:
            return [(eclass, tuple(self._deserialize_eclass_chfs(i)))
                for eclass in i]
        except ValueError:
            raise_from(errors.CacheCorruption(
                cpv, 'ValueError reading %r' % (eclass_string,)))

def existent_path(value):
    if not os.path.exists(value):
        raise ValueError("path %r doesn't exist on disk" % (value,))
    try:
        return osutils.abspath(value)
    except EnvironmentError as e:
        compatibility.raise_from(ValueError("while resolving path %r, encountered error: %r" % (value, e)))

    def setup_distfiles(self):
        if not self.verified_files and self.allow_fetching:
            ops = self.domain.pkg_operations(self.pkg,
                observer=self.observer)
            if not ops.fetch():
                raise format.BuildError("failed fetching required distfiles")
            self.verified_files = ops._fetch_op.verified_files

        if self.verified_files:
            try:
                if os.path.exists(self.env["DISTDIR"]):
                    if (os.path.isdir(self.env["DISTDIR"])
                        and not os.path.islink(self.env["DISTDIR"])):
                        shutil.rmtree(self.env["DISTDIR"])
                    else:
                        os.unlink(self.env["DISTDIR"])

            except EnvironmentError as oe:
                raise_from(format.FailedDirectory(
                    self.env["DISTDIR"],
                    "failed removing existing file/dir/link at: exception %s"
                    % oe))

            if not ensure_dirs(self.env["DISTDIR"], mode=0770,
                               gid=portage_gid):
                raise format.FailedDirectory(

def convert_string(central, value, arg_type):
    """Conversion func for a string-based DictConfigSection."""
    if not isinstance(value, basestring):
        raise ValueError(
            'convert_string invoked with non basestring instance:'
            ' val(%r), arg_type(%r)' % (value, arg_type))
    if arg_type == 'callable':
        try:
            func = modules.load_attribute(value)
        except modules.FailedImport:
            compatibility.raise_from(
                errors.ConfigurationError('Cannot import %r' % (value,)))
        if not callable(func):
            raise errors.ConfigurationError('%r is not callable' % (value,))
        return func
    elif arg_type.startswith('refs:'):
        return list(LazyNamedSectionRef(central, arg_type, ref)
                    for ref in str_to_list(value))
    elif arg_type.startswith('ref:'):
        return LazyNamedSectionRef(central, arg_type, str_to_str(value))
    elif arg_type == 'repr':
        return 'str', value
    func = _str_converters.get(arg_type)
    if func is None:
        raise errors.ConfigurationError('Unknown type %r' % (arg_type,))
    return func(value)

    def keys_dict(self):
        fd = self._fd
        index_start, index_len, data_len = self._check_magic(fd)
        data_start = index_start + index_len
        keys_dict = OrderedDict()
        key_rewrite = self._reading_key_rewrites.get
        while index_len:
            key_len = struct.unpack(">L", fd.read(4))[0]
            key = fd.read(key_len)
            if compatibility.is_py3k:
                key = key.decode('ascii')
            if len(key) != key_len:
                raise MalformedXpak(
                    "tried reading key %i of len %i, but hit EOF" % (
                        len(keys_dict) + 1, key_len))
            try:
                offset, data_len = struct.unpack(">LL", fd.read(8))
            except struct.error:
                raise_from(MalformedXpak(
                    "key %i, tried reading data offset/len but hit EOF" % (
                        len(keys_dict) + 1)))
            key = key_rewrite(key, key)
            keys_dict[key] = (
                data_start + offset, data_len,
                compatibility.is_py3k and not key.startswith("environment"))
            index_len -= (key_len + 12) # 12 for key_len, offset, data_len longs

        return keys_dict

 def instantiate(self):
     if self._instance is None:
         try:
             self._instance = self._instantiate()
         except compatibility.IGNORED_EXCEPTIONS:
             raise
         except Exception, e:
             compatibility.raise_from(errors.InstantiationError(self.name))

def convert_to_restrict(sequence, default=packages.AlwaysTrue):
    """Convert an iterable to a list of atoms, or return the default"""
    l = []
    try:
        for x in sequence:
            l.append(parserestrict.parse_match(x))
    except parserestrict.ParseError, e:
        compatibility.raise_from(optparse.OptionValueError("arg %r isn't a valid atom: %s" % (x, e)))

 def _sync(self, verbosity, output_fd):
     try:
         st = os.stat(self.basedir)
     except EnvironmentError, ie:
         if ie.errno != errno.ENOENT:
             compatibility.raise_from(generic_exception(self, self.basedir, ie))
         command = self._initial_pull()
         chdir = None

 def _delitem(self, cpv):
     try:
         os.remove(pjoin(self.location, cpv))
     except OSError as e:
         if e.errno == errno.ENOENT:
             raise KeyError(cpv)
         else:
             raise_from(errors.CacheCorruption(cpv, e))

 def _get_categories(self, *optional_category):
     # return if optional_category is passed... cause it's not yet supported
     if optional_category:
         return {}
     try:
         return tuple(x for x in listdir_dirs(self.base) if x.lower() != "all")
     except EnvironmentError as e:
         raise_from(KeyError("failed fetching categories: %s" % str(e)))

 def _acquire_fd(self):
     flags = os.R_OK
     if self.create:
         flags |= os.O_CREAT
     try:
         self.fd = os.open(self.path, flags)
     except OSError as oe:
         compatibility.raise_from(GenericFailed(self.path, oe))

def parse_match(text):
    """generate appropriate restriction for text

    Parsing basically breaks it down into chunks split by /, with each
    chunk allowing for prefix/postfix globbing- note that a postfixed
    glob on package token is treated as package attribute matching,
    not as necessarily a version match.

    If only one chunk is found, it's treated as a package chunk.
    Finally, it supports a nonstandard variation of atom syntax where
    the category can be dropped.

    Examples:

    - `*`: match all
    - `dev-*/*`: category must start with 'dev-'
    - `dev-*`: package must start with 'dev-'
    - `*-apps/portage*`: category must end in '-apps', package must start with
      'portage'
    - `>=portage-2.1`: atom syntax, package 'portage', version greater then or
      equal to '2.1'

    :param text: string to attempt to parse
    :type text: string
    :return: :obj:`pkgcore.restrictions.packages` derivative
    """

    # Ensure the text var is a string if we're under py3k.
    if not is_py3k:
        text = text.encode('ascii')
    orig_text = text = text.strip()
    if "!" in text:
        raise ParseError(
            "!, or any form of blockers make no sense in this usage: %s" % (
                text,))
    tsplit = text.rsplit("/", 1)
    if len(tsplit) == 1:
        ops, text = collect_ops(text)
        if not ops:
            if "*" in text:
                r = convert_glob(text)
                if r is None:
                    return packages.AlwaysTrue
                return packages.PackageRestriction("package", r)
        elif text.startswith("*"):
            raise ParseError(
                "cannot do prefix glob matches with version ops: %s" % (
                    orig_text,))
        # ok... fake category.  whee.
        try:
            r = list(util.collect_package_restrictions(
                    atom.atom("%scategory/%s" % (ops, text)).restrictions,
                    attrs=("category",), invert=True))
        except errors.MalformedAtom, e:
            raise_from(ParseError(str(e)))
        if len(r) == 1:
            return r[0]
        return packages.AndRestriction(*r)

 def render_value(self, central, name, arg_type):
     try:
         return self.func(central, self.dict[name], arg_type)
     except compatibility.IGNORED_EXCEPTIONS:
         raise
     except Exception:
         compatibility.raise_from(errors.ConfigurationError(
             "Failed converting argument %r to %s"
             % (name, arg_type)))

 def _recast_exception_decorator(exc_class, name, functor, *args, **kwds):
     try:
         return functor(*args, **kwds)
     except compatibility.IGNORED_EXCEPTIONS:
         raise
     except Exception as exc:
         if isinstance(exc, exc_class):
             raise
         compatibility.raise_from(exc_class(name))