This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Misc doc changes for tarfile
Type: Stage: resolved
Components: Documentation Versions: Python 3.5
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: eric.araujo Nosy List: eric.araujo, lars.gustaebel, python-dev, r.david.murray
Priority: normal Keywords: patch

Created on 2012-02-19 23:32 by eric.araujo, last changed 2022-04-11 14:57 by admin. This issue is now closed.

File name Uploaded Description Edit
misc-tarfile-doc-changes-3.2.diff eric.araujo, 2012-02-19 23:32
lars-comment.diff lars.gustaebel, 2012-02-22 09:31
misc-tarfile-doc-changes-3.2.diff eric.araujo, 2012-02-23 00:54
Messages (6)
msg153733 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-19 23:32
A few things to improve in tarfile’s doc:

a) I found the heading “The following variables are available on module level” strange; does “variable” mean that users are able to edit tarfile.ENCODING to control the default encoding used?  The answer is no, as ENCODING is bound to a function default argument value and a class attribute at import time.  I suggest changing this heading for something like “Module-level constants”, and move it before the doc for the *_FORMATS constants (the attached diff makes it look like I moved these constants, but I actually moved ENCODING—same result).

b) The doc does not say that the availability of compression formats depends on the optional compilation of some modules.  Someone following the link to the module docs for gzip, bz2 or lzma can find the info, but I think a bit more explicitness wouldn’t hurt.  The attached patch for 3.2 tries to inline the info, but is a bit clumsy; alternatively, a table like this could be added near the top:

   Support depends on the availability of certain optional modules:

   ========= =========================================== =============
   Format    Description                                 Requires
   ========= =========================================== =============
   ``xz``    xz'ed tar file (:file:`.tar.xz`)            :mod:`lzma`
   ``bz2``   bzip2'ed tar file (:file:`.tar.bz2`)        :mod:`bz2`
   ``gz``    gzip'ed tar file (:file:`.tar.gz`)          :mod:`gzip`
   ========= =========================================== =============

c) The seealso section links to zipfile, just like the into text, but not to shutil.

Please let me know what suggestions you approve or reject and I’ll commit them.
msg153942 - (view) Author: Lars Gustäbel (lars.gustaebel) * (Python committer) Date: 2012-02-22 09:31
a) Good point, a case of sloppy naming.

b) IMO a table is a tad too much. The amount of different compression methods is still quite small. My patch proposes a simpler approach.

c) A link to shutil is very useful.

BTW, thanks for the effort.
msg154025 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-02-23 00:54
I like your idea.  I’ll keep the table for shutil, which has more things to say (description, file extensions, etc.).
msg228413 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-10-04 00:19
New changeset a486b673b57f by R David Murray in branch '3.4':
#14056: Small improvements to the tarfile documentation.

New changeset ab828eeee2b2 by R David Murray in branch 'default':
Merge: #14056: Small improvements to the tarfile documentation.
msg228419 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2014-10-04 00:31
New changeset 378f3d237ac2 by R David Murray in branch '2.7':
#14056: Small improvements to the tarfile documentation.
msg228420 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-10-04 00:31
Committed Éric's patch.
Date User Action Args
2022-04-11 14:57:26adminsetgithub: 58264
2014-10-04 00:31:28r.david.murraysetstatus: open -> closed

versions: + Python 3.5, - Python 2.7, Python 3.2, Python 3.3
nosy: + r.david.murray

messages: + msg228420
resolution: fixed
stage: commit review -> resolved
2014-10-04 00:31:04python-devsetmessages: + msg228419
2014-10-04 00:19:22python-devsetnosy: + python-dev
messages: + msg228413
2012-02-23 00:54:19eric.araujosetfiles: + misc-tarfile-doc-changes-3.2.diff

messages: + msg154025
2012-02-22 09:31:30lars.gustaebelsetfiles: + lars-comment.diff

messages: + msg153942
2012-02-19 23:32:55eric.araujocreate