docs: def find_duplicates(filenames, max_size):
      """Find duplicates in a list of files, comparing up to `max_size` bytes.
  
      Returns a 2-tuple of two values: ``(duplicate_groups, errors)``.
  
      `duplicate_groups` is a (possibly empty) list of lists: the names of
      files that have at least two copies, grouped together.
  
      `errors` is a list of error messages that occurred. If empty, there were
      no errors.
  
      For example, assuming ``a1`` and ``a2`` are identical, ``c1`` and ``c2`` are
      identical, and ``b`` is different from all others::
  
        >>> dups, errs = find_duplicates(['a1', 'a2', 'b', 'c1', 'c2'], 1024)
        >>> dups
        [['a1', 'a2'], ['c1', 'c2']]
        >>> errs
        []
  
      Note that ``b`` is not included in the results, as it has no duplicates.
  
      """
      errors = []
  
      # shortcut: can't have duplicates if there aren't at least 2 files
      if len(filenames) < 2:
          return [], errors
  
      # shortcut: if comparing 0 bytes, they're all the same
      if max_size == 0:
          return [filenames], errors
  
      files_by_md5 = {}
  
      for filename in filenames:
          try:
              md5 = calculate_md5(filename, max_size)
          except EnvironmentError as e:
              msg = "unable to calculate MD5 for '%s': %s" % (filename, e.strerror)
              sys.stderr.write("%s\n" % msg)
              errors.append(msg)
              continue
  
          if md5 not in files_by_md5:
              # unique beginning so far; index it on its own
              files_by_md5[md5] = [filename]
          else:
              # found a potential duplicate (same beginning)
              files_by_md5[md5].append(filename)
  
      # Filter out the unique files (lists of files with the same md5 that
      # only contain 1 file), and create a list of the lists of duplicates.
      # Don't use values() because on Python 2 this creates a list of all
      # values (file lists), and that may be very large.
      duplicates = [l for l in py3compat.itervalues(files_by_md5) if len(l) >= 2]
  
      return duplicates, errors