Skip to content

Python: drop a Returns section from a method that returns None - #10168

Merged
Eduard van Valkenburg (eavanvalkenburg) merged 1 commit into
microsoft:mainfrom
lxcxjxhx:docs/executor-returns
Nov 9, 2026
Merged

Eduard van Valkenburg (eavanvalkenburg) merged 1 commit into
microsoft:mainfrom
lxcxjxhx:docs/executor-returns

Conversation

@lxcxjxhx

Copy link
Copy Markdown
Contributor

Motivation & Context

Executor.execute is annotated -> None and returns nothing, but its docstring still advertises a return value:

        Returns:
            An awaitable that resolves to the result of the execution.

The wording survived from an earlier shape of this method: the coroutine now resolves to None after the handlers have been dispatched. Because execute is the method every workflow internals path goes through, the stale sentence is the first thing a reader sees when they open the base class to find out how a message reaches a handler.

Description & Review Guide

  • What are the major changes? Removes the Returns: section of WorkflowExecutor.execute (python/packages/core/agent_framework/_workflows/_executor.py). Nothing else changes: no signature, no default, no behaviour, no tests.
  • What is the impact of these changes? Documentation only. python-api-compatibility and the typing jobs are unaffected because no annotation moves.
  • What do you want reviewers to focus on? Whether removing the section is preferable to rewording it. I removed it because the method genuinely produces no value; if you would rather keep a sentence for symmetry with the Args: block, a one-line "Returns nothing; send results through runner_context." is an equally small diff.

Evidence that the documented value does not exist:

  • async def execute(self, message, source_executor_ids, state, runner_context, ...) -> None — the annotation is None.
  • The only internal call site, _edge_runner.py:147, does await target_executor.execute(...) and discards the result.
  • A repository-wide search for = await …\.execute( finds middleware pipelines, the AG-UI intent owner, and database cursors — no caller of this method reads a value.

Related Issue

N/A - trivial change. One docstring section removed on a method that returns None; no design decision is involved and the diff is three deleted lines.

AI Assistance

  • This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: the stale section was located with a static check that reports Returns: blocks in functions whose body never returns a value, and documentation assistance (this description) was used. The finding itself was confirmed by hand against the signature and the single internal call site listed above.

Contribution Checklist

  • The code builds clean without any errors or warnings
  • All unit tests pass, and I have added new tests where possible
  • The PR follows the Contribution Guidelines
  • This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change exception.
  • This is not a breaking change.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

There are no active review issues for the documentation-only update aligning the execute docstring with its None return annotation.

No open issues 🎉

What changed in this PR

This documentation-only change corrects the workflow executor’s execute docstring to match its None return annotation.

Changes:

  • Removes the outdated Returns: section that advertised an execution result.
  • Leaves the signature, runtime behavior, and tests unchanged.
File Description
python/​packages/​core/​agent_framework/​_workflows/​_executor.py Removes the misleading return-value documentation from execute.

Review effort: Balanced

Merged via the queue into microsoft:main with commit 6b3b9f8 Nov 9, 2026
55 checks passed
BranBenji pushed a commit to BranBenji/agent-framework that referenced this pull request Nov 11, 2026
…soft#10203)

`restore_from_checkpoint` is annotated `-> None` and never returns a value, so the
`Returns: None on success.` block repeats the annotation. Same shape as microsoft#10168.

Co-authored-by: lxcxjxhx <[email protected]>

This branch was previously deployed

1 inactive deployment
github-app-auth — a48a5b45 Deployed Nov 7, 2026 by lxcxjxhx via team_check #8940
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

python Usage: [Issues, PRs], Target: Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants