'Add a :app:`Pyramid` asset override to the current
configuration state.
``to_override`` is an :term:`asset specification` to the
asset being overridden.
``override_with`` is an :term:`asset specification` to the
asset that is performing the override. This may also be an absolute
path.
See :ref:`assets_chapter` for more
information about asset overrides.'

@action_method
def override_asset(self, to_override, override_with, _override=None):

    if (to_override == override_with):
        raise ConfigurationError('You    cannot    override    an    asset    with    itself')
    package = to_override
    path = ''
    if (':' in to_override):
        (package, path) = to_override.split(':', 1)
    overridden_isdir = ((path == '') or path.endswith('/'))
    if os.path.isabs(override_with):
        override_source = FSAssetSource(override_with)
        if (not os.path.exists(override_with)):
            raise ConfigurationError('Cannot    override    asset    with    an    absolute    path    that    does    not    exist')
        override_isdir = os.path.isdir(override_with)
        override_package = None
        override_prefix = override_with
    else:
        override_package = override_with
        override_prefix = ''
        if (':' in override_with):
            (override_package, override_prefix) = override_with.split(':', 1)
        __import__(override_package)
        to_package = sys.modules[override_package]
        override_source = PackageAssetSource(to_package, override_prefix)
        override_isdir = ((override_prefix == '') or override_with.endswith('/'))
    if (overridden_isdir and (not override_isdir)):
        raise ConfigurationError('A    directory    cannot    be    overridden    with    a    file    (put    a    slash    at    the    end    of    override_with    if    necessary)')
    if ((not overridden_isdir) and override_isdir):
        raise ConfigurationError('A    file    cannot    be    overridden    with    a    directory    (put    a    slash    at    the    end    of    to_override    if    necessary)')
    override = (_override or self._override)
    def register():
        __import__(package)
        from_package = sys.modules[package]
        override(from_package, path, override_source)
    intr = self.introspectable('asset    overrides', (package, override_package, path, override_prefix), ('%s    ->    %s' % (to_override, override_with)), 'asset    override')
    intr['to_override'] = to_override
    intr['override_with'] = override_with
    self.action(None, register, introspectables=(intr,), order=PHASE1_CONFIG)
