docs: def _unique_by_email(users_and_watches):
      """Given a sequence of (User/EmailUser, [Watch, ...]) pairs
      clustered by email address (which is never ''), yield from each
      cluster a single pair like this::
  
        (User/EmailUser, [Watch, Watch, ...]).
  
      The User/Email is that of...
      (1) the first incoming pair where the User has an email and is not
          anonymous, or, if there isn't such a user...
      (2) the first pair.
  
      The list of Watches consists of all those found in the cluster.
  
      Compares email addresses case-insensitively.
  
      """
      def ensure_user_has_email(user, cluster_email):
          """Make sure the user in the user-watch pair has an email address.
  
          The caller guarantees us an email from either the user or the watch. If
          the passed-in user has no email, we return an EmailUser instead having
          the email address from the watch.
  
          """
          # Some of these cases shouldn't happen, but we're tolerant.
          if not getattr(user, 'email', ''):
              user = EmailUser(cluster_email)
          return user
  
      # TODO: Do this instead with clever SQL that somehow returns just the
      # best row for each email.
  
      cluster_email = ''  # email of current cluster
      favorite_user = None  # best user in cluster so far
      watches = []  # all watches in cluster
      for u, w in users_and_watches:
          # w always has at least 1 Watch. All the emails are the same.
          row_email = u.email or w[0].email
          if cluster_email.lower() != row_email.lower():
              # Starting a new cluster.
              if cluster_email != '':
                  # Ship the favorites from the previous cluster:
                  yield (ensure_user_has_email(favorite_user, cluster_email),
                         watches)
              favorite_user, watches = u, []
              cluster_email = row_email
          elif ((not favorite_user.email or not u.is_authenticated) and
                u.email and u.is_authenticated):
              favorite_user = u
          watches.extend(w)
      if favorite_user is not None:
          yield ensure_user_has_email(favorite_user, cluster_email), watches