O formato VDF (Valve Data Format), também conhecdio como KeyValues, é uma estrutura de serialização de dados amplamente utilizada pela Valve Corporation em seus jogos (como Counter-Strike e Dota 2) e na própria plataforma Steam para arquivos de configuração e metadadso. A biblioteca vdf para Python oferece uma interface eficiente para converter esses dados em dicionários nativos do Python e vice-versa, suportando tanto o formato de texto legível quanto o formato binário.

Instalação do Pacote

Para começar a utilizar a biblioteca, instale-a via gerenciador de pacotes pip:

pip install vdf

Caso precise da versão mais recente diretamente do repositório de desenvolvimento, utilize:

pip install git+https://github.com/ValvePython/vdf.git

Processamento de Arquivos VDF em Texto

A biblioteca opera de forma muito semelhante aos módulos json ou pickle do Python, utilizando os métodos load, loads, dump e dumps.

Leitura de dados

import vdf

# Carregando a partir de uma string estruturada
conteudo_vdf = """
"AppSettings"
{
    "appid" "730"
    "name" "Counter-Strike: Global Offensive"
    "StateFlags" "4"
}
"""
dados_objeto = vdf.loads(conteudo_vdf)
print(dados_objeto['AppSettings']['name'])

# Lendo diretamente de um arquivo físico
with open('config_jogo.vdf', 'r', encoding='utf-8') as arquivo:
    configuracoes = vdf.load(arquivo)

Escrita de dados

import vdf

preferencias = {
    'VideoConfig': {
        'width': '1920',
        'height': '1080',
        'fullscreen': '1'
    }
}

# Gerando uma string formatada
string_vdf = vdf.dumps(preferencias, pretty=True)

# Salvando em um arquivo novo
with open('saida_config.vdf', 'w') as arquivo_saida:
    vdf.dump(preferencias, arquivo_saida, pretty=True)

Trabalhando com Formatos Binários

Além da versão em texto, o formato VDF possui variações binárias utilizadas para otimização de performance. A biblioteca lida com essas variações, incluindo o formato VBKV.

import vdf

# Exemplo de processamento de bytes binários
dados_binarios = b'\x00\x01\x02...' # Exemplo representativo
dicionário_extraido = vdf.binary_loads(dados_binarios)

# Convertendo um dicionário para o formato binário da Valve
buffer_binario = vdf.binary_dumps(dicionário_extraido)

# Suporte ao formato alternativo (VBKV)
dados_vbkv = vdf.binary_loads(dados_binarios, alt_format=True)

Gerenciamento de Chaves Duplicadas e Ordenação

Diferente dos dicionários padrão do Python em versões antigas, os arquivos VDF frequentemente dependem da ordem das chaves ou permitem chaves duplicadas. Para garantir a integridade desses dados, a biblioteca disponibiliza a classe VDFDict.

from vdf import VDFDict

# Criando um dicionário que preserva a ordem e aceita chaves repetidas
estrutura_especial = VDFDict()
estrutura_especial['item'] = 'valor1'
estrutura_especial['item'] = 'valor2' # Em um dict comum, isso sobrescreveria

# O vdf.load() pode ser configurado para usar VDFDict automaticamente
with open('arquivo_complexo.vdf', 'r') as f:
    dados_ordenados = vdf.load(f, mapper=VDFDict)

Casos de Uso Comuns

• Modificação de Configurações de Jogos: Automação de ajustes em arquivos como gamestate_integration ou configurações de servidores dedicados.
• Análise de Inventários Steam: Processamento de arquivos locais da Steam que armazenam informações sobre a biblioteca de jogos do usuário.
• Ferramentas de Modding: Criação de instaladores de modificações que precisam injetar entradas em manifestos de jogos sem corromper a estrutura original.

A biblioteca é compatível com uma ampla gama de versões do Python, incluindo 2.7, 3.3+ e implementações PyPy, o que a torna uma escolha robusta para integração em ferramentas de backend ou scripts de automação local.