Skip to content

Commit c3cf9c0

Browse files
Add kwargs guidelines from issue microsoft#3642 to CODING_STANDARD.md
1 parent b1273a6 commit c3cf9c0

1 file changed

Lines changed: 14 additions & 4 deletions

File tree

‎python/CODING_STANDARD.md‎

Lines changed: 14 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -68,8 +68,8 @@ def process_config(config: MutableMapping[str, Any]) -> None:
6868

6969
To make the code easier to use and maintain:
7070

71-
- **Positional parameters**: Only use for up to 3 fully expected parameters
72-
- **Keyword parameters**: Use for all other parameters, especially when there are multiple required parameters without obvious ordering
71+
- **Positional parameters**: Only use for up to 3 fully expected parameters (this is not a hard rule, but a guideline there are instances where this does make sense to exceed)
72+
- **Keyword-only parameters**: Arguments after `*` in function signatures are keyword-only; prefer these for optional parameters
7373
- **Avoid additional imports**: Do not require the user to import additional modules to use the function, so provide string based overrides when applicable, for instance:
7474
```python
7575
def create_agent(name: str, tool_mode: ChatToolMode) -> Agent:
@@ -82,10 +82,20 @@ def create_agent(name: str, tool_mode: Literal['auto', 'required', 'none'] | Cha
8282
if isinstance(tool_mode, str):
8383
tool_mode = ChatToolMode(tool_mode)
8484
```
85-
- **Document kwargs**: Always document how `kwargs` are used, either by referencing external documentation or explaining their purpose
86-
- **Separate kwargs**: When combining kwargs for multiple purposes, use specific parameters like `client_kwargs: dict[str, Any]` instead of mixing everything in `**kwargs`
8785
- **Avoid shadowing built-ins**: Do not use parameter names that shadow Python built-ins (e.g., use `next_handler` instead of `next`). See [#3583](https://github.com/microsoft/agent-framework/issues/3583) for progress.
8886

87+
### Using `**kwargs`
88+
89+
> **Note:** This convention is being adopted. See [#3642](https://github.com/microsoft/agent-framework/issues/3642) for progress.
90+
91+
Avoid `**kwargs` unless absolutely necessary. It should only be used as an escape route, not for well-known flows of data:
92+
93+
- **Prefer named parameters**: If there are known extra arguments being passed, use explicit named parameters instead of kwargs
94+
- **Subclassing support**: kwargs is acceptable in methods that are part of classes designed for subclassing, allowing subclass-defined kwargs to pass through without issues. In this case, clearly document that kwargs exists for subclass extensibility and not for passing arbitrary data
95+
- **Remove when possible**: In other cases, removing kwargs is likely better than keeping it
96+
- **Separate kwargs by purpose**: When combining kwargs for multiple purposes, use specific parameters like `client_kwargs: dict[str, Any]` instead of mixing everything in `**kwargs`
97+
- **Always document**: If kwargs must be used, always document how it's used, either by referencing external documentation or explaining its purpose
98+
8999
## Method Naming Inside Connectors
90100

91101
When naming methods inside connectors, we have a loose preference for using the following conventions:

0 commit comments

Comments
 (0)