[docs] dictionary unpacking `fn(**kwargs)` should accept `SupportsKeysAndGetitem` and not just `Mapping`
Ninguém assumiu esta issue ainda.
- Linguagem predominante
- Python
- Estrelas
- 77.2k
- Forks
- 36k
- Métricas de merge de PRs
- Métricas de PR pendentes
Descrição
Brief
The docs say that for dict unpacking as in fn(**kwargs), kwargs must "implement the methods specified in the collections.abc.Mapping", when in reality only keys() and __getitem__ as in the dict constructor are required.
Documentation
The current documentation states that:
[6.2.5.4. Dictionary displays]
Instead of a key-value pair, a dict item may be an expression prefixed by a double asterisk **. This denotes dictionary unpacking. At runtime, the expression must evaluate to a mapping;
which points to
[mapping]
A container object that supports arbitrary key lookups and implements the methods specified in the collections.abc.Mapping or collections.abc.MutableMapping abstract base classes.
However, at runtime, fn(**kwargs) works whenever kwargs supports both a keys() -> Iterable[str] and __getitem__(self, key: str) -> object method:
class SupportsKeysAndGetitem:
_dict = {"foo": 0, "bar": object()}
def keys(self):
return iter(self._dict)
def __getitem__(self, key: str, /) -> object:
return self._dict[key]
def expects_kwargs(**kwargs: int) -> None:
print(kwargs)
d = SupportsKeysAndGetitem()
expects_kwargs(**d) # works at runtime
Moreover, the relevant methods that Cpython executes under the hood explicitly supports this looser protocol:
class dict
If a positional argument is given and it defines a keys() method, a dictionary is created by calling getitem() on the argument with each returned key from the method.
and
int PyDict_Merge(PyObject *a, PyObject *b, int override)
Part of the Stable ABI. Thread safety: Safe for concurrent use on the same object.
Iterate over mapping object b adding key-value pairs to dictionary a. b may be a dictionary, or any object supporting PyMapping_Keys() and PyObject_GetItem().
Proposal
Update the documentation of dict-unpacking to reflect the actual runtime behavior in sync with how dict construction works, only requiring keys() and __getitem__ rather than inheritance from the non-protocol class collections.abc.Mapping.
Rationale
fn(**kwargs)only requiringkeys()and__getitem__is how it works at runtime, and has since ages- Supporting a protocol is nicer than just supporting a non-protocol ABC like
collections.abc.Mappingdue to duck-typing (a similar conclusion was reached in the discussion of #116938) - There are real world use-cases like
fn(**dataframe)as for example a pandas DataFrame supportskeys()(yields the list of columns) and__getitem__(look up column by name), but does not inherit from thecollections.abc.Mappingclass, nor implements all of its methods.
Linked PRs
- gh-157771
Guia de contribuição
Primeiros passos
- Leia a issue inteira e depois o guia de contribuição do projeto.
- Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
- Faça um fork do repositório e trabalhe em uma branch.
- Abra um pull request que referencie o número da issue.
Direção de pesquisa
Revise o PR vinculado gh-157771 junto com a documentação sobre exibições de Dictionary e mapping citada na issue. Verifique a redação de acordo com o comportamento em tempo de execução descrito de keys() e getitem; considera-se concluído quando a documentação não exigir mais herança de Mapping e continuar consistente com a construção de dict.
Escrita pelo modelo de indexação a partir do texto da issue.
Avaliação
- Stack de tecnologia
- python
- Domínio
- documentation
- Tipo de issue
- Documentação
- Dificuldade
- 1/5
- Tempo estimado
- 1-3 horas
- Status de atividade
- Estagnada
- Clareza
- Claramente especificada
- Facilidade para iniciantes
- 30/100