Version: 12.0.0

viktor.core

UserException

exception viktor.core.UserException¶

Bases: Exception

Exception that is shown to the user in the web-interface

ParamsFromFile

class viktor.core.ParamsFromFile(*, max_size=None, file_types=None)¶

Decorator that can be used on a pre-process method during a file upload, to produce the parameter set that is stored in the database.

Warning

Prevent storing the complete file content on the properties if the file is large, as this may cause speed and/or stability issues. The file content can be retrieved at all times using the API whenever necessary.

Example with nothing to store:

class Controller(ViktorController):
    ...

    @ParamsFromFile(...)
    def process_file(self, file: File, **kwargs):  # viktor.core.File
        return {}

Example with parameters to store:

class Controller(ViktorController):
    ...

    @ParamsFromFile(...)
    def process_file(self, file: File, **kwargs):  # viktor.core.File
        # app specific parsing logic
        file_content = file.getvalue()  # or use reading in chunks, for large files
        number_of_entries = ...
        project_name = ...

        # linking the parsed output to the parametrization fields (names in database)
        return {
            'tab.section.number_of_entries': number_of_entries,
            'tab.section.project_name': project_name
        }

Warning

Loading the content of a large file in memory (file.getvalue()) may cause the app to crash (out-of-memory). Read the file content in chunks to avoid such memory issues (see File).

Parameters

max_size (Optional[int]) – optional restriction on file size in bytes (e.g. 10 000 000 = 10 MB).
file_types (Optional[Sequence[str]]) – optional restriction on file type(s) (e.g. [‘.png’, ‘.jpg’, ‘.jpeg’]). Note that the extensions are filtered regardless of capitalization.

ViktorController

class viktor.core.ViktorController(**kwargs)¶: The main function of the ViktorController is to “control” the information flow between the frontend (what is inputted by a user) and the application code (what is returned as a result of the user input).

File

class viktor.core.File(*, data=None, path=None, url=None)¶

Creates a File object. Only 1 of data, path or url should be set, or File() for writable file. Or use the corresponding class-methods.

A File object can have one of the following 4 types:

SourceType.DATA: File object with in-memory data as its source

Created with File.from_data(…)

writable: False

SourceType.PATH: File object with an existing file (path) as its source

Created with File.from_path(…)

writable: False

SourceType.URL: File object with a URL as its source

Created with File.from_url(…)

writable: False

SourceType.WRITABLE: File object with a (temporary) writable file on disk as its source

Created with File()

writable: True (writing always takes place at end of file)

Note: Reading from a File with SourceType.URL downloads (part of the) URL content to a (temporary) file on disk, so that re-reading (previously read) content within the same open-context does not require downloading twice. Opening the File object a second time DOES involve downloading the content anew. If such a File needs to be opened multiple times, consider copying the File locally (copy()), so that downloading takes place only once.

Example usage:

data_file = File.from_data("my content")
path_file = File.from_path(Path(__file__).parent / "my_file.txt")
url_file = File.from_url("https://...")
writable_file = File()

data_content = data_file.getvalue_binary()  # bytes (b"my content")
path_content = path_file.getvalue()  # str

with url_file.open() as r:  # open in text-mode, so read -> str
    first_character = r.read(1)  # downloads only partially
    all_other_characters = r.read()  # downloads the rest

with writable_file.open_binary() as w:  # open as binary-mode, so read/write -> bytes
    w.write(b"my content")

writable_content = writable_file.getvalue()  # "my content"

Parameters

data (Union[str, bytes, None]) – in-memory data source (also from_data())
path (Union[str, bytes, PathLike, None]) – existing file path source (also from_path())
url (Optional[str]) – URL source (also from_url())

class SourceType(value)¶

Bases: enum.Enum

An enumeration.

DATA: viktor.core.File.SourceType = 1¶

PATH: viktor.core.File.SourceType = 2¶

URL: viktor.core.File.SourceType = 3¶

WRITABLE: viktor.core.File.SourceType = 4¶

classmethod from_data(data)¶

Create a File object with in-memory data as its source.

Return type: File

classmethod from_path(path)¶

Create a File object with an existing file (path) as its source.

Return type: File

classmethod from_url(url)¶

Create a File object with a URL as its source.

Return type: File

property source¶

