bpo-8840: Improve docstrings for truncate()#6011
Conversation
SylvainDe
left a comment
There was a problem hiding this comment.
Also, iI find truncate more explicit that re-size but I may be wrong on that.
|
|
||
| def truncate(self, size=None): | ||
| """Truncate the file to at most size bytes. | ||
| """Resize stream to at most 'pos' bytes. |
There was a problem hiding this comment.
This should be size, not pos.
|
Patch updated with suggested changes. |
| The position in the stream is left unchanged. The size | ||
| defaults to the current IO position as reported by tell(). If | ||
| the stream's size is increased, the contents of the new file | ||
| area are undetermined. Returns the new size. |
There was a problem hiding this comment.
The contents depend on the platform according to the main RST documentation.
IMO it is okay to leave out this level of detail from docstrings.
|
|
||
| def truncate(self, pos=None): | ||
| """Truncate file to size bytes. | ||
| """Resize stream to at most 'pos' bytes. |
There was a problem hiding this comment.
For most truncate methods, I don’t think the “at most” wording should be added. It should also be okay to remove it from FileIO.truncate. These methods are supposed to either resize to exactly the specified size, or raise an exception.
The odd one out is be BytesIO.truncate, which currently does not expand the size (https://bugs.python.org/issue27261).
|
@akuchling, any interest in trying to get this one wrapped up? Thanks! |
A patch that updates the docstrings for various truncate() methods in the io module.
https://bugs.python.org/issue8840