Commit0651936

authored

gh-67641: Clarify documentation on bytes vs text with non-seeking tarfile stream (GH-31610)

1 parentc66b577 commit0651936Copy full SHA for 0651936

File tree

+11

-8

lines changed

+11

-8

lines changed

Lines changed: 6 additions & 4 deletions

Original file line number	Diff line number	Diff line change
`@@ -116,10 +116,12 @@ Some facts and figures:`
`116`	`116`	``'filemode\|[compression]'``.:func:`tarfile.open` will return a:class:`TarFile`
`117`	`117`	`object that processes its data as a stream of blocks. No random seeking will`
`118`	`118`	`be done on the file. If given, fileobj may be any object that has a`
`119`		-:meth:`~io.TextIOBase.read` or:meth:`~io.TextIOBase.write` method (depending on the mode). bufsize
`120`		- specifies the blocksize and defaults to ``20 * 512`` bytes. Use this variant
`121`		- in combination with e.g. ``sys.stdin``, a socket:term:`file object` or a tape
`122`		- device. However, such a:class:`TarFile` object is limited in that it does
	`119`	+:meth:`~io.RawIOBase.read` or:meth:`~io.RawIOBase.write` method
	`120`	`+ (depending on the mode) that works with bytes.`
	`121`	+ bufsize specifies the blocksize and defaults to ``20 * 512`` bytes.
	`122`	+ Use this variant in combination with e.g. ``sys.stdin.buffer``, a socket
	`123`	+:term:`file object` or a tape device.
	`124`	+ However, such a:class:`TarFile` object is limited in that it does
`123`	`125`	not allow random access, see:ref:`tar-examples`. The currently
`124`	`126`	`possible modes:`
`125`	`127`

Lines changed: 5 additions & 4 deletions

Original file line number	Diff line number	Diff line change
`@@ -330,10 +330,11 @@ def write(self, s):`
`330`	`330`	`class_Stream:`
`331`	`331`	`"""Class that serves as an adapter between TarFile and`
`332`	`332`	`a stream-like object. The stream-like object only`
`333`		`- needs to have a read() or write() method and is accessed`
`334`		`- blockwise. Use of gzip or bzip2 compression is possible.`
`335`		`- A stream-like object could be for example: sys.stdin,`
`336`		`- sys.stdout, a socket, a tape device etc.`
	`333`	`+ needs to have a read() or write() method that works with bytes,`
	`334`	`+ and the method is accessed blockwise.`
	`335`	`+ Use of gzip or bzip2 compression is possible.`
	`336`	`+ A stream-like object could be for example: sys.stdin.buffer,`
	`337`	`+ sys.stdout.buffer, a socket, a tape device etc.`
`337`	`338`
`338`	`339`	`_Stream is intended to be used only internally.`
`339`	`340`	`"""`

Comments

(0)