Skip to content

Basic Infrastructure

This page documents the REvoDesign.basic module, which provides reusable infrastructure classes including plugin registries, data structures, file-extension utilities, menu items, parameter change registrations, third-party module abstractions, and mutation runners.

Plugin Registry

The plugin registry system enables package-scoped, subclass-based plugin discovery. PluginRegistry is a frozen dataclass that discovers all non-abstract subclasses of a given base class within a Python package at initialization time. build_plugin_registry is a convenience factory function.

REvoDesign.basic.plugin_registry.PluginRegistry dataclass

Bases: Generic[PluginT]

Package-scoped plugin registry.

Discovery is performed during initialization by importing all modules under package and collecting subclasses of base_class.

REvoDesign.basic.plugin_registry.build_plugin_registry(base_class, package, installed_attr='installed', include_package_module=True, include_predicate=None)

Data Structures

IterableLoop is a generic class that manages an iterable with circular navigation (next/previous wrapping), tracking the current index.

REvoDesign.basic.data_structure.IterableLoop dataclass

Bases: Generic[T]

A class for managing an iterable with looping behavior.

current_item property

Returns the current item in the iterable.

pick_next()

Moves to the next item in the iterable, wrapping around to the beginning if necessary.

pick_previous()

Moves to the previous item in the iterable, wrapping around to the end if necessary.

walker(direction)

Moves to the next or previous item in the iterable based on the given direction.

Parameters:

Name Type Description Default
direction bool

A boolean value indicating the direction of movement. True for next, False for previous.

 required

reset()

Resets the current index to -1, indicating an uninitialized state.

File Extensions

FileExtension represents a single file extension with a human-readable description; FileExtensionCollection manages a collection of extensions with support for merging, matching, and generating Qt file-filter strings.

REvoDesign.basic.extensions.FileExtension dataclass

Represents a file extension, including its technical details and human-readable description.

Attributes:

Name Type Description
ext str

The file extension, such as 'txt', 'md', etc.
description str

A brief description of the file type, such as 'Text File' or 'Markdown File'.

filter_string property

Generates a file filter string for this file extension.

Returns:

Name Type Description
str str

A file filter string in the format 'Description (*.[ext])', used in file dialog filters.

REvoDesign.basic.extensions.FileExtensionCollection dataclass

Represents a collection of file extensions, used to manage multiple file types.

Attributes:

Name Type Description
extensions tuple[FileExtension, ...]

A tuple containing a series of FileExtension objects.

list_all property

Returns a list of all file extensions.

This property method iterates over the self.extensions list, extracting the 'ext' attribute from each extension object.

list_dot_ext property

Returns a list of string extensions prefixed with a dot.

Returns:

Type Description
list[str]

list[str]: A list of string extensions, each prefixed with a dot.

filter_string property

Generates a combined file filter string for all file extensions in the collection.

Returns:

Name Type Description
str str

A combined file filter string, with each file extension's filter string separated by ';;'.

match(ext)

Check if the given file extension matches any of the extensions in the current object's list.

Parameters: ext (Union[FileExtension, str]): The file extension to check, can be a FileExtension enum or a string.

Returns: bool: True if the extension matches, False otherwise.

squeeze(exts) classmethod

Merge file extensions from multiple FileExtensionCollection instances and remove duplicates.

This method takes a tuple of FileExtensionCollection instances and combines their extensions using set union operations to ensure that the resulting collection contains only unique extensions.

exts (tuple[FileExtensionCollection]): A tuple containing multiple FileExtensionCollection instances whose extensions are to be merged.

FileExtensionCollection: A new FileExtensionCollection instance containing all unique extensions from the input instances.

basename_stem(fname)

Extracts the stem (base name without extension) from a file name.

Parameters: fname (str): The file name to extract the stem from.

Returns: str: The base name (stem) of the file name without the extension.

Group Registry

GroupRegistryItem registers a configuration item with a set of callable group generators, enabling dynamic population of UI widget values from config.

REvoDesign.basic.group_registries.GroupRegistryItem dataclass

A data class representing an item in a group registry.

Attributes:

Name Type Description
cfg_item str

The configuration item associated with this registry entry.
group_generators tuple[Callable[[], Union[List[str], Dict[str, Any]]], ...]

A tuple of callables that generate groups. Each callable returns either a list of strings or a dictionary.

Parameter Change Registration

ParamChangeRegistryItem maps a signal on one UI widget to a config change on another via a parameter mapping dictionary. ParamChangeRegister registers a collection of such items.

REvoDesign.basic.param_toggle.ParamChangeRegistryItem dataclass

A class that registers a mapping between two config items.

This class is used to define how a change in one configuration item (source_cfg_item) should be mapped and registered to another configuration item (target_cfg_item) through a UI widget signal. It uses a dictionary to map parameter values.

Attributes:

Name Type Description
widget_name str

The name of the UI widget.
widget_signal_name str

The name of the signal on the widget.
source_cfg_item str

The name of the source configuration item.
target_cfg_item str

The name of the target configuration item.
param_mapping Dict[Any, Tuple]

