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
