docs: def substitute_partner(self, state, partners_recp, recp, alloc_id):
          '''
          Establish the partnership to recp and, when it is successfull
          remove partner with recipient partners_recp.
  
          Use with caution: The partner which we are removing is not notified
          in any way, so he still keeps link in his description. The correct
          usage of this method requires calling it from two agents which are
          divorcing.
          '''
          partner = state.partners.find(recipient.IRecipient(partners_recp))
          if not partner:
              msg = 'subsitute_partner() did not find the partner %r' %\
                    partners_recp
              self.error(msg)
              return fiber.fail(partners.FindPartnerError(msg))
          return self.establish_partnership(recp, partner.allocation_id,
                                            alloc_id, substitute=partner)