Python: updated docstrings

[eavanvalkenburg]

Motivation and Context

Another round of updates to docstrings, and some fixes to the generation script, we should be able to get rid of that part soon.

Description

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 updates Python docstring formatting to standardize the use of "Keyword Args" sections for named parameters while maintaining "Args" for positional parameters. The changes also include minor fixes to a documentation generation script and some function call improvements.

• Updated docstring formatting across multiple Python files to distinguish between "Args" and "Keyword Args" sections
• Fixed function calls to use proper keyword arguments syntax
• Updated documentation generation script configuration

Reviewed Changes

Copilot reviewed 28 out of 29 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
_provider.py (redis)	Updated docstring formatting to use "Keyword Args" for named parameters
_chat_message_store.py (redis)	Standardized docstring format with "Keyword Args" sections
_provider.py (mem0)	Updated docstring to use "Keyword Args" for named parameters
_sliding_window.py (lab/tau2)	Removed incorrect Args section from docstring
_shared.py (openai)	Updated constructor docstring to use "Keyword Args"
_exceptions.py (openai)	Cleaned up docstring parameter descriptions
observability.py	Updated docstring formatting and removed incorrect parameter
_shared.py (azure)	Added "Keyword Args" section to docstring
_entra_id_authentication.py (azure)	Standardized docstring format with "Keyword Args"
_chat_client.py (azure)	Updated constructor docstring format
_workflow_executor.py (workflows)	Added "Keyword Args" section to constructor
_validation.py (workflows)	Updated validation function docstrings
_magentic.py (workflows)	Standardized docstring format
_executor.py (workflows)	Updated executor docstring formatting
_agent.py (workflows)	Standardized docstring format across methods
_types.py	Extensive docstring updates including format changes and content improvements
_tools.py	Updated docstring formatting and fixed function call syntax
_threads.py	Standardized docstring format with "Keyword Args" sections
_serialization.py	Updated docstring formatting and fixed typo
_middleware.py	Added import, updated function calls, and improved docstring
_memory.py	Standardized docstring format
_mcp.py	Updated docstring formatting across MCP-related classes
_clients.py	Extensive docstring formatting updates
_agents.py	Updated agent class docstring formatting
_agent.py (copilotstudio)	Standardized docstring format
_acquire_token.py (copilotstudio)	Updated function signature and docstring
_agent.py (a2a)	Standardized docstring format
generate_docs.py	Updated documentation generation configuration

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/a2a/agent_framework_a2a
_agent.py	114	14	87%	105, 108–109, 115–118, 121, 125–126, 307–308, 345–346
packages/copilotstudio/agent_framework_copilotstudio
_acquire_token.py	42	0	100%
_agent.py	75	4	94%	154–155, 190, 198
packages/core/agent_framework
_agents.py	226	37	83%	287, 346–348, 394, 442, 460, 597, 660–663, 680, 690, 767–770, 772, 775–777, 899–902, 904, 907–909, 991, 996, 1032, 1073–1074, 1076, 1089
_clients.py	117	13	88%	235, 293, 433, 498–501, 545, 731, 735, 774, 861, 863
_mcp.py	304	111	63%	131, 141–142, 163, 188, 203, 209, 213, 215, 299, 310–315, 318–319, 329–331, 334–336, 338–344, 346–348, 351–352, 374–375, 379–384, 390–391, 395–396, 400, 402, 406–407, 411, 429, 449–459, 471, 474–475, 479, 501, 504–505, 509, 538, 557, 559, 566–567, 586, 588, 594–597, 614–618, 726, 731–735, 829, 832–842, 921, 924–926
_memory.py	70	5	92%	117, 138, 156, 253, 257
_middleware.py	396	9	97%	797, 813, 860–861, 1064–1065, 1110, 1259, 1472
_serialization.py	97	15	84%	185, 195–196, 201, 256, 260, 274, 276–280, 298–299, 312
_threads.py	123	14	88%	232, 315, 327, 439–443, 446–447, 466, 468, 471, 477
_tools.py	460	66	85%	236, 241, 287, 338, 340, 503, 535–536, 692–694, 746–774, 801, 909, 966, 968, 978, 986–987, 1004–1005, 1035–1036, 1123, 1361, 1370–1371, 1378, 1415–1416, 1452, 1455–1457, 1513–1514, 1521–1522
_types.py	889	93	89%	127–128, 146–147, 284, 286, 293, 312, 352, 398–399, 435, 585, 699–700, 702, 727, 734, 751–753, 826, 831–832, 834, 841–842, 844, 866, 873, 876–878, 883–884, 890–892, 1013, 1139, 1320, 1324, 1326, 1570–1572, 1578–1579, 1747, 1823, 1828, 1878, 1883, 1887, 1891, 2098–2102, 2112, 2117, 2398, 2576, 2662–2664, 2687, 2714, 2737, 2745–2749, 2853, 2923, 2927, 2935, 2939–2941, 3041, 3045, 3049, 3053, 3056, 3110–3112, 3180, 3207, 3214
observability.py	603	109	81%	237, 263–265, 267, 269–273, 281, 287–292, 315–317, 319–320, 326, 410, 420, 442, 448, 467–469, 477–479, 502–504, 514–516, 649, 651, 738–742, 745–749, 758–761, 771–774, 776, 863–866, 1041, 1189–1191, 1346, 1353, 1355, 1357, 1359, 1361, 1363, 1365, 1367, 1369, 1371, 1375–1377, 1379, 1389, 1417–1418, 1428, 1431–1434, 1448, 1453–1455, 1457–1460, 1462–1463, 1467, 1470, 1490, 1528, 1544, 1548, 1672, 1674
packages/core/agent_framework/_workflows
_agent.py	222	36	83%	52, 56, 60–63, 91–92, 232, 240–246, 263, 304, 306, 311, 313, 354, 361, 367–368, 374, 386, 418, 425, 446, 453, 457, 459–461, 468
_executor.py	668	190	71%	239, 371, 386, 388, 648, 654, 690–691, 695, 737, 752–759, 765–772, 774–778, 780–786, 792–795, 801–802, 839, 845, 864, 869, 876–880, 882–890, 892–897, 899–901, 937, 939–947, 949–956, 958–962, 964–972, 974–978, 980, 991, 1007, 1011, 1015, 1060, 1084, 1087, 1091, 1098–1099, 1102, 1108–1109, 1124–1128, 1138–1139, 1143–1144, 1149–1152, 1155, 1157–1163, 1167, 1169, 1179, 1189–1194, 1198, 1200, 1203, 1231–1236, 1255, 1269, 1285, 1295–1300, 1335, 1337, 1344–1345, 1409–1411, 1413–1414, 1436, 1446, 1473–1475, 1485–1486, 1488–1489, 1500–1501
_magentic.py	969	263	72%	57–66, 71, 75–86, 315, 340, 345–346, 422, 426, 440, 446, 461, 541, 554, 571, 580–581, 583–585, 587, 598, 665–669, 672–676, 756–759, 762–766, 768–770, 777, 816, 863, 899–901, 903, 1011, 1047, 1056–1058, 1076–1077, 1079–1080, 1099, 1146, 1149, 1177, 1180, 1185, 1193–1197, 1203, 1221–1222, 1233–1235, 1237, 1239, 1247–1252, 1254, 1258–1259, 1262–1265, 1267–1268, 1274–1276, 1279–1280, 1285–1286, 1293–1294, 1296, 1299, 1302, 1305–1307, 1310, 1318, 1330, 1342–1345, 1361, 1366–1368, 1374–1375, 1380–1382, 1415–1416, 1418, 1421, 1424, 1427–1429, 1432, 1440, 1457, 1473, 1483, 1497, 1556, 1562–1563, 1577, 1579, 1582, 1584–1585, 1588–1589, 1593, 1596, 1617, 1652–1653, 1655, 1659–1660, 1664–1666, 1678–1679, 1689–1690, 1705, 1710–1713, 1792–1793, 1797, 1812, 1816–1817, 1821–1822, 1839, 1842, 1866–1867, 1878, 1881–1888, 1896–1900, 1909–1910, 1964–1966, 2003, 2014, 2025–2027, 2057–2059, 2070–2072, 2085–2087, 2090–2091, 2111, 2115, 2119–2120, 2137, 2144, 2147, 2151, 2156, 2193–2196, 2207–2210, 2222–2225, 2234–2237, 2252, 2256
_validation.py	253	12	95%	104, 160, 222, 229, 295, 376, 379, 516, 554–555, 558–559
_workflow_executor.py	247	100	59%	303–304, 339–340, 377, 388–393, 396, 399–400, 407, 410, 413, 424, 448, 451, 457, 461, 474, 478, 503–504, 507–509, 515–516, 518–522, 524–527, 529–533, 535–540, 542, 549–552, 554–561, 563–564, 570–572, 574–577, 579–589, 594, 596–600, 602–604, 606–609, 614, 616, 649
packages/core/agent_framework/azure
_chat_client.py	58	4	93%	166, 168, 181–182
_entra_id_authentication.py	23	0	100%
_shared.py	79	7	91%	135–136, 200, 203, 216, 218, 228
packages/core/agent_framework/openai
_exceptions.py	33	0	100%
_shared.py	74	7	90%	114, 127, 129, 136, 138, 187, 211
packages/mem0/agent_framework_mem0
_provider.py	67	3	95%	159–160, 163
packages/redis/agent_framework_redis
_chat_message_store.py	143	14	90%	144, 177, 267–268, 271, 274, 434, 524–528, 537, 541
_provider.py	188	9	95%	255, 257, 265, 270–271, 274, 329, 386, 398
TOTAL	10248	1697	83%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
1243	98 💤	0 ❌	0 🔥	28.420s ⏱️