srctools.vpk

Classes for reading and writing Valve’s VPK format, version 1.

srctools.vpk.VPK_SIG: Final = 1437209140: The first byte of VPK files.

srctools.vpk.DIR_ARCH_INDEX: Final = 32767: The file index used for the _dir file.

class srctools.vpk.OpenModes

Bases: Enum

Modes for opening VPK files.

READ = 'r'

WRITE = 'w'

APPEND = 'a'

writable: Check if this mode allows modifying the VPK.

srctools.vpk.script_write(args: list[str]) → None: Create a VPK archive.

srctools.vpk.get_arch_filename( prefix: str = 'pak01', index: int | None = None, ) → str

Generate the name for a VPK file.

Prefix is the name of the file, usually ‘pak01’. index is the index of the data file, or None for the directory.

class srctools.vpk.FileInfo( vpk: VPK, dir: str, filename: str, ext: str, crc: int, arch_index: int | None, offset: int, arch_len: int, start_data: bytes, )

Represents a file stored inside a VPK.

Do not call the constructor, it is only meant for VPK’s use. Attributes should not be assigned to - use write() to change the contents.

property filename: str: The full filename for this file.

property name: str: The full filename for this file.

property size: int: The total size of this file.

read() → bytes: Return the contents for this file.

verify() → bool: Check this file matches the checksum.

write( data: bytes, arch_index: int | None = None, ) → None

Replace this file with the given byte data.

arch_index is the pak_01_000 file to put data into (or None for _dir). This is ignored if the VPK is singular. Data written to the directory file is not immediately saved, py:meth:VPK.write_dirfile() must subsequently be called to do so. - If this file already exists in the VPK, the old data is not removed from numeric files.

For this reason VPK writes should be done once per file if possible.

class srctools.vpk.VPK( dir_file: str | PathLike[str], *, mode: OpenModes | str = 'r', dir_data_limit: int | None = 1024, version: int = 1, )

Represents a VPK archive.

VPKs can either be a singular file, or a main archive_dir.vpk with associated numerix archive_XXX.vpk files containing the data.

folder: str: The directory the VPK is located in, used to find the numeric files.

mode: OpenModes

How the file was opened.

Read mode, the file will not be modified and it must already exist.
Write mode will create the directory if needed.
Append mode will also create the directory, but not wipe the file.

dir_limit: int | None

The maximum amount of data for files saved to the dir file.

None: No limit.
0: Save all to a data file.

footer_data: bytes: The block of data after the header, which contains the file data for files stored in the _dir file, not numeric files.

version: int: The VPK version, 1 or 2.

property path: str | PathLike[str]

The full path of the directory VPK file, or the single file.

This can be assigned to set folder and filename.

property filename: str: The filename of the directory VPK file, or the single file.

property file_prefix: str

The VPK filename, without .vpk, or _dir.vpk if a directory.

Deprecated:: Do not assign to this, it assumes the VPK is always a directory file. Instead, assign to filename or path.

property is_directory: bool: If true, this is a _dir.vpk file, potentially with data stored in auxilliary VPKS.

load_dirfile() → None: Read in the directory file to get all filenames. This erases all changes made to the object.

write_dirfile() → None: Write the directory file with the changes. This must be performed after writing to the VPK.

for ... in filenames( ext: str = '', folder: str = '', ) → Iterator[str]

Yield filenames from this VPK.

If an extension or folder is specified, only files with this extension or in this folder are returned.

for ... in folders( *, ext: str | None = None, ) → Iterator[str]

Yield the names of folders present in this VPK.

If an extension is specified, only folders containing files with that extension are returned.

for ... in fileinfos( *, ext: str | None = None, folder: str = '', ) → Iterator[FileInfo]

Yield file info objects from this VPK.

If an extension or folder is specified, only files with this extension or in this folder are returned.

extract_all(dest_dir: str) → None: Extract the contents of this VPK to a directory.

new_file( filename: str | tuple[str, str] | tuple[str, str, str], root: str = '', ) → FileInfo

Create the given file, making it empty by default.

If root is set, files are treated as relative to there, otherwise the filename must be relative.

FileExistsError will be raised if the file is already present.

add_file( filename: str | tuple[str, str] | tuple[str, str, str], data: bytes, root: str = '', arch_index: int | None = 0, ) → None

Add the given data to the VPK.

If root is set, files are treated as relative to there, otherwise the filename must be relative. arch_index is the pak01_xxx file to copy this to, if the length is larger than self.dir_limit. If None it’s written to the _dir file.

FileExistsError will be raised if the file is already present.

add_folder(folder: str, prefix: str = '') → None

Write all files in a folder to the VPK.

If prefix is set, the folders will be written to that subfolder.

verify_all() → bool: Check all files have a correct checksum.