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 摘要。