eezz package

Submodules

Module contents

module eezz.table

This module implements the following classes:

• eezz.table.TTableCell: Defines properties of a table cell

• eezz.table.TTableCellDetail: Defines a list of cell details, used to store multiple values

• eezz.table.TTableRow: Defines properties of a table row, containing a list of TTableCells

• eezz.table.TTableColumn: Defines properties of a table column

• eezz.table.TTable: Defines properties of a table, containing a list of TTableRows

• eezz.table.TTableException: Exception on checking the row-id, which has to be unique

TTable is used for formatted ASCII output of a table structure. It allows to access the table data for further processing e.g. for HTML output. The class handles an internal read cursor, which allows to navigate in the list of rows and to read a fixed amount of rows.

TTable is a list of TTableRow objects, each of which is a list of TCell objects. The TTableColumn holds the as well column names as types and is used to organize sort and filter. A TTableCell object could hold a TTable object for recursive tree structures.

Besides this the following enumerations are used

• eezz.table.TNavigation: Enumeration for method eezz.table.TTable.navigate()

• eezz.table.TSort: Enumeration for method eezz.table.TTable.do_sort()

class eezz.table.TTable(column_names, title)

Bases: UserList

The table extends UserList to enable list management and inherits methods like sort This class is decorated as dataclass

Parameters:

• column_names (List[str]) – List of names for each column

• title (str) – Table name and title

Variables:

format_types (Dict[str, Callable[size, value]]) – A map for types and format rules. The callable takes two variables, the width and the value.

Examples

Table instance:

>>> from table import TTable
>>> my_table = TTable(column_names=['FileName', 'Size'], title='Directory')
>>> # for file in Path('.').iterdir():
>>> #    my_table.append(table_row=[file, file.stat().st_size])
>>> row1 = my_table.append(table_row=['.idea',        4096])
>>> row2 = my_table.append(table_row=['directory.py', 1699])
>>> row3 = my_table.append(table_row=['__init__.py',    37])
>>> row4 = my_table.append(table_row=['__pycache__',  4096])
>>> debug_out = io.StringIO()
>>> my_table.print(file=debug_out)
>>> print(debug_out.getvalue()[:-1])
Table: Directory
| FileName     | Size |
| .idea        | 4096 |
| directory.py | 1699 |
| __init__.py  |   37 |
| __pycache__  | 4096 |

This is a possible extension of a format for type iban, breaking the string into chunks of 4:

>>> iban = 'de1212341234123412'
>>> my_table.format_types['iban'] = lambda x_size, x_val: f"{(' '.join(re.findall('.{1,4}', x_val))):>{x_size}}"
>>> print(f"{my_table.format_types['iban'](30, iban)}")
        de12 1234 1234 1234 12

append(table_row: list, attrs: dict = None, row_type: str = 'body', row_id: str = '', exists_ok=False) → TTableRow

Appends a new row to the table. The new row can include custom attributes, a specified type, and a unique identifier. If row_id already exists in the table, the function will handle it based on the exists_ok parameter. Appropriate cell types, widths, and descriptors are determined and updated accordingly. The added row is indexed and stored within the table structure.

Parameters:

• table_row (list) – List of values representing a single row in the table.

• attrs (dict) – Optional dictionary of attributes for the table row.

• row_type (str) – Type of the row, default is ‘body’.

• row_id (str) – Unique identifier for the row. If not provided, defaults to the row index.

• exists_ok (bool) – If True, allows appending of a row with an existing row_id without raising an exception.

Returns:

The newly created table row object.

Return type:

TTableRow

static create_filter(filter_descr: List[List[str]]) → tuple

Constructs a SQL filter query and its corresponding arguments from a structured filter description. The filter description consists of nested lists representing conditions connected by logical “and” and “or” operators. Each condition within “and” is specified as a string with a column name, an operator, and a value.

Parameters:

filter_descr (List[List[]]) – A list of lists where each inner list contains strings representing individual conditions in the format “<column_name> <operator> <value>”.

Returns:

A tuple containing the constructed SQL filter query as a string and a list of arguments corresponding to the placeholders in the SQL query.

Return type:

tuple

do_select(get_all: bool = False, filter_descr: list = None) → list

Executes a SELECT statement on the SQLite database associated with the current object and retrieves data based on the specified filter and options. The data can be fetched from an existing database or an in-memory table. Supports optional sorting and offset logic.

The method allows focusing on retrieving either all records or a subset defined by internal pagination settings. It uses SQLite3 with Python’s datetime support for converting date and time objects seamlessly. The method supports custom filtering through the filter_descr argument, which works with predefined column descriptions to create conditional where clauses.

Parameters:

• get_all (bool) – A boolean flag indicating whether to retrieve all records from the database. If set to True, the method retrieves all available data. If set to False, the method retrieves a limited number of records based on the current pagination settings.

• filter_descr (List[List[]]) – A list of filters to be applied during the data selection. These filters guide the construction of the SQL WHERE clause and determine which records are included in the result set.

Returns:

A list containing the fetched records from the database. The records fetched are determined by filter conditions or sorting and pagination settings depending on the provided arguments.

do_sort(column: int | str, reverse: bool = False) → TTable

Sorts the table by a specified column. This method allows sorting in ascending or descending order based on the reverse flag. The column to be sorted can be specified using either its index or name.

Parameters:

• column (int|str) – The column by which the table should be sorted. It can be specified as an integer (index) or a string (name).

