python / python/cpython

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

未關閉
#149,402 5 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

還沒有人認領這個 Issue。

docs extension-modules interpreter-core topic-ctypes
主要語言
Python
星號
77.2k
分支
35.9k
PR 合併指標
PR 指標待擷取

描述

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

貢獻指南

開啟貢獻指南

從這裡開始

  1. 先讀完整個 Issue,再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫,在一個分支上完成修改。
  4. 送出 Pull Request,並在描述裡引用這個 Issue 編號。

研究方向

先從 memoryview、struct、array 和 ctypes 的文件章節開始,接著閱讀連結的討論,以及 SC 對 PEP 3118 預定術語的決定。使用 Lib/test/test_ctypes/test_pep3118.py 了解現有的 ctypes buffer protocol 行為。完成的標準是:memoryview 格式參照精確,且 ctypes 緩衝區支援已有文件說明。

由索引模型根據 Issue 內容生成。

評估

技術堆疊
python
領域
documentation
Issue 類型
文件
難度
4/5
預估耗時
3-5 天
活躍度
活躍
描述清晰度
基本清楚
新手友好度
48/100

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。