python / python/cpython

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

Offen
#149,402 5 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

docs extension-modules interpreter-core topic-ctypes
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

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Ö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

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.