ogs5py.fileclasses.base

Base Classes for the OGS Files.

File Classes

File([task_root, task_id, file_ext]) File class with minimal functionality.
LineFile([lines, name, file_ext, task_root, …]) OGS class to handle line-wise text files.
BlockFile([task_root, task_id, file_ext]) OGS Base class to derive all file formats.
MultiFile(base, **standard) Class holding mulitple files of the same type.

class BlockFile(task_root=None, task_id='model', file_ext='.std')[source]

Bases: ogs5py.fileclasses.base.File

OGS Base class to derive all file formats.

Parameters:
  • task_root (str, optional) – Path to the destiny model folder. Default: cwd+”ogs5model”
  • task_id (str, optional) – Name for the ogs task. Default: “model”
  • file_ext (str, optional) – extension of the file (with leading dot “.std”) Default: “.std”
Attributes:
block_no

Number of blocks in the file.

file_name

str: base name of the file with extension.

file_path

str: save path of the file.

force_writing

bool: state if the file is written even if empty.

is_empty

State if the OGS file is empty.

name

str: name of the file without extension.

Methods

add_block(self[, index, main_key]) Add a new Block to the actual file.
add_content(self, content[, main_index, …]) Add single-line content to the actual file.
add_copy_link(self, path[, symlink]) Add a link to copy a file instead of writing.
add_main_keyword(self, key[, main_index]) Add a new main keyword (#key) to the actual file.
add_multi_content(self, content[, …]) Add multiple content to the actual file.
add_sub_keyword(self, key[, main_index, …]) Add a new sub keyword ($key) to the actual file.
append_to_block(self[, index]) Append data to an existing Block in the actual file.
check(self[, verbose]) Check if the given file is valid.
del_block(self[, index, del_all]) Delete a block by its index.
del_content(self[, main_index, sub_index, …]) Delete content by its position.
del_copy_link(self) Remove a former given link to an external file.
del_main_keyword(self[, main_index, del_all]) Delete a main keyword (#key) by its position.
del_sub_keyword(self[, main_index, …]) Delete a sub keyword ($key) by its position.
get_block(self[, index, as_dict]) Get a Block from the actual file.
get_block_no(self) Get the number of blocks in the file.
get_file_type(self) Get the OGS file class name.
get_multi_keys(self[, index]) State if a block has a unique set of sub keywords.
is_block_unique(self[, index]) State if a block has a unique set of sub keywords.
read_file(self, path[, encoding, verbose]) Read an existing OGS input file.
reset(self) Delete every content.
save(self, path, \*\*kwargs) Save the actual OGS input file in the given path.
update_block(self[, index, main_key]) Update a Block from the actual file.
write_file(self) Write the actual OGS input file to the given folder.
add_block(self, index=None, main_key=None, **block)[source]

Add a new Block to the actual file.

Keywords are the sub keywords of the actual file type:

#MAIN_KEY
$SUBKEY1
content1 …
$SUBKEY2
content2 …

which looks like the following:

FILE.add_block(SUBKEY1=content1, SUBKEY2=content2)

Parameters:
  • index (int or None, optional) – Positional index, where to insert the given Block. As default, it will be added at the end. Default: None.
  • main_key (string, optional) – Main keyword of the block that should be added (see: MKEYS) Default: the first main keyword of the file-type
  • **block (keyword dict) – here the dict-keywords are the ogs-subkeywords and the value is the content that should be added with this ogs-subkeyword If a block should contain content directly connected to a main keyword, use this main keyword as input-keyword and the content as value: SUBKEY=content
add_content(self, content, main_index=None, sub_index=None, line_index=None)[source]

Add single-line content to the actual file.

Parameters:
  • content (list) – list containing one line of content given as a list of single statements
  • main_index (int, optional) – index of the corresponding main keyword where the sub keyword should be added. As default, the last main keyword is taken.
  • sub_index (int, optional) – index of the corresponding sub keyword where the content should be added. As default, the last sub keyword is taken.
  • line_index (int, optional) – position, where the new line of content should be added between the existing ones. As default, it is placed at the end.

Notes

There needs to be at least one main keyword, otherwise the content is not added.

If no sub keyword is present, a blank one (“”) will be added and the content is then directly connected to the actual main keyword.

Add a link to copy a file instead of writing.

Instead of writing a file, you can give a path to an existing file, that will be copied/linked to the target folder.

Parameters:
  • path (str) – path to the existing file that should be copied
  • symlink (bool, optional) – on UNIX systems it is possible to use a symbolic link to save time if the file is big. Default: False
add_main_keyword(self, key, main_index=None)[source]

Add a new main keyword (#key) to the actual file.

Parameters:
  • key (string) – key name
  • main_index (int, optional) – position, where the new main keyword should be added between the existing ones. As default, it is placed at the end.
add_multi_content(self, content, main_index=None, sub_index=None)[source]

Add multiple content to the actual file.

Parameters:
  • content (list) – list containing lines of content, each given as a list of single statements
  • main_index (int, optional) – index of the corresponding main keyword where the sub keyword should be added. As default, the last main keyword is taken.
  • sub_index (int, optional) – index of the corresponding sub keyword where the content should be added. As default, the last sub keyword is taken.

Notes

There needs to be at least one main keyword, otherwise the content is not added.

The content will be added at the end of the actual subkeyword.

If no sub keyword is present, a blank one (“”) will be added and the content is then directly connected to the actual main keyword.

add_sub_keyword(self, key, main_index=None, sub_index=None)[source]

Add a new sub keyword ($key) to the actual file.

Parameters:
  • key (string) – key name
  • main_index (int, optional) – index of the corresponding main keyword where the sub keyword should be added. As default, the last main keyword is taken.
  • sub_index (int, optional) – position, where the new sub keyword should be added between the existing ones. As default, it is placed at the end.

Notes

There needs to be at least one main keyword, otherwise the subkeyword is not added.

append_to_block(self, index=None, **block)[source]

Append data to an existing Block in the actual file.

Keywords are the sub keywords of the actual file type:

#MAIN_KEY
$SUBKEY1
content1 …
$SUBKEY2
content2 …

which looks like the following:

FILE.append_to_block(SUBKEY1=content1, SUBKEY2=content2)

Parameters:
  • index (int or None, optional) – Positional index, where to insert the given Block. As default, it will be added at the end. Default: None.
  • **block (keyword dict) – here the dict-keywords are the ogs-subkeywords and the value is the content that should be added with this ogs-subkeyword If a block should contain content directly connected to a main keyword, use this main keyword as input-keyword and the content as value: SUBKEY=content
check(self, verbose=True)

Check if the given file is valid.

Parameters:verbose (bool, optional) – Print information for the executed checks. Default: True
Returns:result – Validity of the given file.
Return type:bool
del_block(self, index=None, del_all=False)[source]

Delete a block by its index.

Parameters:
  • index (int or None, optional) – Positional index of the block of interest. As default, the last one is returned. Default: None
  • del_all (bool, optional) – State, if all blocks shall be deleted. Default: False
del_content(self, main_index=-1, sub_index=-1, line_index=-1, del_all=False)[source]

Delete content by its position.

Parameters:
  • main_index (int, optional) – index of the corresponding main keyword where the sub keyword should be deleted. As default, the last main keyword is taken.
  • sub_index (int, optional) – index of the corresponding sub keyword where the content should be deleted. As default, the last sub keyword is taken.
  • line_index (int, optional) – position of the content line, that should be deleted. Default: -1
  • del_all (bool, optional) – State, if all content shall be deleted. Default: False

Remove a former given link to an external file.

del_main_keyword(self, main_index=None, del_all=False)[source]

Delete a main keyword (#key) by its position.

Parameters:
  • main_index (int, optional) – position, which main keyword should be deleted. Default: -1
  • del_all (bool, optional) – State, if all main keywords shall be deleted. Default: False
del_sub_keyword(self, main_index=-1, sub_index=-1, del_all=False)[source]

Delete a sub keyword ($key) by its position.

Parameters:
  • main_index (int, optional) – index of the corresponding main keyword where the sub keyword should be deleted. As default, the last main keyword is taken.
  • pos (int, optional) – position, which sub keyword should be deleted. Default: -1
  • del_all (bool, optional) – State, if all sub keywords shall be deleted. Default: False
get_block(self, index=None, as_dict=True)[source]

Get a Block from the actual file.

Parameters:
  • index (int or None, optional) – Positional index of the block of interest. As default, the last one is returned. Default: None
  • as_dict (bool, optional) – Here you can state of you want the output as a dictionary, which can be used as key-word-arguments for add_block. If False, you get the main-key, a list of sub-keys and a list of content. Default: True
get_block_no(self)[source]

Get the number of blocks in the file.

get_file_type(self)

Get the OGS file class name.

get_multi_keys(self, index=None)[source]

State if a block has a unique set of sub keywords.

is_block_unique(self, index=None)[source]

State if a block has a unique set of sub keywords.

read_file(self, path, encoding=None, verbose=False)[source]

Read an existing OGS input file.

Parameters:
  • path (str) – path to the existing file that should be read
  • encoding (str or None, optional) – encoding of the given file. If None is given, the system standard is used. Default: None
  • verbose (bool, optional) – Print information of the reading process. Default: False
reset(self)[source]

Delete every content.

save(self, path, **kwargs)[source]

Save the actual OGS input file in the given path.

Parameters:
  • path (str) – path to where to file should be saved
  • update (bool, optional) – state if the content should be updated before saving. Default: True
update_block(self, index=None, main_key=None, **block)[source]

Update a Block from the actual file.

Parameters:
  • index (int or None, optional) – Positional index of the block of interest. As default, the last one is used. Default: None
  • main_key (string, optional) – Main keyword of the block that should be updated (see: MKEYS) This shouldn’t be done. Default: None
  • **block (keyword dict) – here the dict-keywords are the ogs-subkeywords and the value is the content that should be added with this ogs-subkeyword If a block should contain content directly connected to a main keyword, use this main keyword as input-keyword and the content as value: SUBKEY=content
write_file(self)

Write the actual OGS input file to the given folder.

Its path is given by “task_root+task_id+file_ext”.

MKEYS = []

Main Keywords of this OGS-BlockFile

Type:list
SKEYS = []

Sub Keywords of this OGS-BlockFile

Type:list
STD = {}

Standard Block OGS-BlockFile

Type:dict
block_no

Number of blocks in the file.

file_name

base name of the file with extension.

Type:str
file_path

save path of the file.

Type:str
force_writing

state if the file is written even if empty.

Type:bool
is_empty

State if the OGS file is empty.

name

name of the file without extension.

Type:str
class File(task_root=None, task_id='model', file_ext='.std')[source]

Bases: object

File class with minimal functionality.

Parameters:
  • task_root (str, optional) – Path to the destiny folder. Default is cwd+”ogs5model”
  • task_id (str, optional) – Name for the ogs task. Default: “model”
  • file_ext (str, optional) – extension of the file (with leading dot “.std”) Default: “.std”
Attributes:
file_name

str: base name of the file with extension.

file_path

str: save path of the file.

force_writing

bool: state if the file is written even if empty.

is_empty

bool: state if the OGS file is empty.

name

str: name of the file without extension.

Methods

add_copy_link(self, path[, symlink]) Add a link to copy a file instead of writing.
check(self[, verbose]) Check if the given file is valid.
del_copy_link(self) Remove a former given link to an external file.
get_file_type(self) Get the OGS file class name.
read_file(self, path[, encoding, verbose]) Read an existing file.
reset(self) Delete every content.
save(self, path, \*\*kwargs) Save the actual file in the given path.
write_file(self) Write the actual OGS input file to the given folder.

Add a link to copy a file instead of writing.

Instead of writing a file, you can give a path to an existing file, that will be copied/linked to the target folder.

Parameters:
  • path (str) – path to the existing file that should be copied
  • symlink (bool, optional) – on UNIX systems it is possible to use a symbolic link to save time if the file is big. Default: False
check(self, verbose=True)[source]

Check if the given file is valid.

Parameters:verbose (bool, optional) – Print information for the executed checks. Default: True
Returns:result – Validity of the given file.
Return type:bool

Remove a former given link to an external file.

get_file_type(self)[source]

Get the OGS file class name.

read_file(self, path, encoding=None, verbose=False)[source]

Read an existing file.

reset(self)[source]

Delete every content.

save(self, path, **kwargs)[source]

Save the actual file in the given path.

Parameters:path (str) – path to where to file should be saved
write_file(self)[source]

Write the actual OGS input file to the given folder.

Its path is given by “task_root+task_id+file_ext”.

file_name

base name of the file with extension.

Type:str
file_path

save path of the file.

Type:str
force_writing

state if the file is written even if empty.

Type:bool
is_empty

state if the OGS file is empty.

Type:bool
name

name of the file without extension.

Type:str
class LineFile(lines=None, name=None, file_ext='.txt', task_root=None, task_id='model')[source]

Bases: ogs5py.fileclasses.base.File

OGS class to handle line-wise text files.

Parameters:
  • lines (list of str, optional) – content of the file as a list of lines Default: None
  • name (str, optional) – name of the file without extension Default: “textfile”
  • file_ext (str, optional) – extension of the file (with leading dot “.txt”) Default: “.txt”
  • task_root (str, optional) – Path to the destiny model folder. Default: cwd+”ogs5model”
  • task_id (str, optional) – Name for the ogs task. (a place holder) Default: “model”
Attributes:
file_name

str: base name of the file with extension.

file_path

str: save path of the file.

force_writing

bool: state if the file is written even if empty.

is_empty

bool: state if the file is empty.

name

str: name of the file without extension.

Methods

add_copy_link(self, path[, symlink]) Add a link to copy a file instead of writing.
check(self[, verbose]) Check if the given text-file is valid.
del_copy_link(self) Remove a former given link to an external file.
get_file_type(self) Get the OGS file class name.
read_file(self, path[, encoding, verbose]) Read an existing OGS input file.
reset(self) Delete every content.
save(self, path) Save the actual line-wise file in the given path.
write_file(self) Write the actual OGS input file to the given folder.

Add a link to copy a file instead of writing.

Instead of writing a file, you can give a path to an existing file, that will be copied/linked to the target folder.

Parameters:
  • path (str) – path to the existing file that should be copied
  • symlink (bool, optional) – on UNIX systems it is possible to use a symbolic link to save time if the file is big. Default: False
check(self, verbose=True)[source]

Check if the given text-file is valid.

Parameters:verbose (bool, optional) – Print information for the executed checks. Default: True
Returns:result – Validity of the given file.
Return type:bool

Remove a former given link to an external file.

get_file_type(self)

Get the OGS file class name.

read_file(self, path, encoding=None, verbose=False)[source]

Read an existing OGS input file.

Parameters:
  • path (str) – path to the existing file that should be read
  • encoding (str or None, optional) – encoding of the given file. If None is given, the system standard is used. Default: None
  • verbose (bool, optional) – Print information of the reading process. Default: False
reset(self)[source]

Delete every content.

save(self, path)[source]

Save the actual line-wise file in the given path.

Parameters:path (str) – path to where to file should be saved
write_file(self)

Write the actual OGS input file to the given folder.

Its path is given by “task_root+task_id+file_ext”.

file_name

base name of the file with extension.

Type:str
file_path

save path of the file.

Type:str
force_writing

state if the file is written even if empty.

Type:bool
is_empty

state if the file is empty.

Type:bool
name

name of the file without extension.

Type:str
class MultiFile(base, **standard)[source]

Bases: object

Class holding mulitple files of the same type.

Parameters:
  • base (object) – Base class for the files
  • **standard – Standard keyword arguments for new instances of the Base class.
Attributes:
id

int: The current id to access in the file list.

Methods

add(self, \*args, \*\*kwargs) Add a new instance of the base class with *args and **kwargs.
append(self, file) Append a new file to the list.
delete(self[, file_id]) Delete a certain file.
reset_all(self) Reset the Multi File.
add(self, *args, **kwargs)[source]

Add a new instance of the base class with *args and **kwargs.

append(self, file)[source]

Append a new file to the list.

delete(self, file_id=-1)[source]

Delete a certain file.

reset_all(self)[source]

Reset the Multi File.

id

The current id to access in the file list.

Type:int