Skip to content

Python: drop docstring arguments the signatures no longer accept - #14744

Open
Hyacinth-of-Security (lxcxjxhx) wants to merge 1 commit into
microsoft:mainfrom
lxcxjxhx:docs/docstring-arg-drift
Open

Hyacinth-of-Security (lxcxjxhx) wants to merge 1 commit into
microsoft:mainfrom
lxcxjxhx:docs/docstring-arg-drift

Conversation

@lxcxjxhx

Copy link
Copy Markdown

Motivation and Context

Ten docstrings across nine files in python/semantic_kernel list an argument that the function below them does not accept. Nothing here changes behaviour: signatures, defaults and bodies are untouched, only the prose.

This matters because these are the docstrings that end up in the generated API reference and in editor tooltips. Kernel.as_mcp_server telling the reader to pass kernel= is the clearest example — Kernel is the instance, so anyone following the docs writes a call that silently goes into **kwargs.

Description

File Docstring listed Signature accepts
kernel.py — Kernel.as_mcp_server kernel self (no kernel; **kwargs would swallow it silently)
core_plugins/text_memory_plugin.py — TextMemoryPlugin.save kernel text, key, collection
agents/orchestration/group_chat.py — GroupChatManager.filter_results participant_descriptions chat_history (the sibling select_next_agent does take it — that docstring is correct and untouched)
agents/bedrock/bedrock_agent.py — create_and_prepare_agent prompt_template_config name, instructions, and the keyword-only arguments listed there
agents/bedrock/bedrock_agent.py — create_channel chat_history thread_id only
connectors/memory_stores/azure_cognitive_search/..._memory_store.py — create_collection semantic_config collection_name, vector_config, search_resource_encryption_key
connectors/ai/open_ai/exceptions/content_filter_ai_exception.py — from_inner_error_result key inner_error_results
contents/chat_message_content.py — to_element root_key no parameters
contents/streaming_chat_message_content.py — to_element root_key no parameters
memory/semantic_text_memory_base.py — SemanticTextMemoryBase.search with_embeddings collection, query, limit, min_relevance_score

9 files changed, 14 deletions(-) — every line removed is a docstring line.

Verification

  • ruff check on the nine touched files: one finding, D421 at contents/chat_message_content.py:201, which is a pre-existing property docstring this PR does not touch (my change in that file is at line 235).
  • ruff format --check on the same files: already formatted.
  • Docstrings only: nothing imports or reads them at runtime, so there is no build, typing or API-compatibility surface to re-verify. I did not run the unit-test suite; saying so rather than ticking the box.

What I left alone

  • ChromaMemoryStore.__init__ still documents similarity_fetch_limit — the class is marked @deprecated and points at ChromaStore, so it is not worth a docstring commit.
  • OpenAIResponsesAgent.get_response / invoke / invoke_stream document additional_instructions, additional_messages, max_prompt_tokens; BedrockAgent.create_and_prepare_agent neighbours and AutoGenConversableAgent.invoke have the same shape. All of these forward **kwargs, so whether the names are dead or merely undocumented keyword passthroughs is a maintainer call rather than something a static check can settle.
  • data/text_search.py create_search_function documents string_mapper, which exists on an @overload of the same name — correct, not drift.

AI assistance: the list was produced by a static check over Google-style Args: blocks, then each row was read against its signature and, where relevant, against the sibling overloads before being kept. The description was written from those diffs.

Contribution Checklist

  • The code builds clean without any errors or warnings — docstrings only; ruff reports nothing new on the touched files.
  • The PR follows the SK Contribution Guidelines — ruff check / ruff format --check run as the pre-submission formatting step describes.
  • All unit tests pass, and I have added new tests where possible — no tests added: there is nothing to assert for a docstring edit, and I did not run the suite.
  • I didn't break anyone

Copilot AI balanced review requested due to automatic review settings November 7, 2026 13:38
@semantic-kernel-automation semantic-kernel-automation Bot added the python Pull requests for the Python Semantic Kernel label Nov 7, 2026

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

No active review issues are recorded for the docstring cleanup that removes unsupported argument descriptions.

No open issues 🎉

What changed in this PR

Aligns ten Python SDK docstrings with their function signatures, removing unsupported arguments from generated API documentation and editor tooltips.

Changes:

  • Removes stale argument descriptions across nine files.
  • Removes empty Args: sections from both chat-message to_element docstrings.
  • Leaves function signatures, defaults, and implementation code unchanged.
File Description
python/​semantic_kernel/​memory/​semantic_text_memory_base.py Removes with_embeddings from search documentation.
python/​semantic_kernel/​kernel.py Removes kernel from as_mcp_server documentation.
python/​semantic_kernel/​core_plugins/​text_memory_plugin.py Removes kernel from save documentation.
python/​semantic_kernel/​contents/​streaming_chat_message_content.py Removes the obsolete root_key argument section.
python/​semantic_kernel/​contents/​chat_message_content.py Removes the obsolete root_key argument section.
python/​semantic_kernel/​connectors/​memory_stores/​azure_cognitive_search/​azure_cognitive_search_memory_store.py Removes semantic_config from create_collection documentation.
python/​semantic_kernel/​connectors/​ai/​open_ai/​exceptions/​content_filter_ai_exception.py Removes key from from_inner_error_result documentation.
python/​semantic_kernel/​agents/​orchestration/​group_chat.py Removes participant_descriptions from filter_results documentation.
python/​semantic_kernel/​agents/​bedrock/​bedrock_agent.py Removes stale prompt_template_config and chat_history argument descriptions.

Review effort: Balanced

This branch was successfully deployed

1 active deployment
github-app-auth — 4efba603 Deployed Nov 7, 2026 by lxcxjxhx via add_label #29625
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

python Pull requests for the Python Semantic Kernel

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants