docs: def insert(self, val, pipe=None):
        """\
        Inserts a value and returns a :class:`Pair <shorten.Pair>`.
  
        .. admonition :: Key Safety
  
           Keys and tokens are always inserted with a :class:`Pipeline`, so 
           irrevocable keys will never occur.
        
        If `pipe` is given, :class:`KeyInsertError <shorten.KeyInsertError>` and 
        :class:`TokenInsertError <shorten.TokenInsertError>` will not be thrown 
        if duplicate keys and tokens exist. Instead, the nth-from-last results 
        must be checked:
        
        ::
        
           pipe = redis.pipeline()
           key, token = short.insert('value', pipe)
           results = pipe.execute()
           
           if not results[-2]:
              raise KeyInsertError(key)
  
           if not results[-1]:
              raise TokenInsertError(token)
  
  
        :attr val:     a value to insert.
        :attr pipe:    a Redis pipeline. If `None`, the pair will
                       be returned immediately. Otherwise they must be
                       extracted from the pipeline results (see above).
        """
       
        p = self.redis.pipeline() if pipe is None else pipe
        
        try:
           key, token, formatted_key, formatted_token = self.next_formatted_pair()
  
           p.watch(formatted_key, formatted_token)
  
           # Make this atomic
           p.multi()      
  
           # Associate both the value and token with the key to
           # allow `get_token(key)`
           p.hsetnx(formatted_key, 'value', val)
           p.hsetnx(formatted_key, 'token', token)
           p.setnx(formatted_token, key)
           
           if pipe is None:
              results = p.execute()
  
              if not results[-2] or not results[-3]:
                 raise KeyInsertError(key, 'key exists')
  
              if not results[-1]:
                 raise TokenInsertError(token, 'token exists')
  
           return Pair(key, token)
  
        except WatchError:
           raise
  
        finally:
           if pipe is None:
              p.reset()