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)

   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.
