Python: reject @executor on staticmethod/classmethod with clear error message

[Evan Mattson (moonbox3)]

Motivation and Context

Addresses the underlying issue from a bug report about @executor being used with @staticmethod. While this is not a supported use case, the decorator now properly detects and rejects this pattern with a clear, actionable error message.

The @executor decorator is designed for standalone module-level functions only. When mistakenly used with @staticmethod or @classmethod, it would previously fail with confusing errors or incorrect behavior because:

1. When decorators are stacked (@executor then @staticmethod), the executor receives a descriptor object, not the function
2. asyncio.iscoroutinefunction() returns False for descriptor objects, even if the wrapped function is async
3. No validation prevented this misuse

The fix is to have:

• Detection and Clear Error Messages:
  • Added isinstance() check to detect staticmethod and classmethod descriptors
  • Raises ValueError with actionable guidance directing users to the correct pattern:
    • Use @executor for standalone functions
    • Use Executor subclass with @handler on instance methods

Defensive Unwrapping:

• Added _unwrap_descriptor() helper to extract underlying callables from descriptors
• Makes sure async detection works correctly even in edge cases
• Applied unwrapping before signature validation and async checks

Description

• Closes Python: @executor incorrectly treats @staticmethod async def as sync functions #1678
• Added unit tests for coverage

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[Copilot]

Pull Request Overview

This PR enhances the Python @executor decorator to properly detect and reject its misuse with @staticmethod and @classmethod through clear, actionable error messages. Previously, using @executor with these descriptors would fail with confusing errors because the decorator received a descriptor object instead of the actual function, causing async detection to fail.

Key Changes:

• Added explicit validation to reject @staticmethod/@classmethod usage with helpful error messages
• Introduced _unwrap_descriptor() helper for defensive unwrapping in edge cases
• Enhanced documentation to clarify the intended usage pattern (standalone functions vs. class-based executors)

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
python/packages/core/agent_framework/_workflows/_function_executor.py	Added descriptor detection/rejection logic, unwrapping helper, and updated documentation to clarify supported usage patterns
python/packages/core/tests/workflow/test_function_executor.py	Added comprehensive tests validating rejection of @staticmethod/@classmethod and documenting async detection behavior with descriptors

[Mark Wallace (markwallace-microsoft)]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_workflows
_function_executor.py	44	4	90%	101, 107, 113, 129
TOTAL	12296	2004	83%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
1404	98 💤	0 ❌	0 🔥	27.847s ⏱️