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).

exception srctools.filesys.RootEscapeError(root: str, path: str): Raised when a path tries to refer to a file outside the root of a filesystem.

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

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.

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

Base class for different systems defining the interface.

__init__(path: str | _os.PathLike[str]) → None

__repr__() → str: Return repr(self).

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()`.

_check_open() → None: Ensure self._ref is valid.

__eq__(other: object) → bool: Filesystems are equal if they have the same type and same path.

__hash__() → int: Return hash(self).

__enter__() → FileSysT

Deprecated:	No longer needs to be used as a context manager.

__exit__( exc_type: Type[BaseException], exc_val: BaseException, exc_tb: TracebackType, ) → None

Deprecated:	No longer needs to be used as a context manager.

__iter__() → Iterator[File[FileSysT]]: Iteration yields each file.

classmethod _get_data(file: File[FileSysT]) → _FileDataT

Accessor for file._data, to show the relationship to the type checker.

It should only be available to that filesystem, and produces the type.

_get_file(name: str) → File[FileSysT]: Return a specific file.

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

open_str( name: 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: str | File[FileSysT]) → BinaryIO

Open a file in bytes mode or raise FileNotFoundError.

This should be closed when done.

_get_cache_key(file: File[FileSysT]) → int

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

This allows preventing re-parsing the file. If not possible, return CACHE_KEY_INVALID (-1).

__weakref__: list of weak references to the object (if defined)

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

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

__init__(system: FileSysT, path: str, data: Any) → None

Create a File.

Parameters:	system – should be the filesystem which matches. path – is the relative path for the file. data – is filesystem-specific data, allowing directly opening the file.

__fspath__() → str: This can be interpreted as a path.

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.

__weakref__: list of weak references to the object (if defined)

Concrete implementations

class srctools.filesys.FileSystemChain( *systems: FileSystem[Any] | Tuple[FileSystem[Any], 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[Self]) → FileSystem[Any]: Retrieve the system for a File, if it was produced from a FileSystemChain.

add_sys( sys: FileSystem[Any], 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: str | File[Self], encoding: str = 'utf8', ) → TextIO

Open a file in unicode mode or raise FileNotFoundError.

This should be closed when done.

open_bin(name: str | File[Self]) → BinaryIO

Open a file in bytes mode or raise FileNotFoundError.

This should be closed when done.

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

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[Self]]

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.

class srctools.filesys.RawFileSystem( path: 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[Self]]: Yield files in a folder.

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

Open a file in unicode mode or raise FileNotFoundError.

This should be closed when done.

open_bin(name: str | File[Self]) → BinaryIO

Open a file in bytes mode or raise FileNotFoundError.

This should be closed when done.

class srctools.filesys.VirtualFileSystem( mapping: Mapping[str, 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: str | File[Self]) → BinaryIO: Return a bytes buffer for a ‘file’.

open_str( name: str | File[Self], 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[Self]]: Return all files that are ‘subfolders’ of the provided folder.

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

Accesses files in a zip file.

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

open_bin(name: str | File[Self]) → BinaryIO

Open a file in bytes mode or raise FileNotFoundError.

The filesystem needs to be open while accessing this.

open_str( name: str | File[Self], 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.VPKFileSystem(path: str | _os.PathLike[str])

Accesses files in a VPK file.

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

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

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