Meta issue: improve documentation for implementation of the PEP 3118 in Python
Dieses Issue hat noch niemand übernommen.
- Vorherrschende Sprache
- Python
- Sterne
- 77.2k
- Forks
- 35.9k
- PR-Merge-Kennzahlen
- PR-Kennzahlen ausstehend
Beschreibung
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
Beitragsleitfaden
Erste Schritte
- Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
- Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
- Forke das Repository und arbeite in einem Branch.
- Öffne einen Pull Request, der die Issue-Nummer nennt.
Rechercherichtung
Beginne mit den Dokumentationsabschnitten zu memoryview, struct, array und ctypes, lies anschließend die verknüpfte Diskussion und die SC-Entscheidung zur vorgesehenen Terminologie von PEP 3118. Verwende Lib/test/test_ctypes/test_pep3118.py, um das bestehende Verhalten von ctypes beim buffer protocol zu verstehen. Erledigt ist die Aufgabe, wenn die Verweise auf memoryview-Formate präzise sind und die ctypes-Pufferunterstützung dokumentiert ist.
Vom Indexierungsmodell aus dem Issue-Text verfasst.
Bewertung
- Tech-Stack
- python
- Bereich
- documentation
- Issue-Typ
- Dokumentation
- Schwierigkeit
- 4/5
- Geschätzter Aufwand
- 3-5 Tage
- Aktivitätsstatus
- Aktiv
- Klarheit
- Größtenteils klar
- Anfängerfreundlichkeit
- 48/100