python / python/cpython

Update FileIO comments, documentation to match implementation

未关闭
#129,011 1 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

docs
主要语言
Python
星标
77.2k
派生
35.9k
PR 合并指标
PR 指标待抓取

描述

Documentation

Discuss thread: https://discuss.python.org/t/change-open-write-to-guarantee-all-bytes-will-be-written-or-an-exception-will-be-thrown/71082

  1. FileIO behaves differently than its code comments around read and readall. Update the code comments to match current behavior
    • PEP 475, reads are retried in some cases
    • .readall() makes multiple system calls by design
  2. Add documentation to open() builtin that buffering=0, which currently just says "disables buffering") changes how .write() behaves and may result in data loss as a result of a partial write (ex. gh-126606).
    • TextIO and BufferedIO (which are gotten via commonly used open('README.rst'), open('README.rst', 'rb')) retry partial writes providing a user a guarantee either all bytes will be written or an exception will be thrown.
    • FileIO is "Raw I/O" and by PEP-3116 design, as documented, and currently implemented does not retry partial writes.
    • Most the time, buffering=0 currently speeds up writing a file, but it can also result in corrupted files, ex. gh-126606 from using FileIO directly
    • I would like to try and change the behavior of buffering=0 to use BufferedIO but with a 0 sized buffer, and that is on my roadmap but will be a while (people use the flag for a reason / get benefit!). This will mean open() always returns an object which implements "Write all or throw exception" behavior.
    • Add warning / document existing behavior on open() in the meantime.
Linked PRs
  • gh-129012
  • gh-135328
  • gh-150957
  • gh-150958
  • gh-150959

贡献指南

打开贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

调研方向

首先检查 FileIO 代码注释以及 issue 中链接的 open() builtin 文档,然后检查链接的 PR:gh-129012、gh-135328、gh-150957、gh-150958 和 gh-150959。完成的标准是:注释描述当前的 read/readall 行为,并且 open() 文档清楚解释 buffering=0 以及部分写入时的数据丢失行为。

由索引模型根据 Issue 内容生成。

评估

技术栈
python
领域
documentation
Issue 类型
文档
难度
4/5
预计耗时
3-5 天
活跃度
停滞
描述清晰度
基本清楚
新手友好度
25/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。