Update the PATH environment variable.
    
    Can append, prepend, or replace the path.  Each of these expects a string
    or a list of strings (for multiple path elements) and can operate on remote
    connections that offer an @environ@ attribute using the @on@ argument.

def path(append=None, prepend=None, replace=None, on=os):
    """Update the PATH environment variable.
    
    Can append, prepend, or replace the path.  Each of these expects a string
    or a list of strings (for multiple path elements) and can operate on remote
    connections that offer an @environ@ attribute using the @on@ argument.
    """
    
    original = on.environ['PATH']
    
    if replace and (append or prepend):
        raise ValueError("You can not combine append or prepend with replace.")
    
    if replace:
        if not isinstance(replace, list):
            replace = list(replace)
        
        on.environ['PATH'] = ':'.join(replace)
    
    else:
        if append:
            if not isinstance(append, list):
                append = list(append)
            
            append.insert(0, on.environ['PATH'])
            on.environ['PATH'] = ':'.join(append)
        
        if prepend:
            if not isinstance(prepend, list):
                prepend = list(prepend)
            
            prepend.append(on.environ['PATH'])
            on.environ['PATH'] = ':'.join(prepend)
    
    yield
    
    on.environ['PATH'] = original