Meta issue: improve documentation for implementation of the PEP 3118 in Python
Open
Nobody has claimed this yet.
docs
extension-modules
interpreter-core
topic-ctypes
- Dominant language
- Python
- Stars
- 77.2k
- Forks
- 35.9k
- PR merge metrics
- PR metrics pending
Description
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
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the memoryview, struct, array, and ctypes documentation sections, then read the linked discussion and SC decision for the intended PEP 3118 terminology. Use Lib/test/test_ctypes/test_pep3118.py to understand the existing ctypes buffer-protocol behavior. Done means the memoryview format references are precise and ctypes buffer support is documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100