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

  • File represents a file found inside any of the filesystems. It is not publically constructible.

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

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

Give a file path, determine the appopriate filesystem.

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

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

Base class for different systems defining the interface.

path: str

Path to this filesystem root, such as the folder or archive file.

for file in walk_folder(
folder: str = '',
) → Iterator[File[Self]]

Iterate over all files in the specified subfolder, yielding each.

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

Open a file in bytes mode or raise FileNotFoundError.

This should be closed when done.

Parameters:

name – Filename, or a file handle belonging to this 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.

Parameters:

  • name – Filename, or a file handle belonging to this system.

  • encoding – Encoding to use.

read_kv1(
path: str | File[Self],
encoding: str = 'utf8',
) → Keyvalues

Read a Keyvalues1 file from the filesystem.

This handles opening and closing files.

__eq__(other: object) → bool

Filesystems are equal if they have the same type and same path.

__iter__() → Iterator[File[Self]]

Iteration yields each file.

__getitem__(
name: str,
) → File[Self]

Index the filesystem to locate a file.

__contains__(name: str) → bool

Check if a file exists.

class srctools.filesys.File

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

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.

Parameters:

encoding – Encoding to use.

cache_key() → int

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

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

__fspath__() → str

This can be interpreted as a path.

srctools.filesys.CACHE_KEY_INVALID = -1

This is returned from File.cache_key() to indicate no key could be computed.

exception srctools.filesys.RootEscapeError(root: str, path: str)

Raised when a path tries to refer to a file outside the root of a filesystem.

Concrete implementations

The specific implementations of base FileSystem methods have been omitted.

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.

systems: list[tuple[FileSystem[Any], str]]

The child filesystems, as (filesystem, subfolder) tuples.

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.

for file in 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.

Raises:

RootEscapeError – if such access occurs.

constrain_path: bool

If enabled, this prohibits accessing files above its root.

class srctools.filesys.VirtualFileSystem(
mapping: Mapping[str, str | bytes | bytearray | memoryview],
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.

bytes_encoding: str

Encoding used to convert text data for open_bin().

path = "<virtual>"

Always constant.

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

Accesses files in a zip file.

zip: ZipFile

The open zipfile object.

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

Accesses files in a VPK file.

vpk: VPK

The VPK to read from.

Implementing Custom FileSystems

Custom filesystems can be implemented by subclassing :py:class`FileSystem`. File objects store a “data” value, which is private to the filesystem implementation, and can hold things like a file-info object. Specify it as the _FileDataT typevar. These are the methods that should be overridden:

FileSystem._file_exists(name: str) → bool

Check if a file exists. The default implementation checks for :py:class`FileNotFoundError`.

FileSystem._get_file(
name: str,
) → File[Self]

Return a specific file.

FileSystem._get_cache_key(
file: File[Self],
) → int

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

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

These methods can be called by subclasses:

File.__init__(
system: FileSysT_co,
path: str,
data: Any,
) → None

Create a File. Should only be called by FileSystem subclasses.

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.

classmethod FileSystem._get_data(
file: File[Self],
) → _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.

Deprecated Functionality

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

Read a Keyvalues1 file from the filesystem.

Deprecated:

Use read_kv1().

FileSystem._check_open() → None
Deprecated:

filesystems are always valid.

FileSystem.__enter__() → Self
Deprecated:

No longer needs to be used as a context manager.

FileSystem.__exit__(*args: object) → None
Deprecated:

No longer needs to be used as a context manager.

FileSystem.open_ref() → None
Deprecated:

No longer needs to be called.

FileSystem.close_ref() → None
Deprecated:

No longer needs to be called.