python / python/cpython

Update FileIO comments, documentation to match implementation

オープン
#129,011 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

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. リポジトリをフォークし、ブランチを切って変更します。
  4. 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 を短くまとめたダイジェスト。