Skip to main content
Version: 12.9.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,
                    '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).

label: str

Entity-type label.

children: Optional[List[str]] = None

Optional list of child entity-types.

show_children_as: Optional[str] = None

When children are defined, specify how they are shown in the interface (‘Table’ | ‘Cards’).

summary: Optional[Summary] = None

viktor.views.Summary of the entity-type.

parametrization: Optional[Parametrization] = None

viktor.parametrization.Parametrization that describes the entity-type.

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: Optional[str]

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: viktor.core.File.SourceType

Source type of the file.

Return type

SourceType

property writable: bool

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: Tuple[int, int, int]
Return type

Tuple[int, int, int]

property hex: str

Hexadecimal representation of the color.

Return type

str

property deltares: int
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 (Optional[float]) – 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