[New-bugs-announce] [issue32160] lzma documentation: example to XZ compress file on disk

[Daniel Himmelstein]

New submission from Daniel Himmelstein <daniel.himmelstein at gmail.com>:

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:

```sh
xz --compress --keep path
```

I believe this is possible in python with:

```python
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?

----------
components: IO
messages: 307163
nosy: dhimmel
priority: normal
severity: normal
status: open
title: lzma documentation: example to XZ compress file on disk
versions: Python 3.7, Python 3.8

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue32160>
_______________________________________