fix(common): async execution helper for awaitable coroutine objects

[dipeshbabu]

AgentScope version
0.1.5

Description
_execute_async_or_sync_func can mis-handle coroutine objects and other awaitables. If an already-created awaitable (such as a coroutine returned by calling an async function, or an asyncio Task/Future) is passed in, the previous logic may treat it like a callable and attempt await func(*args, **kwargs), which can raise runtime errors because awaitable objects are not callable. The previous _is_async_func logic also had operator precedence pitfalls and mixed generator checks that could lead to incorrect classification.

Purpose
Make _execute_async_or_sync_func reliable for all supported async and sync execution paths, including async callables, sync callables that return awaitables, and already-created awaitable objects, while keeping behavior unchanged for normal synchronous functions.

Changes made
Add a robust execution strategy:
If func is an awaitable object (coroutine, Task, Future), await it directly and disallow args and kwargs. Otherwise require func to be callable, call it, and if the return value is awaitable, await the result. Replace the previous async classification helper with a simpler _is_async_callable that only checks coroutine functions (including partials).

How to test
Run a small script that calls _execute_async_or_sync_func with an async function, a sync function, a sync function that returns a coroutine, a coroutine object (af()), and an asyncio Task. Confirm all return expected results without TypeError.

Checklist

Please check the following items before code is ready to be reviewed.

• Code has been formatted with pre-commit run --all-files command
• All tests are passing
• Docstrings are in Google style
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[gemini-code-assist]

Summary of Changes

Hello @dipeshbabu, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the reliability and correctness of asynchronous function execution within AgentScope by addressing how awaitable objects are handled. It refines the core utility for executing both synchronous and asynchronous functions, ensuring that pre-existing awaitables are correctly awaited rather than mistakenly invoked as callables. Additionally, it improves the robustness of temporary file operations in the configuration loading mechanism, preventing potential resource leaks.

Highlights

• Improved Async Execution: The _execute_async_or_sync_func utility has been refactored to reliably handle various async and sync execution paths, including direct awaitable objects, async callables, and sync callables returning awaitables.
• Robust Awaitable Handling: Introduced logic to directly await coroutine objects, asyncio.Task, or asyncio.Future when passed to _execute_async_or_sync_func, preventing TypeError when they were previously treated as callables.
• Simplified Async Classification: Replaced the complex _is_async_func helper with a more focused _is_async_callable that accurately identifies coroutine functions and partials.
• Enhanced Temporary File Management: Modified the _load_config_from_path_or_default function to ensure temporary YAML configuration files are reliably cleaned up, even if errors occur during processing.

Changelog

• src/agentscope/_utils/_common.py
  • Removed unused imports asyncio and types.
  • Replaced the _is_async_func helper with a new _is_async_callable function for more precise async function detection.
  • Refactored _execute_async_or_sync_func to first check if the input func is an awaitable object (like a coroutine or Task) and await it directly, disallowing arguments in this case.
  • Added checks to ensure func is either callable or an awaitable object, raising TypeError for invalid types.
  • Modified _execute_async_or_sync_func to call func and then await its result if the result is awaitable.
• src/agentscope/tuner/_config.py
  • Reordered import statements for better consistency.
  • Added contextlib and os to imports.
  • Updated the temporary file creation logic in _load_config_from_path_or_default to use delete=False and ensure explicit cleanup of the temporary file using os.unlink within a finally block, suppressing OSError during cleanup.

Activity

• The author has completed the pre-commit formatting, ensured all tests are passing, and confirmed docstrings are in Google style.
• The code is marked as ready for review.
• Documentation updates are pending.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request provides a much-needed fix for the _execute_async_or_sync_func helper, making it more robust in handling various awaitable and callable types. The new implementation correctly distinguishes between awaitable objects and callables, preventing runtime errors that could occur with the previous logic. The changes in src/agentscope/tuner/_config.py to handle temporary files are also a good improvement, especially for cross-platform compatibility.

My review focuses on ensuring adherence to the repository's coding standards. I've identified a couple of instances where the docstrings for the updated functions in _utils/_common.py do not conform to the required format specified in the style guide. I've provided suggestions to align them with the project's standards.

Overall, this is a solid contribution that improves the reliability of asynchronous execution within the library.

[dipeshbabu]

@DavdGao could you review this one as well?