Source of the File object:

SourceType.DATA -> None
SourceType.PATH -> path of (readable) file on disk
SourceType.URL -> url
SourceType.WRITABLE -> path of (writable) file on disk

Return type: Optional[str]

property source_type¶

Source type of the file.

Return type: SourceType

property writable¶

Whether the File is writable or not (only True for SourceType.WRITABLE).

Return type: bool

open(encoding=None)¶

Open the file in text-mode.

Parameters: encoding (Optional[str]) – encoding used for reading the bytes -> str (default: default local encoding)
Return type: TextIO
Returns: opened text file

open_binary()¶

Open the file in binary-mode.

Return type: BinaryIO
Returns: opened binary file

getvalue(encoding=None)¶

Read the content (text) of the file in memory. For large files, open the file and read in chunks, to prevent the app from running out of memory.

Return type: str

getvalue_binary()¶

Read the content (binary) of the file in memory. For large files, open the file and read in chunks, to prevent the app from running out of memory.

Return type: bytes

copy(writable=False)¶

Make a local copy of the file to disk.

Example usages:

URL-file that needs to be opened multiple times:

# copying to path-file prevents re-downloading if opening more than once.
path_file = url_file.copy()  # download the complete content locally

with path_file.open() as r:  # no downloading
    ...

with path_file.open() as r:  # no downloading
    ...

Make writable file from read-only file:

writable_file = read_only_file.copy(writable=True)

with writable_file.open() as w:
    w.write("my content")

Parameters: writable (bool) – True to return writable file, False for read-only (default: False).
Return type: File
Returns: File object (SourceType.WRITABLE if writable = True, else SourceType.PATH).

Color

class viktor.core.Color(r: int, g: int, b: int)¶

Bases: viktor.core.Color

Create an immutable instance of Color

Parameters

r – red-value (0-255)
g – green-value (0-255)
b – blue-value (0-255)

static black()¶

Return type: Color

static white()¶

Return type: Color

static red()¶

Return type: Color

static lime()¶

Return type: Color

static green()¶

Return type: Color

static blue()¶

Return type: Color

static viktor_black()¶

Return type: Color

static viktor_blue()¶

Return type: Color

static viktor_yellow()¶

Return type: Color

classmethod from_hex(hex_value)¶

Color defined by hexadecimal code.

Return type: Color

classmethod from_deltares(value)¶

Color defined by Deltares-type integer.

Parameters: value (int) – Integer representation of the color as used in the Deltares software series.
Return type: Color

static random()¶

Generate a random color.

Return type: Color

property rgb¶

Return type: Tuple[int, int, int]

property hex¶

Hexadecimal representation of the color.

Return type: str

property deltares¶

Return type: int

static rgb_to_hex(r, g, b, include_hashtag=True)¶

Conversion from red-green-blue to hexadecimal value

Return type: str

static hex_to_rgb(hex_value)¶

Conversion from hexadecimal to red-green-blue value

Return type: Tuple[int, int, int]

static rgb_to_deltares(r, g, b)¶

Conversion from Deltares-type color value to red-green-blue value.

:return Integer representation of the color as used in the Deltares software series.

Return type: int

static deltares_to_rgb(value)¶

Conversion from red-green-blue to Deltares-type color value.

Parameters: value (int) – Integer representation of the color as used in the Deltares software series.
Return type: Tuple[int, int, int]

progress_message

viktor.core.progress_message(message, percentage=None)¶

Send a user facing progress message informing the progress of an evaluation. Messages are truncated to 500 characters

Parameters

message (str) – Message shown to the user
percentage (Union[int, float, None]) – Value between 0 and 100 quantifying the progress

Return type

None

make_data_json_serializable

viktor.core.make_data_json_serializable(input_data)¶

The python built-in json dump does not support all the desired types. This function converts those, thereby enabling broader json conversion.

numpy number types -> equivalent python builtin
datetime.datetime and datetime.date -> isoformat str
tuple -> list (otherwise sub elements cannot be converted due to tuple immutability)

Return type: Any

viktor.core

UserException​

ParamsFromFile​

ViktorController​

File​

Color​

progress_message​

make_data_json_serializable​

UserException

ParamsFromFile

ViktorController

File

Color

progress_message

make_data_json_serializable