docs: def xopen(filename, mode='r', compresslevel=6, threads=None):
      """
      A replacement for the "open" function that can also open files that have
      been compressed with gzip, bzip2 or xz. If the filename is '-', standard
      output (mode 'w') or input (mode 'r') is returned.
  
      The file type is determined based on the filename: .gz is gzip, .bz2 is bzip2 and .xz is
      xz/lzma.
  
      When writing a gzip-compressed file, the following methods are tried in order to get the
      best speed 1) using a pigz (parallel gzip) subprocess; 2) using a gzip subprocess;
      3) gzip.open. A single gzip subprocess can be faster than gzip.open because it runs in a
      separate process.
  
      Uncompressed files are opened with the regular open().
  
      mode can be: 'rt', 'rb', 'at', 'ab', 'wt', or 'wb'. Also, the 't' can be omitted,
      so instead of 'rt', 'wt' and 'at', the abbreviations 'r', 'w' and 'a' can be used.
  
      In Python 2, the 't' and 'b' characters are ignored.
  
      Append mode ('a', 'at', 'ab') is unavailable with BZ2 compression and
      will raise an error.
  
      compresslevel is the gzip compression level. It is not used for bz2 and xz.
  
      threads is the number of threads for pigz. If None, then the pigz default is used.
      """
      if mode in ('r', 'w', 'a'):
          mode += 't'
      if mode not in ('rt', 'rb', 'wt', 'wb', 'at', 'ab'):
          raise ValueError("mode '{0}' not supported".format(mode))
      if not _PY3:
          mode = mode[0]
      filename = fspath(filename)
      if not isinstance(filename, basestring):
          raise ValueError("the filename must be a string")
      if compresslevel not in range(1, 10):
          raise ValueError("compresslevel must be between 1 and 9")
  
      if filename == '-':
          return _open_stdin_or_out(mode)
      elif filename.endswith('.bz2'):
          return _open_bz2(filename, mode)
      elif filename.endswith('.xz'):
          return _open_xz(filename, mode)
      elif filename.endswith('.gz'):
          return _open_gz(filename, mode, compresslevel, threads)
      else:
          # Python 2.6 and 2.7 have io.open, which we could use to make the returned
          # object consistent with the one returned in Python 3, but reading a file
          # with io.open() is 100 times slower (!) on Python 2.6, and still about
          # three times slower on Python 2.7 (tested with "for _ in io.open(path): pass")
          return open(filename, mode)