srctools.filesys

Implements a consistent interface for reading files.

This allows accessing different backing file sources interchangably. Files are case-insensitive, and both slashes are converted to ‘/’.

With a filesystem object, you can index it to locate files inside (raising FileNotFoundError if missing). Once a File object is obtained, call open_bin() or open_str() to read the contents. Writing is not supported.

FileSystem is the base ABC, which can be subclassed to define additional subsystems.
RawFileSystem provides access to a directory, optionally prohibiting access to parent folders.
ZipFileSystem and VPKFileSystem provide access to their respective archives.
VirtualFileSystem redirects to a mapping object, for fake file contents already in memory.
FileSystemChain contains multiple other systems, concatenating them together like how Source treats its search paths.

See the srctools.game.Game class for parsing gameinfo.txt files into filesystems. To mount a BSP file, use ZipFileSystem(bsp.pakfile).

class srctools.filesys.File(system: FileSysT, path: str, data: Any)

Represents a file in a system. Should only be created by filesystems..

sys: FileSysT

path: str

open_bin() → BinaryIO

Return a file-like object in bytes mode.

This should be closed when done.

open_str(encoding: str = 'utf8') → TextIO

Return a file-like object in unicode mode.

This should be closed when done.

cache_key() → int

Return a checksum or last-modified date suitable for caching.

This allows preventing reparsing the file. If not possible, return -1.

class srctools.filesys.FileSystem(path: Union[str, _os.PathLike[str]])

Base class for different systems defining the interface.

open_ref() → None

Deprecated:	No longer needs to be called.

close_ref() → None

Deprecated:	No longer needs to be called.

read_kv1(path: str, encoding: str = 'utf8') → Keyvalues

Read a Keyvalues1 file from the filesystem.

This handles opening and closing files.

read_prop(path: str, encoding: str = 'utf8') → Keyvalues

Read a Keyvalues1 file from the filesystem.

Deprecated:	Use `read_kv1()`.

walk_folder(folder: str = '') → Iterator[File[FileSysT]]: Iterate over all files in the specified subfolder, yielding each.

open_str( name: Union[str, File[FileSysT]], encoding: str = 'utf8', ) → TextIO

Open a file in unicode mode or raise FileNotFoundError.

This should be closed when done.

open_bin(name: Union[str, File[FileSysT]]) → BinaryIO

Open a file in bytes mode or raise FileNotFoundError.

This should be closed when done.

srctools.filesys.get_filesystem(path: str) → FileSystem

Return a filesystem given a path.

If the path is a directory this returns a RawFileSystem. Otherwise, it returns a VPK or zip, depending on extension.

srctools.filesys.CACHE_KEY_INVALID: Final = -1: This is returned from FileSystem.cache_key() to indicate no key could be computed.

class srctools.filesys.RawFileSystem( path: Union[str, _os.PathLike[str]], constrain_path: bool = True, )

Accesses files in a real folder.

This can prohibit access to folders above the root.

walk_folder(folder: str = '') → Iterator[File[RawFSysT]]: Yield files in a folder.

open_str( name: Union[str, File[RawFSysT]], encoding: str = 'utf8', ) → TextIO

Open a file in unicode mode or raise FileNotFoundError.

This should be closed when done.

open_bin(name: Union[str, File[RawFSysT]]) → BinaryIO

Open a file in bytes mode or raise FileNotFoundError.

This should be closed when done.

class srctools.filesys.VPKFileSystem(path: Union[str, _os.PathLike[str]])

Accesses files in a VPK file.

walk_folder(folder: str = '') → Iterator[File[VPKFSysT]]: Yield files in a folder.

open_bin(name: Union[str, File[VPKFSysT]]) → BinaryIO: Open a file in bytes mode or raise FileNotFoundError.

open_str( name: Union[str, File[VPKFSysT]], encoding: str = 'utf8', ) → TextIO: Open a file in unicode mode or raise FileNotFoundError.

class srctools.filesys.ZipFileSystem( path: Union[str, _os.PathLike[str]], zipfile: Optional[ZipFile] = None, )

Accesses files in a zip file.

walk_folder(folder: str = '') → Iterator[File[ZipFSysT]]: Yield files in a folder.

open_bin(name: Union[str, File[ZipFSysT]]) → BinaryIO

Open a file in bytes mode or raise FileNotFoundError.

The filesystem needs to be open while accessing this.

open_str( name: Union[str, File[ZipFSysT]], encoding: str = 'utf8', ) → TextIOWrapper

Open a file in unicode mode or raise FileNotFoundError.

The filesystem needs to be open while accessing this.

class srctools.filesys.VirtualFileSystem( mapping: Mapping[str, Union[str, bytes]], encoding: str = 'utf8', )

Access a dict as if it were a filesystem.

The dict should map file paths to either bytes or strings. The encoding arg specifies how text data is presented if open_bin() is called.

open_bin(name: Union[str, File[VirtualFSysT]]) → BinaryIO: Return a bytes buffer for a ‘file’.

open_str( name: Union[str, File[VirtualFSysT]], encoding: str = 'utf8', ) → TextIO

Return a string buffer for a ‘file’.

This performs universal newlines conversion. The encoding argument is ignored for files which are originally text.

walk_folder(folder: str = '') → Iterator[File[VirtualFSysT]]: Return all files that are ‘subfolders’ of the provided folder.

class srctools.filesys.FileSystemChain( *systems: Union[FileSystem, Tuple[FileSystem, str]], )

Chains several filesystem into one prioritised whole.

Each system can additionally be filtered to only allow access to files inside a subfolder. These will appear as if they are at the root level.

classmethod get_system(file: File[ChainFSysT]) → FileSystem: Retrieve the system for a File, if it was produced from a FileSystemChain.

add_sys( sys: FileSystem, prefix: str = '', *, priority: bool = False, ) → None

Add a filesystem to the list.

Parameters:	priority – If True, the system will be added to the start, instead of the end. sys – The filesystem to add. prefix – If specified, only this subfolder’s contents will be accessible, instead of the whole system.

open_str( name: Union[str, File[ChainFSysT]], encoding: str = 'utf8', ) → TextIO

Open a file in unicode mode or raise FileNotFoundError.

This should be closed when done.

open_bin(name: Union[str, File[ChainFSysT]]) → BinaryIO

Open a file in bytes mode or raise FileNotFoundError.

This should be closed when done.

walk_folder(folder: str = '') → Iterator[File[ChainFSysT]]

Walk folders, not repeating files.

This requires temporarily storing the visited paths, to prevent revisiting them. If repeated access is not problematic, prefer walk_folder_repeat().

walk_folder_repeat(folder: str = '') → Iterator[File[ChainFSysT]]

Walk folders, but allow repeating files.

If a file is contained in multiple systems, it will be yielded for each. The first is the highest-priority. Using this instead of walk_folder() is cheaper, since a set of visited files must be maintained.