From 3339d75b63e45efeeb6d8b9f8653089ea14f1456 Mon Sep 17 00:00:00 2001 From: Stephen Rosen Date: Wed, 5 Jul 2023 19:27:51 -0500 Subject: [PATCH] Add keyword arg guidelines to contrib doc (#775) --- CONTRIBUTING.adoc | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index 5ca3d23e4..2894b5e03 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -68,3 +68,14 @@ Style guidance which doesn't get handled by linters and fixers: - If a docstring contains special characters like `\\`, consider using a raw string to ensure it renders correctly + + - Use the `*` marker for keyword-only arguments for any signatures which + take keyword arguments. (For an explanation, see + [PEP 3102](https://peps.python.org/pep-3102/).) + + - Avoid use of `**kwargs` to capture arbitrary keyword arguments. Instead, + always define a named dict argument for any open extension points (see + `query_params` for prior art in the SDK, or `extra` in `logging` for a + case from the stdlib). + This makes type checking more effective and avoids a class of backwards + compatibility issues when arguments are added.