Exceptions

All exceptions in HELMshaker inherit from a common base class, making it easy to catch any library-specific error.

Exception Hierarchy

HelmShakerError (base)
├── ReadError            # Errors during reading/parsing
├── WriteError           # Errors during writing/conversion
├── ModificationError    # Errors during molecule modification
├── ValidationError      # Errors during validation process
├── VisualizationError   # Errors during visualization
├── MonomerLibraryError  # No monomer library available
├── MappingError         # Retained for backwards compatibility
└── InvalidNotationError # Unknown notation format

Usage Example

HELMshaker ships no monomers, so reading without a library raises MonomerLibraryError before any parsing happens. See Monomer Libraries for how to get one.

from helmshaker import Molecule, MonomerLibrary
from helmshaker.exceptions import HelmShakerError, MonomerLibraryError, ReadError

library = MonomerLibrary()
library.load_from_file("monomers.json")  # your dictionary, or one pulled from TMR

# No library at all: raised before the string is even parsed.
try:
    Molecule.from_helm("RNA1{[moe](A)}$$$$V2.0")
except MonomerLibraryError as e:
    print(f"No library: {e}")

# Malformed notation, with a library present.
try:
    Molecule.from_helm("invalid helm string", monomer_library=library)
except ReadError as e:
    print(f"Failed to read HELM: {e}")

# Catch any HELMshaker error.
try:
    molecule = Molecule.from_helm("RNA1{[moe](A)p.[moe](U)}$$$$V2.0", monomer_library=library)
    molecule.apply_pattern("unknown_pattern")
except HelmShakerError as e:
    print(f"HELMshaker error: {e}")

Backwards Compatibility

For backwards compatibility with older code, the following aliases are available:

New Name	Alias
HelmShakerError	MoleculeError
ReadError	ParsingError
WriteError	ConversionError

API Reference

HelmShakerError

Bases: Exception

Base exception for all errors raised by the HELMshaker package.

ReadError

Bases: HelmShakerError

Exception raised for errors that occur during reading of molecule data.

WriteError

Bases: HelmShakerError

Exception raised for errors that occur during writing of molecule data.

ModificationError

Bases: HelmShakerError

Exception raised for errors that occur during modification of molecule data.

InvalidNotationError

Bases: HelmShakerError

Exception raised when an invalid notation is provided.

ValidationError

Bases: HelmShakerError

Exception raised for errors that occur during the validation process itself.

Note: This is for technical issues during validation, not for reporting chemical validity problems (which should be in a ValidationResult object).

VisualizationError

Bases: HelmShakerError

Exception raised for errors that occur during visualization of molecule data.

MappingError

Bases: HelmShakerError

Exception raised for errors during monomer library remapping.

MonomerLibraryError

Bases: HelmShakerError

Exception raised when no monomer library is available.

HELMshaker ships no bundled monomers: a library must be supplied explicitly (monomer_library=), pinned via a {lib=name@version} annotation and resolved from the cache, or pulled with MonomerLibrary.from_tmr(...).