• reverse (bool) – Determines the order of sorting. If True, the table is sorted in descending order; otherwise, it is sorted in ascending order. Default is False.

Returns:

The sorted table object.

Return type:

TTable

filter_columns(column_names: Dict[str, str]) → None

The column_names is a dictionary with a set of keys as subset of TTable.column_names. The values are translated names to display in output. The order of the keys represents the order in the output. The filter is used to generate customized output. This function could also be used to reduce the number of visible columns

Parameters:

column_names (Dict[str, str]) – Map new names to a column, e.g. after translation

Example:

>>> my_table = TTable(column_names=['FileName', 'Size'], title='Directory')
>>> my_table.filter_columns(column_names={'Size':'Größe', 'FileName': 'Datei'})
>>> row1 = my_table.append(['.idea',        4096])
>>> row2 = my_table.append(['directory.py', 1886])
>>> row3 = my_table.append(['__init__.py',    37])
>>> row4 = my_table.append(['__pycache__',  4096])
>>> debug_out = io.StringIO()
>>> my_table.print(file=debug_out)
>>> print(debug_out.getvalue()[:-1])
Table: Directory
| Größe | Datei        |
|  4096 | .idea        |
|  1886 | directory.py |
|    37 | __init__.py  |
|  4096 | __pycache__  |

get_header_row() → TTableRow

Retrieves the header row of a table, applying a filter to the columns if necessary. If the apply_filter_column attribute is set to True, selects the visible columns according to the order specified in column_names_filter and maps these columns to new names specified in column_names_alias.

Returns:

The table header row, potentially filtered and with aliased column names, encapsulated in a TTableRow object.

Return type:

TTableRow

get_next_values(search_filter: Callable[[TTableRow], bool]) → tuple

Iterates over rows in the dataset and yields a tuple of values for each row that matches the given search filter. The search filter is a callable that should return a boolean indicating whether a particular row matches the criteria.

Parameters:

search_filter (Callable[[TTableRow, bool]]) – A callable function that takes a TTableRow object and returns a boolean indicating whether the row matches the criteria.

Returns:

Tuple of values from each matched row.

get_visible_rows(get_all: bool = False) → List[TTableRow]

Retrieves visible rows from the data source. The rows are filtered based on column descriptions and filter expressions, and can be further controlled by whether all rows should be retrieved or just a limited visible set.

Parameters:

get_all (bool) – Determines whether to retrieve all rows without counting against the visible items limit. Defaults to False.

Returns:

A generator yielding visible rows that match the filter criteria.

Return type:

List[TTableRow]

id: str = None

navigate(where_togo: int = 1, position: int = 0) → None

Adjusts the current navigation offset based on the specified navigation command and position. It calculates a new offset value for navigating within a data structure while ensuring that boundaries are respected. The offset determines the starting point for visible items and can be adjusted using different navigation strategies such as moving to the next, previous, absolute position, top, or last items in the structure.

Parameters:

• where_togo (int) – Determines the navigation strategy. The navigation can be to the ‘NEXT’ item, ‘PREV’ item, an ‘ABS’olute position, ‘TOP’ of the data, or the ‘LAST’ item.

• position (int) – Used when the ‘ABS’ navigation strategy is selected. Determines the target position for the offset in the data structure.

Returns:

None

navigation(value)

alias of TNavigation

on_select(row: str) → TTableRow | None

Updates the pointer to the selected row in the table if a row with the given index exists and returns this row. If the row does not exist, it returns None.

Parameters:

row (str) – The unique identifier for the table row that is to be selected.

Returns:

The selected table row if it exists, otherwise None.

print(level: int = 0, file=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>) → None

Prints the table with the specified formatting and indentation level. The table headers are determined based on the column descriptions, and the rows are printed with respect to the visibility and formatting criteria applied. Each row can have a hierarchy with child rows being printed recursively at increasing indentation levels.

Parameters:

• level (int) – The indentation level to be applied to the printed table. Default is 0. This affects the amount of whitespace before the table data, enhancing readability for nested (child) tables.

• file (TextIO) – An optional output stream to which the table will be printed. Default is sys.stdout, which represents standard output.

Returns:

This function does not return any value. It directly prints the formatted table to the specified output.

visible_navigation: str = 'collapse'

Defines the visibility of the navigation bar

class eezz.table.TTableCell(name, value)

Bases: object

Represents a table cell with properties such as name, value, width, index, type, and additional user-defined attributes. This class is used to store and manage the properties of a single cell within a table structure. It provides default values for width, index, type, and allows the inclusion of custom attributes if necessary.

Variables:

• name (str) – Name of the column.

• value (Any) – Value of the cell.

• width (int) – Calculated width of a cell.

• index (int) – Calculated index of a cell.

• type (str) – Calculated type (could also be user defined).

• attrs (dict) – User attributes.

• details (list) – List of values, which could be used to address objects of the same kind.

detail_class

Possible user implementation to add more detail attributes

alias of TTableCellDetail

class eezz.table.TTableRow(cells)

Bases: object

Represents a table row, capable of handling both simple and complex table structures.

The TTableRow class is designed to facilitate the management and manipulation of table rows, allowing for both straightforward data representation and handling of more complex recursive data structures within a table. This class supports automatic conversion of string lists into cells and provides properties for interacting with row elements by column name or index.

Variables:

