Overview

Path PyPoE/poe/file/shared/keyvalues.py
Version 1.0.0a0
Revision $Id: c3236a16d9c21ca3a3ccbd735d839efea4b2bd37 $
Author Omega_K2

Description

Shared abstract classes for files that contain key-value pairs.

When implementing support for other file types that use the generic key-value format GGG uses, the file should subclass the files found here and appropriately change the logic.

The key value format is generally something like this:

SectionName
{
    key = value
    key = "quoted value"
}

Warning

None of the abstract classes found here should be instantiated directly.

See also:

Agreement

See PyPoE/LICENSE

Documentation

Abstract Classes

class PyPoE.poe.file.shared.keyvalues.AbstractKeyValueSection(parent, name=None, *args, **kwargs)[source]

Bases: dict

class PyPoE.poe.file.shared.keyvalues.AbstractKeyValueFile(parent_or_base_dir_or_ggpk=None, version=None, extends=None, keys=None)[source]

Bases: PyPoE.poe.file.shared.AbstractFile, collections.defaultdict

Variables:
read(file_path_or_raw, *args, **kwargs)

Reads the file contents into the specified path or buffer. This will also reset any existing contents of the file.

If a buffer or bytes was given, the data will be read from the buffer or bytes object.

If a file path was given, the resulting data will be read from the specified file.

Parameters:
  • file_path_or_raw (BytesIO | bytes | str) – file path, bytes or buffer to read from
  • args – Additional positional arguments
  • kwargs – Additional keyword arguments
Returns:

result of the read operation, if any
Return type:

object
Raises:

TypeError – if file_path_or_raw has an invalid type
get_read_buffer(file_path_or_raw, function, *args, **kwargs)

Will attempt to open the given file_path_or_raw in read mode and pass the buffer to the specified function. The function must accept at least one keyword argument called ‘buffer’.

Parameters:
  • file_path_or_raw (BytesIO | bytes | str) – file path, bytes or buffer to read from
  • args – Additional positional arguments to pass to the specified function
  • kwargs – Additional keyword arguments to pass to the specified function
Returns:

Result of the function
Return type:

object
Raises:

TypeError – if file_path_or_raw has an invalid type
write(*args, **kwargs)[source]

Write the contents of file to the specified path or buffer.

If a buffer or bytes was given, a buffer object with the new data should be returned.

If a file path was given, the resulting data should be written to the specified file.

Parameters:
  • file_path_or_raw (BytesIO | bytes | str) – file path, bytes or buffer to write to
  • args – Additional positional arguments
  • kwargs – Additional keyword arguments
Returns:

result of the write operation, if any
Return type:

object
Raises:

TypeError – if file_path_or_raw has an invalid type

Warning

The current values held by the file instance will be written. This means values inherited from parent files will also be written.

get_write_buffer(file_path_or_raw, function, *args, **kwargs)

Will attempt to open the given file_path_or_raw in write mode and pass the buffer to the specified function. The function must accept at least one keyword argument called ‘buffer’.

Parameters:
  • file_path_or_raw (BytesIO | bytes | str) – file path, bytes or buffer to write to
  • args – Additional positional arguments to pass to the specified function
  • kwargs – Additional keyword arguments to pass to the specified function
Returns:

Result of the function
Return type:

object
Raises:

TypeError – if file_path_or_raw has an invalid type
_read(buffer, *args, **kwargs)[source]
Parameters:buffer (io.BytesIO) – The file/byte buffer
_write(buffer, *args, **kwargs)[source]
Parameters:buffer (io.BytesIO) – The file/byte buffer
merge(other)[source]

Merge with other file.

Parameters:other (AbstractKeyValueFile) – Instance of the other file to merge with
Raises:ValueError – if other has a different type then this instance
class PyPoE.poe.file.shared.keyvalues.AbstractKeyValueFileCache(path_or_ggpk=None, files=None, files_shortcut=True, instance_options=None, read_options=None)[source]

Bases: PyPoE.poe.file.shared.cache.AbstractFileCache

FILE_TYPE

alias of AbstractKeyValueFile

__init__(path_or_ggpk=None, files=None, files_shortcut=True, instance_options=None, read_options=None)
Parameters:
  • path_or_ggpk (str | GGPKFile) – The root path (i.e. relative to content.ggpk) where the files are stored or a PyPoE.poe.file.ggpk.GGPKFile instance
  • files (Iterable) – Iterable of files that will be loaded right away
  • files_shortcut (bool) – Whether to use the shortcut function, i.e. self.__getitem__
  • instance_options (dict[str, object]) – options to pass to the file’s __init__ method
  • read_options (dict[str, object]) – options to pass to the file instance’s read method
Raises:
_create_instance(file_name, *args, **kwargs)

Creates a new instance for the given file name

Parameters:file_name (str) – Name to the file to pass on
Returns:
Return type:File instance
_get_file_instance_args(file_name)[source]

Returns a dictionary of keyword arguments to pass to the file’s __init__ method upon initial reading.

Parameters:file_name (str) – Name of the file
Returns:Dictionary of keyword arguments
Return type:dict[str, object]
_get_read_args(file_name, *args, **kwargs)

Returns a dictionary of keyword arguments to pass to the file’s read method upon initial reading.

In particular it sets file_path_or_raw based on how the cache was instantiated.

Parameters:file_name (str) – Name of the file
Returns:Dictionary of keyword arguments
Return type:dict[str, object]
get_file(file_name, *args, **kwargs)

Returns the the specified file from the cache.

If the file does not exist, read it from the path specified on cache creation, add it to the cache and then return it.

Parameters:file_name (str) – File to retrieve
Returns:read file instance
Return type:AbstractFileReadOnly
path_or_ggpk

The path or PyPoE.poe.file.ggpk.GGPKFile instance the cache was created with

Exceptions & Warnings

class PyPoE.poe.file.shared.keyvalues.DuplicateKeyWarning[source]

Bases: PyPoE.poe.file.shared.ParserWarning

Warning for keys that are not explicitly specified to be overridden.

__init__

Initialize self. See help(type(self)) for accurate signature.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class PyPoE.poe.file.shared.keyvalues.OverriddenKeyWarning[source]

Bases: PyPoE.poe.file.shared.ParserWarning

Warning for keys that are overridden during a merge.

__init__

Initialize self. See help(type(self)) for accurate signature.

with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.