python / python/cpython

Meta issue: improve documentation for implementation of the PEP 3118 in Python

Aberta
#149,402 5 comentários 0 reações 0 responsáveis Ver no GitHub

Ninguém assumiu esta issue ainda.

docs extension-modules interpreter-core topic-ctypes
Linguagem predominante
Python
Estrelas
77.2k
Forks
35.9k
Métricas de merge de PRs
Métricas de PR pendentes

Descrição

Documentation

Recent d.p.o discussion thread and SC decision reveal some problems with current docs. Affected parts are the memoryview and struct/array/ctypes modules. I'll list issues in a random order with a hope that people will extend/correct this list:

  • The struct module docs has Format Characters section. Though, some type codes now have more than one character. We should rename this section and use some different term. Format Codes? // https://github.com/python/cpython/pull/149483
  • array docs says: The type is specified at object creation time by using a type code, which is a single character. // https://github.com/python/cpython/pull/149483
  • memoryview docs are too vague in their references to the struct module:
    • "format" described as being "in struct module style"
    • it might be not clear that means "single element native format" (C type with native byte size, native endianness, and native alignment)
  • ctypes has no documentation for the buffer protocol support at all; though, it's probably most advanced across of the stdlib, see Lib/test/test_ctypes/test_pep3118.py.
  • ctypes._SimpleCData._type_ docs says "Class attribute that contains an internal type code, as a single-character string. See Fundamental data types for a summary." // https://github.com/python/cpython/pull/149483
Linked PRs
  • gh-149483

Guia de contribuição

Abrir o guia de contribuição

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Direção de pesquisa

Comece pelas seções da documentação sobre memoryview, struct, array e ctypes; em seguida, leia a discussão vinculada e a decisão do SC sobre a terminologia pretendida do PEP 3118. Use Lib/test/test_ctypes/test_pep3118.py para entender o comportamento existente de ctypes com o buffer protocol. A tarefa estará concluída quando as referências aos formatos de memoryview forem precisas e o suporte a buffers de ctypes estiver documentado.

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
4/5
Tempo estimado
3-5 dias
Status de atividade
Ativa
Clareza
Razoavelmente clara
Facilidade para iniciantes
48/100

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.