Interface
- class korus.database.interface.interface.FieldAlias(field_name: str, name: str, type: type, description: str, transform: callable = <function FieldAlias.<lambda>>, reverse_transform: callable = <function FieldAlias.<lambda>>)[source]
Bases:
objectDefinition of a field alias in a Korus table interface.
- Attrs:
- field_name: str
The field’s name
- name: str
The alias name
- type: Any
The alias type
- description: str
Short, human-readable description of the alias
- transform: callable (optional)
Transform applied to every alias value to convert it to a field value
- reverse_transform: callable (optional)
Transform applied to every field value to convert it to an alias value
- reverse_transform(**_)
- transform(**_)
- class korus.database.interface.interface.FieldDefinition(name: str, type: type, description: str, required: bool = True, default: Any = None, options: list = None, is_path: bool = False)[source]
Bases:
objectDefinition of a field in a Korus table interface.
Fields must have one of the following Python types:
bool,str,int,float,datetime
Table indices are stored in fields with type int and name ending in _id.
- Attrs:
- name: str
The name of the field
- type: type
The field Python type.
- description: str
Short, human-readable description of the data stored in this field
- required: bool
True if the field is required to have a non-null value. False otherwise
- default: same as type (optional)
The field default value
- options: list (optional)
Allowed values
- is_path: bool
Whether the field is an OS path.
- Properties:
- is_index: bool
Whether the field is a table index
- class korus.database.interface.interface.TableInterface(name: str, backend: TableBackend)[source]
Bases:
objectBase class for all Korus table interfaces.
Table interfaces define how users interact with the database, e.g., adding data to the database or retrieving data from it.
- Args:
- name: str
The table interface name
- backend: korus.database.backend.TableBackend
The table backend, connecting the interface to the underlying database
- add(row: dict) int[source]
Add an entry to the table
- Args:
- row: dict
Input data in the form of a dict, where the keys are the field names and the values are the values to be added to the database.
- Returns:
- : int
Index assigned to the added entry.
- add_field(name: str, type: Any, description: str, required: bool = True, default: Any = None, options: list = None, is_path: bool = False)[source]
Add a custom field to the table interface.
The field is saved to the database. This allows it to be automatically re-created at every subsequent connection to the database.
- Args:
- name: str
The field’s name
- type: Any
The field’s type
- description: str
Short, human-readable description of the data stored in this field
- required: bool
True if the field is required to have a non-null value. False otherwise
- default: same as type (optional)
The field default value
- options: list (optional)
Allowed values
- is_path: bool
Whether the field is an OS path.
- property aliases: list[korus.database.interface.interface.FieldAlias]
The field aliases
- property aliases_asdict: dict[str, korus.database.interface.interface.FieldAlias]
The field aliases as a dict
- create_alias(field_name: str, name: str, type: Any, description: str, transform: callable = None, reverse_transform: callable = None)[source]
Create a custom alias.
OBS: Note that the alias is not saved to the database, so the alias needs to be re-created every time the table interface is instantiated.
- Args:
- field_name: str
The field’s name
- name: str
The alias name
- type: Any
The alias type
- transform: callable (optional)
Transform applied to every row of input data to convert the alias value to its corresponding field value. Expects the alias value as the first positional argument, and accepts other field/alias values as keyword arguments. Note: The transform is also applied to the condition argument of the filter method.
- reverse_transform: callable (optional)
Transform applied to every row of output data to convert the field value to its corresponding alias value. Expects the field value as the first positional argument, and accepts other field/alias values as keyword arguments.
- property fields: list[korus.database.interface.interface.FieldDefinition]
The definitions of the table’s fields
- property fields_asdict: dict[str, korus.database.interface.interface.FieldDefinition]
The definitions of the table’s fields as a dict
- filter(*conditions, **kwargs)[source]
Search the table.
If the backend’s filtering method accepts additional keyword arguments, these can be passed as keyword arguments to this method.
- Args:
- conditions: sequence of dict
Search criteria, where the keys are the field names and the values are the search values. Use tuples to search on a range of values and lists to search on multiple values. Append ~ to the field name to invert the search criteria, i.e., to exclude values or a range of values. Multiple dicts are joined by a logical OR. Within each dict, search criteria are joined by a logical AND.
- Returns:
- self: TableInterface
A reference to this instance
- get(indices: int | list[int] | None = None, fields: str | list[str] | None = None, return_indices: bool = False, always_tuple: bool = True, as_pandas: bool = False) list[tuple][source]
Retrieve data from the table.
Note that the method always returns a list, even when only a single index is specified.
- Args:
- indices: int | list[int]
The indices of the entries to be returned. If None, all entries in the table are returned.
- fields: str | list[str]
The fields to be returned. If None, all fields are returned. Can also be aliases.
- return_indices: bool
Whether to also return the indices. If True, indices are inserted at the beginning of each row tuple.
- always_tuple: bool
If False, and there is only 1 field, return a list of values instead of tuples.
- as_pandas: bool
Return data in the form of a Pandas DataFrame.
- Returns:
- data: list[tuple]
The data
- get_next(fields: str | list[str] | None = None, return_indices: bool = False, always_tuple: bool = True, as_pandas: bool = False) tuple[source]
Get the next row from the table
- info() str[source]
Nicely formatted summary of the table definition.
- Returns:
- res: str
Table definition
- remove(indices: int | list[int] | None = None)[source]
Remove entries from the table.
- Args:
- indices: int | list[int]
The indices of the entries to be removed. If None, all entries will be removed.
- unique(field: str) list[source]
Get the unique values of a given field.
- Args:
- field: str
The field name
- Returns:
- values: list
The non-null, unique values
- update(idx: int, row: dict, insert: bool = False)[source]
Modify an existing entry in the table
- Args:
- idx: int
Row index
- row: dict
New data to replace the existing data
- insert: bool
If True, and the index does not exist in the table, create a new row with this index
- values_asdict(values: tuple, fields: str | list[str] | None = None, index: bool = False) dict[source]
Convert a tuple of field values to a dict, with field names as keys.
- Args:
- values: tuple
The values
- fields: str | list[str]
The field names. If None, the value tuple is assumed to contain values for every field, in the correct ordering.
- index: bool
Whether the index has been inserted at the beginning of the value tuple. If True, the index value is added to the dict with the key id.
- Returns:
- : dict
The values in a dictionary with field names as keys.
- class korus.database.interface.interface.TableViewer(table: TableInterface, fields: str | list[str] | None = None, nrows: int = 20, max_char: int = 60, transforms: dict | None = None)[source]
Bases:
objectClass for viewing table contents
- Args:
- table: TableInterface
The table interface
- fields: str | list[str]
Which fields to include
- nrows: int
Number of rows printed per page
- max_char: int
Column width no. characters
- transforms: dict[str, callable]
Custom transformations applied to individual fields