\
      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).

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()