• cells (List[TTableCell] | List[str]) – A list of TTableCell objects or strings. Strings are automatically converted into TTableCell objects during initialization.

• cells_filter (List[TTableCell]) – Filtered cells used for re-ordering and alias names, intended for internal use only.

• column_descr (List[str]) – The column descriptor holds the attributes of the columns.

• index (int) – Unique address for the columns, intended for internal use only.

• row_id (str) – Unique row id of the row, valid for the entire table, intended for internal use only.

• child (TTable) – A row could handle recursive data structures, intended for internal use only.

• type (str) – Customizable type used for triggering template output, intended for internal use only.

• attrs (dict) – Customizable row attributes, intended for internal use only.

get_values_list() → list

Retrieves a list of values from the cells.

This method iterates over the cells and extracts their values into a list.

Returns:

A list containing values of the cells.

Return type:

list

property id: str

Computes the SHA1 hash of the row_id attribute encoded in UTF-8.

This property provides a unique string identifier for an object by hashing its row_id attribute. This can be particularly useful for ensuring consistent, non-collision identifiers across distributed systems or unique object tracking.

Returns:

The SHA1 hash of the row_id as a hexadecimal string.

Return type:

str

class eezz.table.TTableColumn(header, attrs)

Bases: object

Represents a column in a table with customizable properties.

This class is designed to encapsulate the properties and behaviors of a table column, offering options to set and modify its header, attributes, index, width, alias, sorting preference, data type, and filtering criteria. It is typically used in table structures where columns may need specific customization for display or processing.

Variables:

• header (str) – Name of the column.

• attrs (doct) – Customizable attributes of the column.

• index (int) – Calculated index of the column.

• width (int) – Calculated width of the column.

• alias (str) – Alias name for output.

• sort (bool) – Sort direction of the column.

• type (str) – Type of the column.

• filter (str) – Filter string.

