Meta issue: improve documentation for implementation of the PEP 3118 in Python
Nessuno ha ancora preso questa issue.
- Lingua principale
- Python
- Stelle
- 77.2k
- Fork
- 35.9k
- Metriche di merge delle PR
- Metriche PR in attesa
Descrizione
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
Guida per i contributori
Apri la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Direzione di ricerca
Inizia con le sezioni della documentazione relative a memoryview, struct, array e ctypes, poi leggi la discussione collegata e la decisione dello SC sulla terminologia prevista di PEP 3118. Usa Lib/test/test_ctypes/test_pep3118.py per comprendere il comportamento esistente di ctypes con il buffer protocol. Il lavoro è completo quando i riferimenti ai formati di memoryview sono precisi e il supporto ai buffer di ctypes è documentato.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- python
- Ambito
- documentation
- Tipo di issue
- Documentazione
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Stato di attività
- Attiva
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 48/100