docs(python): Clarify behavior of DataFrame.rows_by_key

[BGR360]

When I read the docs for this method for the first time, it was not at all clear to me how the returned dictionary was constructed until I scrolled all the way down to the examples. And even then, it took me a little while to understand.

I edited the description to be a bit more clear about how the dictionary is structured, while trying not to be too redundant with the examples and parameter docs.

Also, while I was here, I added a little blurb to the rows docs as well.

[BGR360]

Question: could we be any more precise about the return type of rows_by_key? It's pretty vague:

def rows_by_key(...) -> dict[Any, Iterable[Any]]

Compared to rows:

def rows(...) -> list[tuple[Any, ...]] | list[dict[str, Any]]:

That being said, the return type of rows_by_key is certainly more complicated and has more variants than that of rows.

[stinodego]

@alexander-beedie would you mind reviewing this one (and the comment about the return type)?

[alexander-beedie]

Question: could we be any more precise about the return type of rows_by_key? It's pretty vague:

Possibly, but it would need quite a few @overload decorators to cover all of the permutations; I'll see what I can do ;)