class eezz.table.TNavigation(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Elements to describe navigation events for method eezz.table.TTable.navigate(). The navigation is organized in chunks of rows given by property TTable.visible_items:

class eezz.table.TSort(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

sorting order for a table column.

module eezz.tabletree

This module implements the following classes:

• eezz.table.TTableTree: Implements a Tree representation, where each node is a TTable with TTableRow entries. Nodes could be expanded and collapsed.

class eezz.tabletree.TTableTree(column_names: list[str], title: str, path: str, visible_items=20)

Bases: TTable

Represents a tree structure built on top of a table. This class extends the functionalities of a basic table to allow hierarchical organization of data, resembling a directory tree. It provides methods to append rows with unique identifiers, handle selection of nodes, read directories, and manage the expansion states of nodes.

Variables:

• root_path (Path) – The root path for the tree structure, initialized from the given path string.

• nodes (List[TTable]) – A list containing the tree’s nodes, initialized with the current instance.

• expanded (bool) – A boolean indicating whether the current node is expanded.

• selected (TTableTree) – The currently selected node within the tree structure.

append(table_row: list, attrs: dict = None, row_type: str = 'body', row_id: str = '', exists_ok=False) → TTableRow

Append a new row to the table with optional attributes and a specific row type.

Parameters:

• table_row (list) – A list representing the contents of the table row.

• row_id (str) – A string representing a file in a directory.

• attrs (dict) – A dictionary of attributes to set for the table row (default is None).

• row_type (str) – A string representing the type of row, e.g., ‘is_file’, ‘is_dir’ (default is ‘body’).

• exists_ok (bool) – If True, supress exception, trying to insert the same row-ID

Returns:

An instance of TTableRow representing the appended row.

on_select(index: str) → TTableRow

Handles the selection of a table row by a given index within a tree.

This method iterates through the nodes and checks if a row is selected by calling the parent class’s on_select method. If a row is found, it returns the selected table row.

Parameters:

index (str) – The index of the table row to select.

Returns:

The selected table row if found.

Return type:

TTableRow

open_dir(path: str) → TTableRow | None

This class provides functionalities to expand or collapse node elements in a tree based on their index. Expansion status is toggled, i.e., if an element is currently collapsed, it will be expanded and vice versa.

If the subtree is expensive to calculate, override this method and omit the clearing of data .

Parameters:

path (str) – Path in the hierarchy to open

Returns:

The TTableRow containing the new TTable as child

abstract read_dir()

Defines an interface for a directory reading system, requiring all subclasses to implement the method for reading directories.

read_file(path: str) → bytes

Reads the contents of a file specified by the given path and returns the data in binary format. If the file does not exist or cannot be read, the function returns an empty binary string.

Parameters:

path – The file system path to the file that needs to be read. It should be a string representing the path to the file.

Returns:

A binary string containing the contents of the file if it exists, otherwise an empty binary string.

module eezz.database

This module handles the database access and implements the following classes

• eezz.database.TDatabaseTable: Create database from scratch. Encapsulate database access.

• eezz.database.TDatabaseColumn: Extends the TTableColumn by parameters, which are relevant only for database access

The TDatabaseTable allows flexible usage of database and buffer access of data by switching seamlessly and hence make standard access very easy and performant. The database is created in sqlite3 in the first call of the class.

class eezz.database.TDatabaseTable(column_names, title)

Bases: TTable

Represents a database table, extending capabilities of a general table to include database interactions.

The TDatabaseTable class is designed to manage a table within a database context. It handles the creation of database statements, synchronization with a database table, and data navigation and manipulation operations such as inserting records and committing changes. It uses the database path, name, and column descriptors to construct necessary SQL statements for operations. Initialization involves setting up the data structure and checking for primary keys.

Variables:

• column_names (list) – List of column names for the database table.

• database_name (str) – The name of the database file to connect or create.

• database_path (str) – File path for the database.

• virtual_len (int) – Virtual length of the dataset.

append(table_row: list, attrs: dict = None, row_type: str = 'body', row_id: str = '', exists_ok: bool = True) → TTableRow

Appends a new row to the table with specified attributes and parameters. The function checks for a row_id and generates one if not provided, based on primary keys.

Attributes are defaulted to include a ‘_database’ key with value ‘new’. This is used to manage values to be commited to the database with commit.

The method accepts parameters to specify the type of the row, presence check, and any additional attributes.

Parameters:

• table_row (list) – List of values representing the table row to append.

• attrs (dict) – Optional dictionary of additional attributes. Defaults to None.

• row_type (str) – Type of the row, default is ‘body’.

• row_id (str) – Identifier for the row. If not provided, it is generated automatically.

• exists_ok (bool) – Indicates if appending should proceed without error if row exists. Defaults to True.

Returns:

A reference to the appended table row.

Return type:

TTableRow

commit()

Commits new rows in the data to the database. This method iterates through entries marked as ‘new’ in their ‘_database’ attribute, removes this marker, and then inserts the entries into the database using the provided insert statement and column names.

Raises:

sqlite3.Error – If there is an error executing the database operations.

create_database() → None

Creates a new SQLite database using the specified database path. This method registers adapters and converters for the datetime type to facilitate proper storage and retrieval of datetime objects within the database.

The method connects to the SQLite database using the provided path, executes the SQL statement designed to create the necessary database tables, and then closes the connection ensuring the changes are committed.

Raises:

sqlite3.Error – If an error occurs while connecting to the database or executing the SQL statement.

get_visible_rows(get_all=False) → list

Retrieves a list of visible rows from the data source. By default, it synchronizes the data if not already synchronized, clears any existing data in the process, and appends new data based on the current row filter description. The method subsequently yields visible rows as determined by the superclass implementation.

Parameters:

get_all – A boolean to determine if all rows should be retrieved.

Returns:

A list of visible rows.

navigate(where_togo: int = 1, position: int = 0) → None

Navigate to a specified position within a data structure. This method allows navigation through different points based on the parameters provided. If the position is set to 0, synchronization is disabled by setting is_synchron to False. This allows to select data and restrict the number of data records transferred to the application. It allows the user to navigate in the selected data set if needed

Parameters:

• where_togo (TNavigation) – The direction or target to which the navigation should occur. Defaults to TNavigation.NEXT`.

• position (int) – The index or position to navigate to. If the value is 0, internal synchronization will be set to False. Defaults to 0.

Returns:

None

prepare_statements()

Prepare SQL statements for a database table based on provided column descriptions.

This method constructs SQL statements for creating, selecting, counting, and inserting data into a database table. The statements are built using the table title and column descriptions provided to the instance. The resulting SQL statements include a ‘CREATE TABLE’ statement with primary key constraint, a ‘SELECT’ statement to retrieve all data, a ‘COUNT’ statement to tally the rows, and an ‘INSERT OR REPLACE’ statement for adding or updating records.

class eezz.database.TDatabaseColumn(primary_key, options, alias)

Bases: TTableColumn

Represents a database column as a subclass of a table column.

This class provides additional features specific to database columns, including the ability to specify whether a column is a primary key, options related to its behavior or properties, and an alias for referencing the column under a different name. It is designed to be extended for specific use cases in managing and interacting with database tables.

Variables:

• primary_key (bool) – Boolean flag indicating if the column is a primary key.

• options (str) – Additional options or settings for the column.

• alias (str) – Alternative name for referring to the column.

module eezz.document

This module implements the following classes

• eezz.document.TManifest: The Manifest contains the attributes and the content of a document. This includes for example author, creation date and embedded external files.

• eezz.document.TDocument: A document consists of one or more embedded files and the Manifest. The class implements methods for file download and creating a TAR archive.

A document has always a reference to a shelf, which contains documents with the same Manifest layout

class eezz.document.TDocument(path, name)

Bases: object

Manages documents A document is a zipped TAR file, w ith a Metafile and a collection of data files.

Variables:

• path (Path) – Documents bookshelf path

• attributes (List[str]) – List of attributes like author and title

• shelf_name (str) – A document has always a reference to a bookshelf

• manifest (TManifest) – Document header definition

• files_list (List[TFile]) – List of embedded files

attributes: List[str]

List of document attributes like author and title

create_archive(document_title: str) → None

ZIP the given files and the manifest to a document. The TFile class keeps track on the location of the file content and their properties.

Parameters:

document_title (str) – The name of the archive

abstract create_document()

Abstract method which is called after all files are in place

download_file(file: dict, stream: bytes = b'') → bytes

Download file callback. The method is called for each chunk and for a final acknowledge. If all files are transferred, the document is created. For each final acknowledge a 100% is returned.

Parameters:

• file (dict) – File descriptor with details on file and byte stream

• stream (bytearray) – File stream, usually a chunk of

Returns:

The percentage of transferred document size as bytearray, terminated with the percent sign

Return type:

bytearray

extract_file(document_title: str, file_pattern: str = None, dest_root: Path = '.') → None

Restores the specified files, given by the regular expression in file_pattern

Parameters:

• document_title (str) – The document title is the name of the archive

• dest_root (Path) – The path within the archive for all entries

• file_pattern (str) – The files to extract

files_transferred: int = 0

initialize_document(values: list) → None

Initializes the document, providing values for the Manifest header

Parameters:

values (List[str]) – List of values according to the definition of columns

read_file(document_title: str, file_name: str) → bytes

Returns the bytestream of the specified file in the archive

Parameters:

• document_title (str) – The title of the document is the name of the archive

• file_name (str) – The file content to return

module eezz.filesrv

This module implements the following classes:

• eezz.filesrv.TFile: Takes a chunk of data and merges it to a file

• eezz.filesrv.TEezzFile: Extends TFile and implements encryption and decryption for transmitted data

• eezz.filesrv.TFileMode: Enum file-mode for TEezzFiles

• eezz.filesrv.TFileEncryptionError: Detect an error during reading an encrypted file

This module supports a download of big files in chunks and ensures, that the incoming fragments are put together in the correct order again. Furthermore, a hash is calculated for each chunk, so that the data consistency of a file could be ensured during reading.

class eezz.filesrv.TEezzFile(*, file_type: str, destination: Path, size: int, chunk_size: int, transferred: int = 0, key: bytes, vector: bytes, hash_chain: dict = None)

Bases: TFile

Derived from TFile, this class allows encryption and decryption using AES key. Each chunk generates a hash, which could be collected and saved to validate the encrypted data stream.

Parameters:

• key (Crypto.Random.new(16)) – AES key for cypher

• vector (Crypto.Random.new(16)) – AES vector for cypher

• hash_chain (List[SHA256.hexdigest]) – A list of hash values for each chunk

decrypt(raw_data: Any, sequence_nr: int) → str

Decrypt the incoming stream

Parameters:

• raw_data (Any) – Data chunk of the steam

• sequence_nr (int) – Sequence number in the stream

Returns:

Hash value of the chunk

Return type:

SHA256.hexdigest

encrypt(raw_data: Any, sequence_nr: int) → str

Encrypt the incoming data stream

Parameters:

• raw_data (Any) – Data chunk of the stream

• sequence_nr (int) – Sequence number in the stream

Returns:

Hash value of the chunk

Return type:

SHA256.hexdigest

read(source: BufferedReader, hash_list: List[str] = None) → None

Read an encrypted file from source input stream and create an decrypted version

Parameters:

• source (BufferedReader) – Input stream

• hash_list (List[SHA256.hexdigest]) – A hash list to check the stream

Raises:

TFileEncryptionError –

write(raw_data: Any, sequence_nr: int, mode: TFileMode = TFileMode.ENCRYPT) → str

Write a chunk of data

Parameters:

• raw_data – The data chunk to write

• sequence_nr – Sequence of the data chunk in the stream

• mode – The mode used to en- or decrypt the data or pass through

Returns:

The hash value of the data after encryption/before decryption

Return type:

SHA256.hexdigest

class eezz.filesrv.TFile(*, file_type: str, destination: Path, size: int, chunk_size: int, transferred: int = 0)

Bases: object

TFile supports chunked file transfer.

Parameters:

• file_type – User defined file type

• destination – Path to store the file

• size – The size of the file

• chunk_size – Fixed size for each chunk of data, except the last element

property name: str

Returns the file name including extension

write(raw_data: Any, sequence_nr: int, mode: TFileMode = TFileMode.NORMAL) → str

Write constant chunks of raw data to file. Only the last chunk might be smaller. The sequence number is passed along, because we cannot guarantee, that elements received in the same order as they are send.

Parameters:

• raw_data (Any) – Raw chunk of data

• sequence_nr (int) – Sequence number to insert chunks at the right place

• mode (TFileMode) – Set signature for derived classes

Returns:

Signature for derived classes

exception eezz.filesrv.TFileEncryptionError(message)

Bases: Exception

Exception handling for encrypted files

enum eezz.filesrv.TFileMode(value)

Bases: Enum

File mode: Determine how to handle incoming stream

Parameters:

• NORMAL – Write through

• ENCRYPT – Encrypt and write

• ENCRYPT – Decrypt and write

Valid values are as follows:

NORMAL = <TFileMode.NORMAL: 0>

ENCRYPT = <TFileMode.ENCRYPT: 1>

DECRYPT = <TFileMode.DECRYPT: 2>

eezz.filesrv.test_file_reader()

Test the TFile interfaces :meta private:

module eezz.http_agent

his module implements the following classes

• eezz.http_agent.THttpAgent: The handler for incoming WEB-socket requests

The interaction with the JavaScript via WEB-Socket includes generation of HTML parts for user interface updates. It inherits from abstract eezz.websocket.TWebSocketAgent and implements the method “handle_request” The class provides methods to compile EEZZ extensions and to generate complex DOM structures.

class eezz.http_agent.THttpAgent

Bases: TWebSocketAgent

Agent handles WEB socket events

static compile_data(a_parser: Lark, a_tag_list: list, a_id: str, a_query: dict = None) → None

Compile data-eezz-json to data-eezz-compile, create tag attributes and generate tag-id to manage incoming requests

Parameters:

• a_parser (Lark) – The Lark parser to compile EEZZ to json

• a_tag_list (list) – HTML-Tag to compile

• a_id (str) – The ID of the tag to be identified for update

• a_query (dict) – The query of the HTML request

do_get(a_resource: Path | str, a_query: dict) → str

Response to an HTML GET command

The agent reads the source, compiles the data-eezz sections and adds the web-socket component It returns the enriched document

Parameters:

• a_resource (pathlib.Path) – The path to the HTML document, containing EEZZ extensions

• a_query (dict) – The query string of the URL

Returns:

The compiled version of the HTML file

static format_attributes(a_key: str, a_value: str, a_fmt_funct: Callable, a_id: str = None) → str

Eval template tag-attributes, diving deep into data-eezz-json

Parameters:

• a_id (str) – The ID which replaces the placeholder ‘this’

• a_key (str) – Thw key string to pick the items in an HTML tag

• a_value (str) – The dictionary in string format to be formatted

• a_fmt_funct (Callable) – The function to be called to format the values

Returns:

The formatted string

static format_attributes_update(json_str: str, formatter: Callable) → str

Special routine to format function arguments in the update section

Parameters:

• formatter (Callable) – Format function for values in curly brackets

• json_str (str) – An eezz generated json string

Returns:

formatted function arguments

generate_html_cells(a_tag: Tag, a_cell: TTableCell) → Tag

Generate HTML cells

Parameters:

• a_tag (bs4.Tag) – The template tag to generate a table cell

• a_cell (TTableCell) – The cell providing the data for the HTML tag element

Returns:

A new tag, based on the template and the cell data

Return type:

bs4.Tag

generate_html_grid(a_tag: Tag) → dict

Besides the table, supported display is grid via class clzz_grid or select

Parameters:

a_tag (bs4.Tag) – The HTML tag, which is assigned to a TTable object

Returns:

The DOM of the generated grid as dictionary with key “tbody”

Return type:

dict

generate_html_grid_item(tag_template: Tag, a_row: TTableRow, a_table: TTable) → Tag

Generates elements of the same kind, derived from a template and update content according the row values

Parameters:

• tag_template (bs4.Tag) – Template for the entire tile

• a_row (TTableRow) – Row with data for the specific tile

• a_table (TTable) – Parent table

Returns:

Generated HTML tag

generate_html_rows(a_html_cells: list, a_tag: Tag, a_row: TTableRow) → Tag

This operation add fixed cells to the table. Cells which are not included as template for table data are used to add a constant info to the row

Parameters:

• a_html_cells (list) – A list of cells to build up a row

• a_tag (bs4.Tag) – The parent containing the templates for the row

• a_row (TTableRow) – The table row values to insert

Returns:

The row with values rendered to HTML

generate_html_table(a_table_tag: Tag, a_id: str) → dict

Generates a table structure in four steps

1. Get the column order and the viewport

2. Get the row templates

3. Evaluate the table cells

4. Send the result separated by table main elements

Parameters:

• a_table_tag (bs4.Tag) – The parent table tag to produce the output

• a_id (str) – Unique table ID

Returns:

The generated table separated in sections as dictionary

Return type:

dict

generate_table_footer(a_table_tag: Tag, a_table: TTable, a_id: str) → Tag | None

Generate the table footer. Methods in this section have to be redirected to the correct table.

Parameters:

• a_table_tag (bs4.Tag) – The HTML table template

• a_table (TTable) – The TTable object, parent for the footer to create

• a_id (str) – The new ID for method calls and references

Returns:

The footer inner HTML

Return type:

bs4 footer TAG or None

handle_request(request_data: dict) → dict | None

Handle WEB socket requests

• initialize: The browser sends the complete HTML for analysis.

• call: The request issues a method call and the result is sent back to the browser

Parameters:

request_data (dict) – The request send by the browser

Returns:

Response in JSON stream, containing valid HTML parts for the browser

module eezz.server

This module implements the following classes

• eezz.server.TWebServer : Implementation of http.server.HTTPServer, prepares the WEB-Socket interface.

• eezz.server.THttpHandle: Implementation of http.server.SimpleHTTPRequestHandler, allows special access on local services.

class eezz.server.THttpHandler(request, client_address, server)

Bases: SimpleHTTPRequestHandler

HTTP handler for incoming requests

do_GET()

handle GET request

do_POST()

handle POST request

handle_request()

handle GET and POST requests

shutdown(args: int = 0)

Shutdown handler

class eezz.server.TWebServer(a_server_address, a_http_handler, a_web_socket)

Bases: HTTPServer

WEB Server encapsulate the WEB socket implementation

Parameters:

• a_server_address (Tuple[str,socket]) – The WEB address of this server

• a_http_handler – The HTTP handler

• a_web_socket – The socket address waiting for WEB-Socket interface

shutdown()

Shutdown the WEB server

eezz.server.shutdown_function(handler: THttpHandler)

module eezz.service

This module implements the following classes:

• TService: A singleton for TGlobalService

• TServiceCompiler: A Lark compiler for HTML EEZZ extensions

• TTranslate: Extract translation info from HTML to create a POT file

• TQuery: Class representing the query of an HTML request

class eezz.service.TService

Bases: object

Container for unique environment as

• path descriptors

• stores assignments of the parser

• stores RSA application key

assign_object(obj_id: str, description: str, attrs: dict, a_tag: Tag = None, force_reload: bool = False) → None

assign_object Assigns an object to an HTML tag

Parameters:

• obj_id (str) – Unique object-id

• description (str) – Path to the class: <directory>.<module>.<class>

• attrs (dict) – Attributes for the constructor

• a_tag (bs4.Tag) – Parent tag which handles an instance of this object

• force_reload (bool) – Force reloading

Raises:

• AttributeError – Class not found

• IndexError – description systax does not match

get_method(obj_id: str, a_method_name: str) → tuple

Get a method by name for a given object

Parameters:

• obj_id (str) – Unique hash-ID for object as stored in eezz.service.TService.assign_object()

• a_method_name (str) – Name of the method

Returns:

tuple(object, method, parent-tag)

Raises:

AttributeError – Class has no method with the given name

get_object(obj_id: str) → Any

Get the object for a given ID

Parameters:

obj_id (str) – Unique hash-ID for object as stored in eezz.service.TGlobalService.assign_object()

Returns:

The assigned object

get_tag_ref(obj_id: str) → Any

Get Tag and descriptor for a given object ID

Parameters:

obj_id (str) – Object ID

Returns:

Tag and descriptor

Return type:

dict

class eezz.service.TServiceCompiler(a_tag: Tag, a_id: str = '', a_query: dict = None)

Bases: Transformer

Transforms the parser tree into a list of dictionaries The transformer output is in json format

Parameters:

• a_tag (bs4.Tag) – The parent tag

• a_id (str) – A unique object id

• a_query (dict) – The URL query part

class eezz.service.TTranslate

Bases: object

The class TTranslate executes the EEZZ grammar and translates the input to a JSON object

module eezz.websocket

This module implements the following classes

• eezz.websocket.TWebSocketAgent: The abstract class has to be implemented by the user to drive the TWebSocketClient

• eezz.websocket.TWebSocketException: The exception for errors on low level interface

• eezz.websocket.TWebSocketClient: This class interacts with the TWebSocketAgent and HTML frontend

• eezz.websocket.TWebSocket: Low level access to the socket interface

• eezz.websocket.TAsyncHandler: This class is used to interact with user defined methods

• eezz.websocket.TLogger: A TTable object, which collects logger output for the browser

The TWebSocket implements the protocol according to rfc 6455

class eezz.websocket.TLogger

Bases: TTable

Log Table for requests to display in browser

add_message(msg)

Compile a message to a table row dict_keys([‘elapsed’, ‘exception’, ‘extra’, ‘file’, ‘function’, ‘level’, ‘line’, ‘message’, ‘module’, ‘name’, ‘process’, ‘thread’, ‘time’])

class eezz.websocket.TWebSocketAgent

Bases: object

User has to implement this class to receive data. TWebSocketClient is called with the class type, leaving the TWebSocketClient to generate an instance

abstract handle_request(request_data: Any) → dict

handle request expects a json structure

shutdown()

Implement shutdown to release allocated resources

class eezz.websocket.TWebSocketClient(a_client_addr: tuple, a_agent: type[TWebSocketAgent])

Bases: object

The TWebSocketClient class handles the WebSocket client connection, transitioning a standard HTTP connection to a WebSocket, maintaining socket communication, and managing interaction with a specified WebSocket agent.

This class is responsible for upgrading HTTP connections to WebSocket connections, handling requests sent over WebSocket, and managing asynchronous and synchronous processing of those requests. It interacts with a WebSocket agent class to delegate specific tasks, handle incoming data frames, generate handshake responses, and maintain the overall stability of the WebSocket communication channel.

Variables:

• m_headers (dict) – Stores HTTP headers relevant for WebSocket handshake.

• m_socket (Any) – The socket object related to the client connection.

• m_cnt (int) – A counter used internally (specific usage/context not documented).

• m_buffer (bytearray) – A buffer space used for storing data received over the WebSocket.

• m_protocol (str) – The protocol name used during WebSocket handshake.

• m_agent_class (type[TWebSocketAgent]) – The class type of the WebSocket agent associated with this client.

• m_agent_client (TWebSocketAgent) – An instance of the WebSocket agent class, facilitating task delegation.

• m_lock (Lock) – A threading lock used to ensure thread safety during operations.

• m_threads (Dict[Callable, Thread]) – A dictionary mapping asynchronous callables to their respective threads.

gen_handshake(a_data: str)

Generates a WebSocket handshake response based on the input request data. The function parses the request headers, determines the appropriate WebSocket protocol version and constructs the response necessary for the protocol switch. This is essential for establishing a connection that adheres to WebSocket protocol specifications.

Parameters:

a_data (str) – The raw HTTP request string containing headers that are used to construct the WebSocket handshake response.

Returns:

A string representing the HTTP response for switching protocols, formatted for a WebSocket handshake.

Return type:

str

gen_key() → str

Generates a WebSocket accept key by concatenating the client’s key with a GUID and hashing the result using SHA-1, followed by base64 encoding. This process is described in RFC 6455, Section 4.2.2, which is part of the WebSocket protocol specification. The key serves as a mechanism to ensure that the connection request is valid and not coming from a source that doesn’t understand WebSockets, thereby providing a level of handshake security.

Returns:

The WebSocket accept key, encoded in base64 format

Return type:

str

handle_async_request(request: dict) → dict

Handles an asynchronous request by utilizing a client to process the request and subsequently sending the response. This function is intended to ensure thread safety when accessing shared resources.

Parameters:

request (dict) – A dictionary containing the details of the request to be processed. It typically includes all necessary information required by the client for processing.

Returns:

A string response generated by the client after handling the request. The response is also sent in an encoded format.

handle_request() → None

Handles incoming WebSocket requests by interpreting their JSON content and executing the appropriate method based on the included command. The method supports commands for ‘download’, ‘file’, ‘initialize’, and ‘call’. The command determines which backend process or asynchronous task should be triggered.

Returns:

None

read_frame(x_opcode, a_mask_vector, a_payload_len)

Reads a frame from a socket and processes it based on the given opcode, mask vector, and payload length. If the payload length is zero, it returns immediately with an empty bytearray. Otherwise, it reads the payload from the socket into an internal buffer.

If a mask vector is provided, it applies the mask to the payload using byte-wise XOR operations. The method supports both masked and unmasked frames typical of web socket communication.

Parameters:

• x_opcode (int) – OpCode of the frame to be read, determining the type of frame.

• a_mask_vector (bytes) – Mask vector for unmasking the frame’s payload, if present.

• a_payload_len (int) – Length of the payload that needs to be read from the socket.

Returns:

A bytearray containing the unmasked payload of the read frame.

Return type:

bytearray

read_frame_header()

Reads the header of a WebSocket frame from the socket, processing information related to control and payload data. This function extracts the fin bit, opcode, mask vector, and payload length from the frame’s header, which are crucial for determining the frame’s structure and for handling WebSocket connections in a compliant manner.

Returns:

A tuple containing the following elements: - x_final (bool): Indicates if the frame is the final fragment. - x_opcode (int): Specifies the opcode defining the frame’s content type. - x_mask_vector (bytes or None): The mask key if the payload is masked. - x_payload_len (int): Length of the payload data.

Return type:

tuple

Raises:

TWebSocketException – If no data is received from the socket.

read_websocket() → Tuple[bytes, bytes]

Reads data from a websocket, processing various websocket frame opcodes such as text, binary, ping, and pong, until a final frame is encountered. Handles exceptions during the reading process, logging them and shutting down the client connection if necessary.

Returns:

The raw bytes data read from the websocket until a final frame is encountered.

Raises:

• TWebSocketException – If a close frame is received or an unknown opcode is encountered.

• Exception – For any other unexpected exceptions during the reading process.

upgrade()

Establishes a web socket connection by performing a handshake with the server. This method handles receiving initial binary data, decoding it to UTF-8, generating a handshake response, and sending this response back to establish a connection. It also initializes a buffer used for further communications.

Raises:

TWebSocketException – if no data is received during the handshake process

write_frame(a_data: bytes, a_opcode: hex = 1, a_final: hex = 128, a_mask_vector: list | None = None) → None

Constructs and sends a WebSocket frame using the specified parameters. The function handles masking the payload if a mask vector is provided, maintains the frame structure as per the WebSocket protocol, and sends the frame through the established socket connection.

Parameters:

• a_data (bytes) – The payload data to be sent in the WebSocket frame.

• a_opcode (hex) – The opcode for the frame, indicating the type of data being sent (e.g., text, binary).

• a_final (hex) – A flag indicating if this is the final fragment in a message. Defaults to 1 << 7.

• a_mask_vector (list) – A list of four byte mask keys used for masking the payload data. If None, no masking is applied. Must be exactly 4 bytes if provided.

class eezz.websocket.TWebSocket(a_web_address: tuple, a_agent_class: type[TWebSocketAgent])

Bases: Thread

TWebSocket is a thread-based server for handling WebSocket connections.

This class provides the implementation for a WebSocket server that listens for incoming WebSocket requests on a specified address and port. It uses a separate client handler class to manage the communication with each connected client and supports gracefully shutting down all sockets when required. The server runs as a daemon thread, allowing it to operate independently of the main application flow.

Variables:

• m_web_socket (socket.socket) – The main server socket for accepting client connections.

• m_web_addr (tuple) – The tuple containing the IP address and port where the server listens.

• m_clients (dict) – A dictionary mapping client sockets to their handler instances.

• m_agent_class (type[TWebSocketAgent]) – The class type used for creating client agent instances.

• m_running (bool) – A boolean flag indicating if the server is currently active and accepting connections.

run()

Establishes a WebSocket server that listens for incoming connections and handles client requests. The server operates in a loop where it waits for socket events, manages client connections, and processes incoming WebSocket messages. It handles errors by shutting down faulty connections and cleaning up resources appropriately.

Raises:

Exception if the server socket encounters an error

shutdown()

Shutdown closes all sockets

class eezz.websocket.TAsyncHandler(socket_server: TWebSocketClient | None, request: dict, do_loop: bool = False)

Bases: Thread

The AsyncHandler is able to execute request method in background task. This class is designed to be put a method into an async thread to execute a user method, without blocking the websocket. After the method returns, the AsyncHandler creates the websocket response. It’s also possible to specify do_loop to allow successive calls to the same method. This way you could implement a monitor measurement, sending actual data in some time intervals to the user interface.

Parameters:

• socket_server (TWebSocketClient) – The server to send the result. None for test and validation only

• request (dict) – The request, containing the method to call. The request takes the result of the method call and returns it to the rendering machine to return it to the browser.

• do_loop (bool) – If True the thread does not return, but allows the method to trigger any number of update events for the browser.

handle_update() → dict

Executes the request in either asynchronous or synchronous mode based on the request parameters. Continuously handles asynchronous requests while the ‘running’ attribute is True. In synchronous mode, processes the request once and returns the result.

Returns:

Dict with target and values for update