Summary

PEP 692 introduced a way define the keyword arguments are runtime using Unpack on a TypedDict. This allows for the TypedDict's attributes to be used directly as keyword arguments, and the actual keyword argument shouldn't be used.

This causes issues when Ruff tries to check that the arguments are documented in a docstring.

Example

The PEP document gives the following example which suffices for this example:

from typing import TypedDict, Unpack

class Movie(TypedDict):
    name: str
    year: int

def foo(**kwargs: Unpack[Movie]) -> None:
    """
    Foo a movie.

    Args:
        name: The name of the movie.
        year: The year the movie was released.
    """
    assert kwargs["year"] > 0

movie: Movie = {"name": "Life of Brian", "year": 1979}

foo(movie)                                  # Invalid
foo(kwargs=movie)                           # Invalid
foo(**movie)                                # OK!
foo(name="The Meaning of Life", year=1983)  # OK!

In effect, the use of Unpack[Movie] is meant to replace the kwargs with the relevant keyword arguments as inferred from the Movie TypedDict and as a result:

def foo(**kwargs: Unpack[Movie]) -> None: ...

becomes essentially equivalent to:

def foo(*, name: str, year: int) -> None: ...

The above example (using Google style) will raise the following error:

ruff-unpack-example.py:7:5: D417 Missing argument description in the docstring for `foo`: `**kwargs`

Solution

Ideal World

The most ideal solution would be for Ruff to parse the TypedDict and adjust the keyword arguments accordingly. I suspect this is beyond the scope of Ruff's current capabilities.

Compromise

If Ruff sees specifically the pattern **{arg}: Unpack[{class}], then:

• Ruff should not require that arg be documented.
• Better yet, Ruff should perform a check in case arg is documented, and raise a warning as the documentation is misleading.