Meta issue: improve documentation for implementation of the PEP 3118 in Python
Nadie ha tomado este issue todavía.
- Lenguaje dominante
- Python
- Estrellas
- 77.2k
- Forks
- 35.9k
- Métricas de merge de PR
- Métricas de PR pendientes
Descripción
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
Guía de contribución
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Línea de trabajo
Empieza por las secciones de documentación de memoryview, struct, array y ctypes; después, lee la discusión enlazada y la decisión del SC sobre la terminología prevista de PEP 3118. Usa Lib/test/test_ctypes/test_pep3118.py para comprender el comportamiento existente de ctypes con el buffer protocol. La tarea está terminada cuando las referencias a los formatos de memoryview sean precisas y la compatibilidad de ctypes con buffers esté documentada.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Stack tecnológico
- python
- Área
- documentation
- Tipo de issue
- Documentación
- Dificultad
- 4/5
- Tiempo estimado
- 3-5 días
- Estado de actividad
- Activo
- Claridad
- Bastante claro
- Aptitud para principiantes
- 48/100