Clean up README slightly and document the xopen function parameters #139
Conversation
rhpvorderman
left a comment
rhpvorderman
left a comment
There was a problem hiding this comment.
Nice cleanup! I have a few small suggestions.
README.rst
Outdated
|
|
||
| * `python-isal <https://github.com/pycompression/python-isal>`_. | ||
| Supports multiple threads and compression levels up to 3. | ||
| * zlib-ng |
There was a problem hiding this comment.
* `python-zlib-ng <https://github.com/pycompression/python-zlib-ng>`_.
Supports multiple threads and compression levels up to 9.
There was a problem hiding this comment.
Whoops, I wrote this while our broadband was updated and had no internet access. I had intended meant to add the link later.
There was a problem hiding this comment.
BTW, if you make these comments on the 'Files changed' tab, then you can use the 'Suggestions' button and I can just click to accept them.
There was a problem hiding this comment.
Ah, that is good to know. Thanks!
| Supports multiple threads and compression levels up to 3. | ||
| * zlib-ng | ||
| * `pigz <https://zlib.net/pigz/>`_ (a parallel version of ``gzip``) | ||
|
|
There was a problem hiding this comment.
* `gzip <https://www.gnu.org/software/gzip/>`_.
README.rst
Outdated
| If multi-threaded compression or decompression is available, | ||
| this parameter can be used to override the number of threads | ||
| used. It is ignored otherwise. | ||
|
|
||
| Set threads to 0 to force opening the file without using a subprocess. | ||
| For some compression levels, | ||
| compressed files are by default read or written | ||
| using a pipe to a subprocess running an external tool such as | ||
| ``pbzip2`` or ``xz``. | ||
| With *threads* set to 0, a normal function call is used instead. |
There was a problem hiding this comment.
The above is not entirely correct as not always a subprocess is used. Below is my attempt at the paragraph. It is a hard thing to properly explain in a few short sentences so please do not take this as a literal suggestion:
Sets the number of threads spawned to open a compressed file. May be ignored if the backend does not support threads.
By default xopen tries to offload the (de)compression work load to other threads to free up the main Python thread for the application. This can either be done by using a subprocess to an external application or using a library that supports threads.
Set threads to 0 to force xopen to use only the main Python thread.
There was a problem hiding this comment.
I changed it to a variant of your suggestion. I agree it’s hard to explain. Maybe an extra section is needed in the documentation somewhere (later). As this paragraph is just the explanation of the parameter, I think it should be relatively short.
|
Looks good to me! |
No description provided.