Add the args and kwargs page

Author: delfick

docs/advice/advice/types_for_args_and_kwargs.rst

@@ -0,0 +1,80 @@
+.. _types_for_args_and_kwargs:
+
+Adding types for ``*args`` and ``**kwargs``
+===========================================
+
+Given a function like this:
+
+.. code-block:: python
+
+    def foo(*args: X, **kwargs: Y) -> None:
+        pass
+
+The types of ``args`` and ``kwargs`` will be ``tuple[X, ...]`` and
+``dict[str, Y]`` respectively.
+
+Avoid args+kwargs, replicate the parent method's signature
+----------------------------------------------------------
+
+When overriding a method defined in a parent class, it's better to be a little
+verbose and replicate the parent signature, even if it is unchanged in the child
+class and those arguments aren't used.
+
+So instead of:
+
+.. code-block:: python
+
+    from typing import Any
+
+    class Parent:
+        def some_method(self, var1: int, *, var2: bool) -> str:
+            ...
+
+    class Child(Parent):
+        def some_method(self, *args: Any, **kwargs: Any) -> str:
+            super().some_method(*args, **kwargs)
+
+Use:
+
+.. code-block:: python
+
+    class Parent:
+        def some_method(self, var1: int, *, var2: bool) -> str:
+            ...
+
+    class Child(Parent):
+        def some_method(self, var1: int, *, var2: bool) -> str:
+            super().some_method(var1, var2=var2)
+            # Do other things
+
+Mypy does not support defining the signature of a method in terms of
+the signature of a different method (like the method being overridden) so it's
+best to explicitly replicate the signature of the parent method.
+
+Avoid kwargs, replace dictionaries with custom types
+----------------------------------------------------
+
+Rather than using ``**kwargs`` to pass dictionaries of options between functions,
+consider defining a custom type to pass instead. E.g. a class defined with
+``dataclasses``, ``attrs`` or other similar libraries. Types with explicit fields
+provide better type safety than dictionaries as mypy can't be certain of what
+keys are present in a dictionary.
+
+Use ``typing.Unpack``
+---------------------
+
+It's also possible to use ``typing.Unpack`` to explicitly define the
+types of the ``kwargs`` dictionary. E.g.
+
+.. code-block:: python
+
+    from typing import TypedDict, Unpack
+
+    class Args(TypedDict):
+        name: str
+        age: int
+
+    def foo(**kwargs: Unpack[Args]) -> str:
+        ...
+
+This will indicate to mypy that ``kwargs`` is a dictionary of type ``Args``.

docs/advice/index.rst

@@ -8,3 +8,4 @@ Kraken Static Typing Advice
    advice/understanding_typevars
    advice/strongly_typed_decorators_and_descriptors
    advice/using_abc_vs_protocols
+   advice/types_for_args_and_kwargs