A dictionary mapping parameter values from the source to the target.

widget_signal(ui)

Retrieves the specified signal from the specified widget on the UI.

Parameters:

Name Type Description Default
ui Any

The UI instance containing the widgets.

 required

Returns:

Name Type Description
QtEventSignal pyqtBoundSignal

The signal associated with the widget.

Raises:

Type Description
InternalError

If the widget does not have the specified signal.

register(register_func, ui)

Registers the mapping between two configuration items by connecting the widget signal to the registration function.

Parameters:

Name Type Description Default
register_func Callable[[str, str, Dict[str, Tuple]], None]

The function to be called when the signal is emitted.

 required
ui Any

The UI instance containing the widgets.

 required

REvoDesign.basic.param_toggle.ParamChangeRegister dataclass

A data class to register parameter change functions.

  • register_func: Callable[[str, str, Dict[str, Tuple]], None] A function that registers a parameter change handler.
  • registry: tuple[ParamChangeRegistryItem, ...] A tuple of items to be registered.

register_all(ui)

Registers all items in the registry using the provided register function and UI.

Parameters: - ui: The user interface object used for registration.

MenuItem defines a single menu entry (action name, callable, arguments, display text). MenuCollection binds a collection of MenuItem instances to a UI, creating missing actions as needed.

REvoDesign.basic.menu_item.MenuItem dataclass

A data class representing a menu item.

This class is used to define the properties of a menu item, including its name, associated function, and optional arguments. The use of the @dataclass decorator automatically generates special methods such as init(), repr(), and eq(). The frozen parameter ensures that instances of the class are immutable, enhancing thread safety and consistency.

Attributes:

Name Type Description
action str

The action attr name associated with the menu item. Set to '---' for a separator to a menu section.
func Callable | str

The function associated with the menu item, which is executed when the item is selected.
args Optional[Tuple]

Optional arguments passed to the associated function when it is executed. Defaults to None.
kwargs Optional[Mapping]

Optional arguments passed to the associated function when it is executed. Defaults to None.
action_text Optional[str]

The text to display in the menu item if we need to build the action from scratch. Defaults to None.
menu_section Optional[str]

The menu section to which the menu item belongs if we need to build the action from scratch. Defaults to None.

is_separator cached property

Returns True if the menu item is a separator, False otherwise.

func_to_call cached property

Returns the real callable function to be executed. If the function is a string, it will be resolved to a callable function.

trigger cached property

Returns a triggered function that is lazy resolved

REvoDesign.basic.menu_item.MenuCollection dataclass

A data class representing a collection of menu items. This class registers the menu items and their associated functions while instantiating the class.

bind()

Binds the menu items to their respective functions. This method iterates over the menu items and binds their functions to the associated actions.

Third-Party Module Abstractions

ThirdPartyModuleAbstract is the base class for all third-party integrations, providing name and installed attributes and inheriting from CitableModuleAbstract for BibTeX citation support. TorchModuleAbstract is a base class for PyTorch-based modules with cross-device memory management.

REvoDesign.basic.abc_third_party_module.ThirdPartyModuleAbstract

Bases: CitableModuleAbstract

Abstract class for third-party modules.

Attributes:

Name Type Description
name str

The name of the third-party module.
installed bool

A flag indicating whether the module is installed.
__bibtex__ dict

A dictionary containing the BibTeX entries for the module.

REvoDesign.basic.abc_third_party_module.TorchModuleAbstract

An abstract class for managing PyTorch modules on different devices.

Parameters:

Name Type Description Default
device str

The device on which the module will run, e.g., "cuda", "mps".

 required
**kwargs

Additional keyword arguments for future extensions or subclass-specific parameters.

 {}

cleanup()

Cleans up the memory cache on the specified device if it is a CUDA or MPS device.

This method checks the device type and clears the respective memory cache using PyTorch's utility functions. It prints a confirmation message after cleaning up the memory.

Mutation Runner

MutateRunnerAbstract is the abstract base class for running protein mutation tools. It provides parallel mutation execution, PDB file mapping, and optional reconstruction support.

REvoDesign.basic.mutate_runner.MutateRunnerAbstract

Bases: ThirdPartyModuleAbstract

Abstract base class for running mutation tools.

Subclasses should implement the specific methods for protein mutation, and optionally, reconstruction.

reconstruct()

Reconstruct the protein structure.

This method can be overridden by subclasses that support reconstruction. By default, it raises a NotImplementedError.

run_mutate(mutant) abstractmethod

Perform mutation on the protein and return the PDB path

Parameters:

Name Type Description Default
mutant Mutant

An object or data structure representing the mutation.

 required

This method should be implemented by subclasses to provide the specific mutation functionality.

run_mutate_parallel(mutants, nproc=2) abstractmethod

Perform mutation on the protein in parallel and return the PDB paths

Parameters:

Name Type Description Default
nproc int

Nproc

 2
mutants list[Mutant]

An list object or data structure representing the mutation.

 required

This method should be implemented by subclasses to provide the specific mutation functionality.