Define Asynchronous Conversion Methods in Python Converters
Summary
A structured method for implementing asynchronous conversion methods within MSMetaEnhancer's ComputeConverter subclasses, enabling local chemical structure transformations using RDKit without blocking I/O. This skill ensures proper method signatures, return types, and integration with the framework's asynchronous annotation pipeline.
When to use
When extending MSMetaEnhancer with a new local chemical transformation (e.g., SMILES to InChI) that should execute non-blockingly within an asynchronous annotation workflow. Apply this skill when the conversion logic is computationally self-contained (does not require external web service calls) and must participate in the app's async batch processing loop.
When NOT to use
- Input requires calling external web services (CIR, CTS, PubChem, etc.); use WebConverter subclasses instead.
- Conversion is already available in an existing registered converter; reuse or extend the existing converter rather than duplicating.
- Chemical transformation logic is CPU-intensive or requires blocking I/O; consider a synchronous implementation or offloading to a background task queue.
Inputs
- Python class inheriting from ComputeConverter
- List of conversion specifications (source and target attribute names)
- String input in source chemical format (e.g., SMILES string)
Outputs
- Async conversion method definitions (async def coroutines)
- Dictionary mapping target attribute key to converted chemical representation
- Integrated converter instance available to MSMetaEnhancer Application
How to apply
Create a ComputeConverter subclass by inheriting from the abstract base and defining a conversions list with source and target attributes (e.g., 'smiles' to 'inchi'). Call create_top_level_conversion_methods(conversions, asynch=False) to auto-generate dispatcher methods. Implement individual conversion methods as async def coroutines that accept a string input in the source format, use RDKit APIs (e.g., Chem.MolFromSmiles, Chem.inchi.MolToInchi) to perform the molecular transformation, and return a dictionary keyed by the target attribute name. Ensure each async method uses await syntax where applicable and handles None returns from RDKit gracefully by returning an empty dict or raising a descriptive exception. Register the converter in init.py and validate with pytest test cases covering instantiation and conversion accuracy against reference SMILES inputs.
Related tools
- RDKit (Provides APIs (Chem.MolFromSmiles, Chem.inchi.MolToInchi) for local molecular structure parsing and conversion within async methods)
- MSMetaEnhancer (Framework providing ComputeConverter base class, create_top_level_conversion_methods method, and Application registration mechanism) — https://github.com/RECETOX/MSMetaEnhancer
- pytest (Testing framework for validating converter instantiation and conversion accuracy against reference inputs)
- Python asyncio (Provides async/await syntax and event loop integration for non-blocking method execution in annotation pipeline)
Examples
from MSMetaEnhancer.libs.converters.compute import RDKit; from MSMetaEnhancer.libs.utils.ConverterBuilder import ConverterBuilder; ConverterBuilder.register([RDKit]); import asyncio; result = asyncio.run(RDKit().smiles_to_inchi('CC(C)Cc1ccc(cc1)[C@@H](C)C(=O)O'))
Evaluation signals
- Converter class successfully instantiates and methods are callable as async coroutines (no syntax errors).
- Test cases confirm conversion accuracy: reference SMILES inputs produce chemically correct InChI, InChIKey, or formula outputs matching expected canonical forms.
- Return value structure matches expected dictionary schema (target attribute name as key, string or None value).
- Existing MSMetaEnhancer pytest suite still passes after converter registration in init.py.
- Converter executes within Application.annotate_spectra() without blocking the event loop and completes within reasonable time bounds for typical molecular inputs (single-digit milliseconds per molecule).
Limitations
- RDKit's local conversion may fail silently or return None for invalid or ambiguous SMILES inputs; robust error handling and logging are essential.
- Async method overhead (coroutine overhead, event loop scheduling) is minimal but non-zero; for trivial conversions, synchronous methods may be faster in single-threaded contexts.
- RDKit does not support all chemical formats; conversion coverage is limited to what RDKit's API natively provides (e.g., no support for obscure proprietary formats).
- Asynchronous design does not parallelize RDKit execution across cores within a single Python process due to the GIL; true parallelization requires multiprocessing or external service calls.
Evidence
- [other] Create a new Python file in MSMetaEnhancer/libs/converters/compute/ that inherits from ComputeConverter: "Create a new Python file in MSMetaEnhancer/libs/converters/compute/ that inherits from ComputeConverter"
- [other] Define the conversions list with source and target attributes (e.g., 'smiles' to 'inchi') and call create_top_level_conversion_methods: "Define the conversions list with source and target attributes (e.g., 'smiles' to 'inchi') and call create_top_level_conversion_methods with asynch=False"
- [other] Implement conversion methods using RDKit to perform local molecular structure transformations (e.g., parse SMILES strings with RDKit Chem.MolFromSmiles and generate InChI with Chem.inchi.MolToInchi): "Implement conversion methods using RDKit to perform local molecular structure transformations (e.g., parse SMILES strings with RDKit Chem.MolFromSmiles and generate InChI with Chem.inchi.MolToInchi)"
- [other] Return converted data as a dictionary with target attribute keys: "Return converted data as a dictionary with target attribute keys"
- [other] Register the new converter in MSMetaEnhancer/libs/converters/compute/init.py by importing and adding to all: "Register the new converter in MSMetaEnhancer/libs/converters/compute/init.py by importing and adding to all"
- [readme] The app uses asynchronous implementation of annotation process allowing for optimal fetching speed: "The app uses asynchronous implementation of annotation process allowing for optimal fetching speed"
- [other] Create a pytest test file that validates converter instantiation and tests conversion accuracy against reference SMILES inputs: "Create a pytest test file that validates converter instantiation and tests conversion accuracy against reference SMILES inputs, verifying output structure and chemical correctness"
- [other] Use the RDKit converter as a reference implementation: "Use the RDKit converter as a reference implementation"
1---2name: python-async-method-definition-23description: Use when when extending MSMetaEnhancer with a new local chemical transformation (e.g., SMILES to InChI) that should execute non-blockingly within an asynchronous annotation workflow.4license: CC-BY-4.05---67# Define Asynchronous Conversion Methods in Python Converters89## Summary1011A structured method for implementing asynchronous conversion methods within MSMetaEnhancer's ComputeConverter subclasses, enabling local chemical structure transformations using RDKit without blocking I/O. This skill ensures proper method signatures, return types, and integration with the framework's asynchronous annotation pipeline.1213## When to use1415When extending MSMetaEnhancer with a new local chemical transformation (e.g., SMILES to InChI) that should execute non-blockingly within an asynchronous annotation workflow. Apply this skill when the conversion logic is computationally self-contained (does not require external web service calls) and must participate in the app's async batch processing loop.1617## When NOT to use1819- Input requires calling external web services (CIR, CTS, PubChem, etc.); use WebConverter subclasses instead.20- Conversion is already available in an existing registered converter; reuse or extend the existing converter rather than duplicating.21- Chemical transformation logic is CPU-intensive or requires blocking I/O; consider a synchronous implementation or offloading to a background task queue.2223## Inputs2425- Python class inheriting from ComputeConverter26- List of conversion specifications (source and target attribute names)27- String input in source chemical format (e.g., SMILES string)2829## Outputs3031- Async conversion method definitions (async def coroutines)32- Dictionary mapping target attribute key to converted chemical representation33- Integrated converter instance available to MSMetaEnhancer Application3435## How to apply3637Create a ComputeConverter subclass by inheriting from the abstract base and defining a conversions list with source and target attributes (e.g., 'smiles' to 'inchi'). Call create_top_level_conversion_methods(conversions, asynch=False) to auto-generate dispatcher methods. Implement individual conversion methods as async def coroutines that accept a string input in the source format, use RDKit APIs (e.g., Chem.MolFromSmiles, Chem.inchi.MolToInchi) to perform the molecular transformation, and return a dictionary keyed by the target attribute name. Ensure each async method uses await syntax where applicable and handles None returns from RDKit gracefully by returning an empty dict or raising a descriptive exception. Register the converter in __init__.py and validate with pytest test cases covering instantiation and conversion accuracy against reference SMILES inputs.3839## Related tools4041- **RDKit** (Provides APIs (Chem.MolFromSmiles, Chem.inchi.MolToInchi) for local molecular structure parsing and conversion within async methods)42- **MSMetaEnhancer** (Framework providing ComputeConverter base class, create_top_level_conversion_methods method, and Application registration mechanism) — https://github.com/RECETOX/MSMetaEnhancer43- **pytest** (Testing framework for validating converter instantiation and conversion accuracy against reference inputs)44- **Python asyncio** (Provides async/await syntax and event loop integration for non-blocking method execution in annotation pipeline)4546## Examples4748```49from MSMetaEnhancer.libs.converters.compute import RDKit; from MSMetaEnhancer.libs.utils.ConverterBuilder import ConverterBuilder; ConverterBuilder.register([RDKit]); import asyncio; result = asyncio.run(RDKit().smiles_to_inchi('CC(C)Cc1ccc(cc1)[C@@H](C)C(=O)O'))50```5152## Evaluation signals5354- Converter class successfully instantiates and methods are callable as async coroutines (no syntax errors).55- Test cases confirm conversion accuracy: reference SMILES inputs produce chemically correct InChI, InChIKey, or formula outputs matching expected canonical forms.56- Return value structure matches expected dictionary schema (target attribute name as key, string or None value).57- Existing MSMetaEnhancer pytest suite still passes after converter registration in __init__.py.58- Converter executes within Application.annotate_spectra() without blocking the event loop and completes within reasonable time bounds for typical molecular inputs (single-digit milliseconds per molecule).5960## Limitations6162- RDKit's local conversion may fail silently or return None for invalid or ambiguous SMILES inputs; robust error handling and logging are essential.63- Async method overhead (coroutine overhead, event loop scheduling) is minimal but non-zero; for trivial conversions, synchronous methods may be faster in single-threaded contexts.64- RDKit does not support all chemical formats; conversion coverage is limited to what RDKit's API natively provides (e.g., no support for obscure proprietary formats).65- Asynchronous design does not parallelize RDKit execution across cores within a single Python process due to the GIL; true parallelization requires multiprocessing or external service calls.6667## Evidence6869- [other] Create a new Python file in MSMetaEnhancer/libs/converters/compute/ that inherits from ComputeConverter: "Create a new Python file in MSMetaEnhancer/libs/converters/compute/ that inherits from ComputeConverter"70- [other] Define the conversions list with source and target attributes (e.g., 'smiles' to 'inchi') and call create_top_level_conversion_methods: "Define the conversions list with source and target attributes (e.g., 'smiles' to 'inchi') and call create_top_level_conversion_methods with asynch=False"71- [other] Implement conversion methods using RDKit to perform local molecular structure transformations (e.g., parse SMILES strings with RDKit Chem.MolFromSmiles and generate InChI with Chem.inchi.MolToInchi): "Implement conversion methods using RDKit to perform local molecular structure transformations (e.g., parse SMILES strings with RDKit Chem.MolFromSmiles and generate InChI with Chem.inchi.MolToInchi)"72- [other] Return converted data as a dictionary with target attribute keys: "Return converted data as a dictionary with target attribute keys"73- [other] Register the new converter in MSMetaEnhancer/libs/converters/compute/__init__.py by importing and adding to __all__: "Register the new converter in MSMetaEnhancer/libs/converters/compute/__init__.py by importing and adding to __all__"74- [readme] The app uses asynchronous implementation of annotation process allowing for optimal fetching speed: "The app uses asynchronous implementation of annotation process allowing for optimal fetching speed"75- [other] Create a pytest test file that validates converter instantiation and tests conversion accuracy against reference SMILES inputs: "Create a pytest test file that validates converter instantiation and tests conversion accuracy against reference SMILES inputs, verifying output structure and chemical correctness"76- [other] Use the RDKit converter as a reference implementation: "Use the RDKit converter as a reference implementation"
HolobiomicsLab