lzma documentation: example to XZ compress file on disk

[dhimmel]

BPO	32160
Nosy	@dhimmel

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2017-11-28.20:41:15.049>
labels = ['3.8', 'type-feature', '3.7', 'expert-IO', 'docs']
title = 'lzma documentation: example to XZ compress file on disk'
updated_at = <Date 2017-11-28.20:50:25.989>
user = 'https://github.com/dhimmel'

bugs.python.org fields:

activity = <Date 2017-11-28.20:50:25.989>
actor = 'dhimmel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'IO']
creation = <Date 2017-11-28.20:41:15.049>
creator = 'dhimmel'
dependencies = []
files = []
hgrepos = []
issue_num = 32160
keywords = []
message_count = 2.0
messages = ['307163', '307166']
nosy_count = 2.0
nosy_names = ['docs@python', 'dhimmel']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue32160'
versions = ['Python 3.7', 'Python 3.8']

[dhimmel]

The documentation for the lzma module currently contains 6 examples (https://docs.python.org/3.6/library/lzma.html#examples). However, it does not include an example to XZ compress a file on disk. The functionality I'm envisioning would be similar to the command:

xz --compress --keep path

I believe this is possible in python with:

with open(in_path) as in_file, lzma.open(out_path, 'w') as out_file:
    shutil.copyfileobj(in_path, out_file)

Note gzip has a similar example (https://docs.python.org/3.6/library/gzip.html#examples-of-usage).

Compressing an existing file on disk is a use case I commonly encounter. Python is ideal for the task because it provides a cross-platform solution that doesn't require installing additional command line utilities. Before finding shutil.copyfileobj, I assumed memory-efficient on-disk XZ compression was not possible in Python, due to its omission from the docs.

I'm happy to propose example code for the documentation.

Alternatively, if this feature is considered useful, we could consider an API addition to provide a one-line command for on-disk compressing/decompressing files. Since this would be a major addition that should be consistent across compression modules, perhaps we should just start with a lzma doc example?

[dhimmel]

we could consider an API addition

Just brainstorming here... perhaps an API addition would be most appropriate in the shutil module (https://docs.python.org/3.6/library/shutil.html) which already contains shutil.make_archive and shutil.unpack_archive. One could imagine shutil.compress and shutil.decompress that took a format argument to specify the compression type.