KFFile

See also

The AKFReader Python class provides a convenient alternative for reading data from KF files.

class KFFile(filename: str, omode: OpenMode = <OpenMode.Any: 0>)

A class representing a file in KF format. Allows inspecting, reading and writing KF files.

class OpenMode(value)

Enum representing the mode in which a file should be opened.

Values:

• Any: Open an existing file or create a new file.

• New: Creates a new file. If the file already exists, a KFError exception may be thrown.

• Old: Open an existing file. If the file does not exist, a KFError exception may be thrown.

class StringSep(value)

Enum representing the separator used to delimit elements in arrays of strings:

Values:

• NullChar: The strings are separated with the C-style \0 character.

• NewLine: The strings are separated with the \n newline character.

• LCHARS: When writing each string is padded or truncated to a width of LCHARS=160 characters. The total length of the variable is thus a multiple of 160. When reading, the variable is split into sections of 160 characters again, representing the individual elements of the array.

class VarType(value)

Enum representing type of a variable on a KF file.

Values:

• Empty: indicates an empty index slot

• Int: a variable of integer type

• Real: a variable of real type

• Char: a variable of string type

• Logical: a variable of logical type

close() → None

Closes the file. No further methods should be called on a file that has been closed.

close_var() → None

Closes a variable.

copy_section(from_kf: KFFile, to_kf: KFFile, section: str) → None

copy_section(from_kf: KFFile, to_kf: KFFile, from_section: str, to_section: str) → None

Helper for @overload to raise when called.

create_section(section: str) → None

Creates a new section on the KF file.

create_var(section: str, variable: str, n: int, type: VarType) → None

Creates a new variable on the file of a given length and type.

classmethod delete_file(filename: str) → None

Deletes a KF file from disk after checking that no other KFFile instances reference that file.

delete_section(section: str) → None

Deletes a section and all of the contained variables from the file.

delete_var(section: str, variable: str) → None

Deletes a variable from the KF file.

property filename

The filename of the file managed by this KFFile instance.

get_skeleton() → Dict[str, Set[str]]

Return a dictionary reflecting the structure of this KF file.

Each key in that dictionary corresponds to a section name of the KF file with the value being a set of variable names.

classmethod is_kffile(filename: str) → bool

Checks if a file has the KF format, aka it is a properly formatted KF file.

num_sections() → int

Returns the number of sections existing on the file.

num_variables(section: str) → int

Returns the number of variables in a section.

open_var(section: str, variable: str) → None

Opens a variable for reading and writing. Mostly useful if you incrementally want to read/write data from/to it.

property path

The absolute path to the file managed by this KFFile instance.

read(section: str = '', variable: str = '', return_as_list: bool = False, string_separator: Optional[StringSep] = None) → Union[bool, int, float, str, List[bool], List[int], List[float], List[str]]

Extract and return data for a variable located in a section.

By default, for single-value numerical or boolean variables returned value is a single number or bool. For longer variables this method returns a list of values. This behavior can be changed by setting return_as_list parameter to True. In that case the returned value is always a list of numbers (possibly of length 1).

For string variables this works a bit differently: the return_as_list argument is ignored. Instead an optional KFFile.StringSep can be given as a separator. If any separator is give, the return value will always be a list of strings (possibly of length 1 if there is nothing to be separated). If no separator is given, the return value is always a single string.

This method exists primarily for backwards compatibility with the plams.KFFile. For new code we recommend using the strongly typed read_*() methods instead, e.g. read_int().

read_int(section: str, variable: str) → int

Reads a single integer from a specific section and variable.

read_ints(section: str, variable: str) → List[int]

Reads a list of integers from a specific section and variable.

read_ints_np(section: str, variable: str) → numpy.ndarray[Any, numpy.dtype[numpy.int64]]

Reads integers from a specific section and variable into a numpy array.

read_logical(section: str, variable: str) → bool

Reads a single logical value from a specific section and variable.

read_logicals(section: str, variable: str) → List[bool]

Reads a list of logical values from a specific section and variable.

read_logicals_np(section: str, variable: str) → numpy.ndarray[Any, numpy.dtype[numpy.bool_]]

Reads logical values from a specific section and variable into a numpy array.

read_real(section: str, variable: str) → float

Reads a single real number from a specific section and variable.

read_reals(section: str, variable: str) → List[float]

Reads a list of real numbers from a specific section and variable.

read_reals_np(section: str, variable: str) → numpy.ndarray[Any, numpy.dtype[numpy.float64]]

Reads real numbers from a specific section and variable into a numpy array.

read_section(section: str) → Dict[str, Union[bool, int, float, str, List[bool], List[int], List[float], List[str]]]

Return a dictionary with all variables from a given section.

Note: Some sections can contain very large amount of data.

Turning them into dictionaries can cause memory shortage or performance issues. Use this method carefully …

read_string(section: str, variable: str) → str

Reads a single string from a specific section and variable.

read_strings(section: str, variable: str, sep: StringSep = <StringSep.LCHARS: 2>) → List[str]

Reads a list of strings from a specific section and variable.

rewind_var() → None

Rewinds a variable. Incremental reading and writing will then start from the beginning of the variable again.

save() → None

Write all internal buffers to disk (or at least the OS cache). It’s basically a flush …

section_exists(section: str) → bool

Check if a section exists on the file.

sections() → List[str]

Returns a list of all sections on the file.

skip_var(n: int) → None

Skip forward over a number of elements in the variable.

var_exists(section: str, variable: str) → bool

Check if a variable exists on the file.

var_length(section: str, variable: str) → int

Returns the allocated length of variable on file. This is the maximum number of elements that can be written to it without reallocation.

var_type(section: str, variable: str) → VarType

Returns the type of the elements of a variable.

var_used(section: str, variable: str) → int

Returns the number of elements written to a variable.

variables(section: str) → List[str]

Returns a list of all variables in a section.

write(value: bool) → None

write(value: int) → None

write(value: float) → None

write(value: str) → None

write(value: List[bool]) → None

write(value: List[int]) → None

write(value: List[float]) → None

write(value: List[str]) → None

write(section: str, variable: str, value: bool) → None

write(section: str, variable: str, value: int) → None

write(section: str, variable: str, value: float) → None

write(section: str, variable: str, value: str) → None

write(section: str, variable: str, value: List[bool]) → None

write(section: str, variable: str, value: List[int]) → None

write(section: str, variable: str, value: List[float]) → None

write(section: str, variable: str, value: List[str], sep: StringSep = StringSep.LCHARS) → None

Helper for @overload to raise when called.

class KFError

Error thrown for all KF issues, e.g. reading of non-existing variables or reading as wrong datatypes.