1============= 2python-zstd 3============= 4 5.. image:: https://travis-ci.org/sergey-dryabzhinsky/python-zstd.svg?branch=master 6 :target: https://travis-ci.org/sergey-dryabzhinsky/python-zstd 7 8Simple python bindings to Yann Collet ZSTD compression library 9 10**Zstd**, short for Zstandard, is a new lossless compression algorithm, 11 which provides both good compression ratio *and* speed for your standard compression needs. 12 "Standard" translates into everyday situations which neither look for highest possible ratio 13 (which LZMA and ZPAQ cover) nor extreme speeds (which LZ4 covers). 14 15It is provided as a BSD-license package, hosted on GitHub_. 16 17.. _GitHub: https://github.com/facebook/zstd 18 19 20WARNING!!! 21---------- 22 23If you setup 1.0.0.99.1 version - remove it manualy to able to update. 24PIP matching version strings not tuple of numbers. 25 26Result generated by versions prior to 1.0.0.99.1 is not compatible with orignial Zstd 27by any means. It generates custom header and can be read only by zstd python module. 28 29As of 1.0.0.99.1 version it uses standard Zstd output, not modified. 30 31To prevent data loss there is two functions now: ```compress_old``` and ```decompress_old```. 32They are works just like in old versions prior to 1.0.0.99.1. 33 34As of 1.1.4 version module build without them by default. 35 36As of 1.3.4 version these functions are deprecated and will be removed in future releases. 37 38As of 1.5.0 version these functions are removed. 39 40 41DISCLAIMER 42__________ 43 44These python bindings are kept simple and blunt. 45 46Support of dictionaries and streaming is not planned. 47 48 49LINKS 50----- 51 52* Zstandard: https://github.com/facebook/zstd 53* More full-featured and compatible with Zstandard python bindings by Gregory Szorc: https://github.com/indygreg/python-zstandard 54 55 56Build from source 57----------------- 58 59 >>> $ git clone https://github.com/sergey-dryabzhinsky/python-zstd 60 >>> $ git submodule update --init 61 >>> $ apt-get install python-dev python3-dev python-setuptools python3-setuptools 62 >>> $ python setup.py build_ext clean 63 >>> $ python3 setup.py build_ext clean 64 65Note: legacy format support disabled by default. 66To build with Zstd legacy versions support - pass ``--legacy`` option to setup.py script: 67 68 >>> $ python setup.py build_ext --legacy clean 69 70Note: PyZstd legacy format support disabled by default. 71To build with python-zstd legacy format support (pre 1.1.2) - pass ``--pyzstd-legacy`` option to setup.py script: 72 73 >>> $ python setup.py build_ext --pyzstd-legacy clean 74 75If you want to build with existing distribution of libzstd just add ``--external`` option. 76But beware! Legacy formats support is unknown in this case. 77And if your version not equal with python-zstd - tests may not pass. 78 79 >>> $ python setup.py build_ext --external clean 80 81If paths to header file ``zstd.h`` and libraries is uncommon - use common ``build`` params: 82--libraries --include-dirs --library-dirs. 83 84 >>> $ python setup.py build_ext --external --include-dirs /opt/zstd/usr/include --libraries zstd --library-dirs /opt/zstd/lib clean 85 86 87Install from pypi 88----------------- 89 90 >>> # for Python 2.7+ 91 >>> $ pip install zstd 92 >>> # or for Python 3.4+ 93 >>> $ pip3 install zstd 94 95 96API 97___ 98 99Error 100 Standard python Exception for zstd module 101 102ZSTD_compress (data[, level, threads]): string|bytes 103 Function, compress input data block via mutliple threads, return compressed block, or raises Error. 104 105 Params: 106 107 * **data**: string|bytes - input data block, length limited by 2Gb by Python API 108 * **level**: int - compression level, ultra-fast levels from -100 (ultra) to -1 (fast) available since zstd-1.3.4, and from 1 (fast) to 22 (slowest), 0 or unset - means default (3). Default - 3. 109 * **threads**: int - how many threads to use, from 0 to 200, 0 or unset - auto-tune by cpu cores count. Default - 0. Since: 1.4.4.1 110 111 Aliases: *compress(...)*, *dumps(...)* 112 113 Since: 0.1 114 115ZSTD_uncompress (data): string|bytes 116 Function, decompress input compressed data block, return decompressed block, or raises Error. 117 118 Params: 119 120 * **data**: string|bytes - input compressed data block, length limited by 2Gb by Python API 121 122 Aliases: *decompress(...)*, *uncompress(...)*, *loads(...)* 123 124 Since: 0.1 125 126version (): string|bytes 127 Returns this module doted version string. 128 129 Since: 1.3.4.3 130 131ZSTD_version (): string|bytes 132 Returns ZSTD library doted version string. 133 134 Since: 1.3.4.3 135 136ZSTD_version_number (): int 137 Returns ZSTD library version in format: MAJOR*100*100 + MINOR*100 + RELEASE. 138 139 Since: 1.3.4.3 140 141ZSTD_external (): int 142 Returns 0 of 1 if ZSTD library build as external. 143 144 Since: 1.5.0.2 145 146 147Removed 148_______ 149 150ZSTD_compress_old (data[, level]): string|bytes 151 Function, compress input data block, return compressed block, or raises Error. 152 153 **DEPRECATED**: Returns not compatible with ZSTD block header 154 155 **REMOVED**: since 1.5.0 156 157 Params: 158 159 * **data**: string|bytes - input data block, length limited by 2Gb by Python API 160 * **level**: int - compression level, ultra-fast levels from -5 (ultra) to -1 (fast) available since zstd-1.3.4, and from 1 (fast) to 22 (slowest), 0 or unset - means default (3). Default - 3. 161 162 Since: 1.0.0.99.1 163 164ZSTD_uncompress_old (data): string|bytes 165 Function, decompress input compressed data block, return decompressed block, or raises Error. 166 167 **DEPRECATED**: Accepts data with not compatible with ZSTD block header 168 169 **REMOVED**: since 1.5.0 170 171 Params: 172 173 * **data**: string|bytes - input compressed data block, length limited by 2Gb by Python API 174 175 Since: 1.0.0.99.1 176 177Use 178___ 179 180Module has simple API: 181 182 >>> import zstd 183 >>> dir(zstd) 184 ['Error', 'ZSTD_compress', 'ZSTD_external', 'ZSTD_uncompress', 'ZSTD_version', 'ZSTD_version_number', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__', 'compress', 'decompress', 'dumps', 'loads', 'uncompress', 'version'] 185 >>> zstd.version() 186 '1.5.0.4' 187 >>> zstd.ZSTD_version() 188 '1.5.0' 189 >>> zstd.ZSTD_version_number() 190 10500 191 >>> zstd.ZSTD_external() 192 0 193 194In python2 195 196 >>> data = "123456qwert" 197 198In python3 use bytes 199 200 >>> data = b"123456qwert" 201 202 203 >>> cdata = zstd.compress(data, 1) 204 >>> data == zstd.decompress(cdata) 205 True 206 >>> cdata_mt = zstd.compress(data, 1, 4) 207 >>> cdata == cdata_mt 208 True 209 >>> data == zstd.decompress(cdata_mt) 210 True 211