Debian Codegraph @

PKG-INFO

raw ◀ ▶
1 Debian patch touch this file
1 Metadata-Version: 2.4
2 Name: backports.zstd
3 Version: 1.5.0
4 Summary: Backport of compression.zstd
5 Author-email: Rogdham <[email protected]>
6 License-Expression: PSF-2.0
7 Project-URL: Homepage, https://github.com/rogdham/backports.zstd
8 Project-URL: Source, https://github.com/rogdham/backports.zstd
9 Keywords: backport,backports,pep-784,zstd
10 Classifier: Development Status :: 5 - Production/Stable
11 Classifier: Intended Audience :: Developers
12 Classifier: Topic :: System :: Archiving :: Compression
13 Classifier: Programming Language :: Python
14 Classifier: Programming Language :: Python :: 3
15 Classifier: Programming Language :: Python :: 3 :: Only
16 Classifier: Programming Language :: Python :: 3.10
17 Classifier: Programming Language :: Python :: 3.11
18 Classifier: Programming Language :: Python :: 3.12
19 Classifier: Programming Language :: Python :: 3.13
•20 Requires-Python: >=3.10
21 Description-Content-Type: text/markdown
22 License-File: LICENSE.txt
23 License-File: LICENSE_zstd.txt
24 Dynamic: license-file
25
26 <div align="center" size="15px">
27
28 # backports.zstd
29
30 Backport of [PEP-784 “adding Zstandard to the standard library”][PEP-784]
31
32 [![GitHub build status](https://img.shields.io/github/actions/workflow/status/rogdham/backports.zstd/build.yml?branch=master)](https://github.com/rogdham/backports.zstd/actions?query=branch:master)
33 [![Release on PyPI](https://img.shields.io/pypi/v/backports.zstd)](https://pypi.org/project/backports.zstd/)
34
35 ---
36
37 [📖 PEP-784][PEP-784]&nbsp;&nbsp;&nbsp;|&nbsp;&nbsp;&nbsp;[📃 Changelog](./CHANGELOG.md)
38
39 [PEP-784]: https://peps.python.org/pep-0784/
40
41 </div>
42
43 ---
44
45 ## Install
46
47 Add the following dependency to your project:
48
49 ```
50 backports.zstd ; python_version<'3.14'
51 ```
52
53 …or just run `pip install backports.zstd`.
54
55 ## Usage
56
57 When importing a module needing Zstandard support, use a conditional import based on the
58 version of Python. See below for examples.
59
60 ### zstd
61
62 ```python
63 import sys
64
65 if sys.version_info >= (3, 14):
66 from compression import zstd
67 else:
68 from backports import zstd
69
70
71 # use the zstd module, for example:
72 zstd.compress(b"Hello, world!")
73 ```
74
75 Refer to the [official Python documentation][doc-zstd] for usage of the module.
76
77 [doc-zstd]: https://docs.python.org/3.14/library/compression.zstd.html
78
79 ### tarfile
80
81 ```python
82 import sys
83
84 if sys.version_info >= (3, 14):
85 import tarfile
86 else:
87 from backports.zstd import tarfile
88
89
90 # use the tarfile module, for example:
91 with tarfile.open("archive.tar.zst") as tar:
92 tar.list()
93 ```
94
95 This `tarfile` modules is backported from Python 3.14 and includes Zstandard-specific
96 features such as: explicit modes for opening files (e.g. `r:zstd`), specific arguments
97 (e.g. `zstd_dict`)… refer to the [official Python documentation][doc-tarfile] for more
98 info.
99
100 [doc-tarfile]: https://docs.python.org/3.14/library/tarfile.html
101
102 Moreover, the CLI is available as well: `python -m backports.zstd.tarfile`.
103
104 ### zipfile
105
106 ```python
107 import sys
108
109 if sys.version_info >= (3, 14):
110 import zipfile
111 else:
112 from backports.zstd import zipfile
113
114
115 # use the zipfile module, for example:
116 with zipfile.ZipFile("archive.zip", "w") as zf:
117 zf.writestr("hello.txt", "Hi!", zipfile.ZIP_ZSTANDARD)
118 ```
119
120 This `zipfile` modules is backported from Python 3.14 and includes Zstandard-specific
121 features such as the constant `ZIP_ZSTANDARD` to be used for `compress_type`… refer to
122 the [official Python documentation][doc-zipfile] for more info.
123
124 [doc-zipfile]: https://docs.python.org/3.14/library/zipfile.html
125
126 Moreover, the CLI is available as well: `python -m backports.zstd.zipfile`.
127
128 ### shutil
129
130 ```python
131 import shutil
132 import sys
133
134 if sys.version_info < (3, 14):
135 from backports.zstd import register_shutil
136 register_shutil()
137
138 # use the shutil module, for example
139 shutil.unpack_archive('archive.tar.zst')
140 ```
141
142 Calling the `register_shutil` function allows to create zstd'ed tar files using the
143 `"zstdtar"` format, as well as unpack them.
144
145 It also overrides support for unpacking zip files, enabling the unpacking of zip
146 archives that use Zstandard for compression.
147
148 Alternatively, call `register_shutil(tar=False)` or `register_shutil(zip=False)` to
149 choose which archiving support to register.
150
151 ## FAQ
152
153 ### Who are you?
154
155 This project is created and maintained by [Rogdham](https://github.com/rogdham)
156 (maintainer of [`pyzstd`](https://github.com/rogdham/pyzstd), who helped with [PEP-784]
157 and integration of Zstandard into the standard library), with help from
158 [Emma Smith](https://github.com/emmatyping) (author of [PEP-784], who did most of the
159 work of porting `pyzstd` into the standard library).
160
161 ### How is this backport constructed?
162
163 The aim is to be as close as possible to the upstream code of
164 [CPython](https://github.com/python/cpython).
165
166 The runtime code comes from CPython 3.14, with minor changes to support older versions
167 of Python. For PyPy users, the C code has been ported to CFFI.
168
169 During the build phase, the project uses [`zstd`](https://github.com/facebook/zstd)
170 (canonical implementation of Zstandard) as well as
171 [`pythoncapi-compat`](https://github.com/python/pythoncapi-compat) (which handles some
172 of the compatibility with older Python versions).
173
174 Tests come from CPython 3.14, with minor changes to support older versions of Python.
175 Additional tests have been written specifically for `backports.zstd`.
176
177 The type hints for the standard library have been contributed to
178 [`typeshed`](https://github.com/python/typeshed) and also backported to
179 `backports.zstd`.
180
181 ### Why can this library not be installed with Python 3.14?
182
183 This is [on purpose](https://github.com/Rogdham/backports.zstd/issues/50). For Python
184 3.14 and later, use the `compression.zstd` module from the standard library.
185
186 If you want your code to be compatible with multiple Python versions, condition the
187 usage of this library based on the Python version:
188
189 - [During install](#install);
190 - [When importing at runtime](#usage).
191
192 ### Can I use the libzstd version installed on my system?
193
194 The wheels distributed on PyPI include a static version of `libzstd` for ease of
195 installation and reproducibility.
196
197 If you want to use `libzstd` installed on your system, pass the `--system-zstd` argument
198 to the build backend. For example:
199
200 ```sh
201 python -m pip install --config-settings=--build-option=--system-zstd ...
202 python -m build --wheel --config-setting=--build-option=--system-zstd ...
203 ```
204
205 If you run the test suite, set the environment variable
206 `BACKPORTSZSTD_SKIP_EXTENSION_TEST=1` to skip tests that may fail when using the system
207 library.
208
209 ### I found a bug
210
211 If you encounter any issues, please open a
212 [GitHub issue](https://github.com/Rogdham/backports.zstd/issues/new) with a minimal
213 reproducible example.
214
215 We will check if the issue is with `backports.zstd` or CPython. We have already reported
216 and fixed a few issues in CPython this way!