DOCSEARCHbyAlgolia
Submit Docs

vdf Python Module

repository·master·Indexed 42 days ago

https://github.com/valvepython/vdf

A pure Python module for serialization to and from Valve's KeyValue (VDF) text format, including support for binary representations and the VBKV format. It provides a VDFDict class to handle duplicate keys and preserve insertion order, and includes the vdf2json CLI tool for converting VDF files to JSON.

Tokens
1.8K
Snippets
9
Records
9
Agent score
49%

What's inside vdf

  1. Handle duplicate keys and preserve order with VDFDict

    master

    Standard Python dictionaries cannot represent VDF files that contain duplicate keys. To handle duplicates and preserve insertion order, use vdf.VDFDict as the mapper argument in loading functions.

    VDFDict features:

    • Duplicate Support: Assigning a value to an existing key creates a duplicate instead of overwriting. Access duplicates using a tuple index: d[(index, 'key')].
    • Order Preservation: Remembers insertion order.
    • Key Constraints: Keys must be of type str.
    • Special Methods:
      • get_all_for(key): Returns a list of all values associated with that key.
      • remove_all_for(key): Removes all instances of the specified key.
      • has_duplicates(): Returns True if the dictionary contains duplicate keys.
    import vdf
import collections

# Using VDFDict to handle duplicates and order
d = vdf.loads(vdf_string, mapper=vdf.VDFDict)

# Example of VDFDict behavior
d = vdf.VDFDict()
d['key'] = 111
d['key'] = 222

print(d.items())          # [('key', 111), ('key', 222)]
print(d['key'])            # 111 (returns the first occurrence)
print(d[(1, 'key')])       # 222 (accesses the second duplicate)
print(d.get_all_for('key')) # [111, 222]

d.remove_all_for('key')
print(len(d))              # 0

  2. Install vdf via pip

    master

    You can install the latest release of vdf from PyPI using pip.

    To install the current development version directly from GitHub, use the following command:

    pip install vdf

# Or for the dev version:
pip install git+https://github.com/ValvePython/vdf

  3. Parse and dump binary VDF and VBKV

    master

    The module supports binary VDF formats and the VBKV format (which includes header and CRC checking).

    Binary VDF

    Use vdf.binary_loads() and vdf.binary_dumps(). You can also use the alt_format=True option for an alternative binary representation.

    VBKV

    Use vdf.vbkv_loads() and vdf.vbkv_dumps() for VBKV data.

    import vdf

# Binary VDF
d = vdf.binary_loads(vdf_bytes)
b = vdf.binary_dumps(d)

# Binary VDF with alternative format
d = vdf.binary_loads(vdf_bytes, alt_format=True)
b = vdf.binary_dumps(d, alt_format=True)

# VBKV (with header and CRC checking)
d = vdf.vbkv_loads(vbkv_bytes)
b = vdf.vbkv_dumps(d)

  4. Dump dictionary as VDF text

    master

    Convert a Python dictionary into a VDF text string using vdf.dumps(), or write it directly to a file using vdf.dump(). You can use the pretty=True argument to enable indentation.

    import vdf

# Dump to string
vdf_text = vdf.dumps(d)
indented_vdf = vdf.dumps(d, pretty=True)

# Dump to file
vdf.dump(d, open('file2.txt','w'), pretty=True)

  5. Parse VDF text from files or strings

    master

    Use vdf.load() or vdf.parse() to read VDF data from a file-like object, and vdf.loads() or vdf.parse() to read from a string. Note that vdf.parse and vdf.load are available for parsing.

    import vdf

# Parsing from a file
d = vdf.load(open('file.txt'))
d = vdf.parse(open('file.txt'))

# Parsing from a string
d = vdf.loads(vdf_text)
d = vdf.parse(vdf_text)

  6. Configure vdf2json CLI options

    master

    When using the vdf2json CLI, you can use the following flags to modify the conversion process:

    • -p, --pretty: Generates pretty-printed JSON output instead of a single line.
    • -ei encoding: Specifies the encoding of the input VDF file (e.g., utf8, utf-16le).
    • -eo encoding: Specifies the encoding for the output JSON file (e.g., utf8, utf-16le).
    • -h, --help: Displays the help message.
    optional arguments:
  -h, --help    show this help message and exit
  -p, --pretty  pretty json output
  -ei encoding  input encoding E.g.: utf8, utf-16le, etc
  -eo encoding  output encoding E.g.: utf8, utf-16le, etc

  7. Use the vdf2json CLI tool

    master

    The vdf2json command-line utility converts Valve Data Format (VDF) files into JSON format. It accepts an input VDF file and an output JSON file. By default, the output is UTF-8 encoded.

    usage: vdf2json [-h] [-p] [-ei encoding] [-eo encoding] [infile] [outfile]

positional arguments:
  infile        VDF
  outfile       JSON (utf8)

optional arguments:
  -h, --help    show this help message and exit
  -p, --pretty  pretty json output
  -ei encoding  input encoding E.g.: utf8, utf-16le, etc
  -eo encoding  output encoding E.g.: utf8, utf-16le, etc

  8. vdf2json CLI arguments and options

    master

    The vdf2json CLI accepts the following positional arguments and options:

    Positional Arguments:

    • infile: The source VDF file. If omitted, reads from stdin.
    • outfile: The destination JSON file. If omitted, writes to stdout.

    Options:

    • -p, --pretty: Enables pretty-printed JSON output (uses 4-space indentation).
    • -ei, --encoding (metavar: encoding): Sets the input encoding (e.g., utf-8, utf-16le). Defaults to utf-8.
    • -eo, --output-encoding (metavar: encoding): Sets the output encoding (e.g., utf-8, utf-16le). Defaults to utf-8.
    # Example: Convert with specific encoding and pretty print
vdf2json -ei utf-16le -eo utf-8 --pretty input.vdf output.json

  9. Use the vdf2json CLI to convert VDF to JSON

    master

    The vdf2json command-line tool converts Valve Data Format (VDF) files into JSON format. It supports reading from standard input (stdin) and writing to standard output (stdout) by default, or you can specify explicit input and output files. You can also control the character encoding for both input and output and enable pretty-printed JSON output.

    Basic Usage:

    vdf2json input.vdf > output.json
    vdf2json input.vdf output.json