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.
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.
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.
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 |
Menu Items¶
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.
Attributes:
| Name | Type | Description |
|---|---|---|
action |
str
|
The action attr name associated with the menu item.
Set to |
func |
Callable | str
|
The function associated with the menu item, executed when
the item is selected. May be a callable, a dotted-string
reference ( |
args |
tuple | None
|
Positional arguments passed to func on trigger. |
kwargs |
Mapping | None
|
Keyword arguments passed to func on trigger. |
action_text |
str | None
|
Display text for dynamically-created actions. |
menu_section |
str | QMenu | None
|
Target QMenu (or its object name) for dynamically- created actions. |
is_separator
cached
property
¶
Return True if this item is a menu separator.
func_to_call
cached
property
¶
Return the resolved callable for this menu item.
trigger
cached
property
¶
Return a zero-argument callable that invokes func_to_call.
separator(menu_section)
classmethod
¶
Shorthand for a menu separator in menu_section.
REvoDesign.basic.menu_item.MenuCollection
dataclass
¶
Bind a collection of MenuItems to a UI proxy's named QActions / QMenus.
bind()
¶
Bind every menu item to its QAction (static or dynamically-created).
bind_one(item)
¶
Bind a single item to the UI.
When a QAction with item.action already exists on the UI it is connected directly. Otherwise a new QAction is created and added to the menu section named by item.menu_section.
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.