Open file handles

pshell.open(file: str | Path | int | BinaryIO, mode: str = 'r', *, encoding: str | None = None, errors: str | None = None, compression: Literal[False, 'gzip', 'bzip2', 'lzma', 'zstd', 'zstandard', 'auto'] = 'auto', **kwargs: Any) → IO

Open a file handle to target file name or file descriptor.

Unlike the builtin function, this wrapper:

• performs automatic environment variable resolution in the file name

• logs the file access

• supports automatic compression/decompression

Parameters:

• file – Path to the file to be opened or file descriptor to be wrapped. If compression is set to ‘auto’, ‘gzip’, ‘bzip2’, ‘lzma’, ‘zstd’, or ‘zstandard’, file can also be a binary file handle.

• mode (str) – As in the builtin open() function. It always defaults to text mode unless ‘b’ is explicitly specified; this is unlike gzip.open(), bz2.open(), lzma.open(), or compression.zstd.open() which instead default to binary mode.

• encoding (str) – Character encoding when in text mode. Unlike the builtin open() function, it always defaults to utf-8 instead of being platform-specific.

• errors (str) – As in the builtin open() function, but it defaults to replace instead of strict.

• compression –

  One of:

  False

  No compression (use builtin open())

  gzip

  gzip compression (use gzip.open())

  bzip2

  bzip2 compression (use bz2.open())

  lzma

  lzma compression (use lzma.open())

  zstd, zstandard

  zstd compression (use compression.zstd.open()). Requires either Python 3.14+ or the backports.zstd package.

  auto (default):

  Automatically set compression if the file extension is .gz, .bz2, .xz, .zst, or .zstd (case insensitive)

• kwargs – Passed verbatim to the underlying open function