delta/cpython-git.git/Doc/tutorial/inputoutput.rst, branch v3.8.5

Improve IO tutorial's "Old string formatting" section (GH-16251)

2020-05-28T01:41:31+00:00

* Use a more universal explanation of string interpolation rather than specifically referencing sprintf(), which depends on the reader having a C background.

Co-authored-by: Kyle Stanley 
(cherry picked from commit eaca2aa117d663acf8160a0b4543ee2c7006fcc7)

Co-authored-by: Adorilson Bezerra

bpo-37635: Update arg name for seek() in IO tutorial (GH-16147)

2019-09-14T20:47:31+00:00

Typically, the second positional argument for ``seek()`` is *whence*. That is the POSIX standard name (http://man7.org/linux/man-pages/man3/lseek.3p.html) and the name listed in the documentation for ``io`` module (https://docs.python.org/3/library/io.htmlGH-io.IOBase.seek).

The tutorial for IO is the only location where the second positional argument for ``seek()`` is referred to as *from_what*. I suspect this was created at an early point in Python's history, and was never updated (as this section predates the GitHub repository):

```
$ git grep "from_what"
Doc/tutorial/inputoutput.rst:To change the file object's position, use ``f.seek(offset, from_what)``.  The position is computed
Doc/tutorial/inputoutput.rst:the *from_what* argument.  A *from_what* value of 0 measures from the beginning
Doc/tutorial/inputoutput.rst:the reference point.  *from_what* can be omitted and defaults to 0, using the
```

For consistency, I am suggesting that the tutorial be updated to use the same argument name as the IO documentation and POSIX standard for ``seek()``, particularly since this is the only location where *from_what* is being used.

Note: In the POSIX standard, *whence* is technically the third positional argument, but the first argument *fildes* (file descriptor) is implicit in Python.

https://bugs.python.org/issue37635
(cherry picked from commit ff603f6c3d3dc0e9ea8c1c51ce907c4821f42c54)

Co-authored-by: Kyle Stanley

Correct info about "f.read(size)". (GH13852)

2019-09-10T16:00:09+00:00

In text mode, the "size" parameter indicates the number of characters, not bytes.
(cherry picked from commit faff81c05f838b0b7a64bbc8c53c02a9b04bb79d)

Co-authored-by: William Andrea

Clarify file-closing example in tutorial (GH-11652)

2019-04-17T12:18:37+00:00

bpo-35506: Remove redundant and incorrect links from keywords. (GH-11174)

2018-12-19T06:09:46+00:00

bpo-34712: Fix style in examples in "Input and Output" (GH-9361)

2018-09-19T10:28:28+00:00

A couple of fixes here to make this more PEP-8:

* Avoid multiple statements on one line with `;` statement separator -- this is very rare in Python and is "generally discouraged" in PEP 8 (and if used, per PEP 8 there shouldn't be a space before the `;`)
* Add output for the first "Formatted String Literals" example. (Side note: are the doctests for this being run? If so, why didn't it fail?)
* Avoid space before `!r`. I have generally not seen spaces before the `!`, and this also matches the style used in the docs here: https://docs.python.org/3/library/string.html#format-string-syntax



https://bugs.python.org/issue34712

Doc: Missing 'f' in an f-string. (GH-9074)

2018-09-07T09:31:47+00:00

Remove extra parentheses in output formatting tutorial (GH-8350)

2018-07-20T16:06:44+00:00

The parentheses were incorrect.

Fix documentation for input and output tutorial (GH-8231)

2018-07-11T00:11:34+00:00

The ValueError message ends with a period.

bpo-28626: rearrange discussion of output formatting to encourage f-strings (#6036)

2018-07-07T21:36:23+00:00

The 'output formatting' section of the tutorial talks a lot about manual formatting with things like .rjust() and .zfill(), with only a passing reference to 3.6's new f-strings.

This doesn't drop all of the old material, but it does rearrange the topics into a more modern order: f-strings first, discussing formatting specifiers a bit; then calling .format(); finally manual formatting with .ljust().