KFFile¶

class KFFile(filename: str, omode: OpenMode = OpenMode.Any)¶

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.

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.

read(section: str = '', variable: str = '', return_as_list: bool = False, string_separator: StringSep | None = None) → 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) → ndarray[Any, dtype[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) → ndarray[Any, dtype[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) → ndarray[Any, dtype[float64]]¶

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

read_section(section: str) → Dict[str, 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) → 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.

property filename: str¶

The filename of the file managed by this KFFile instance.

property path: str¶

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

class KFError¶

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