| 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 |
[](https://github.com/rogdham/backports.zstd/actions?query=branch:master) |
| 33 |
[](https://pypi.org/project/backports.zstd/) |
| 34 |
|
| 35 |
--- |
| 36 |
|
| 37 |
[📖 PEP-784][PEP-784] | [📃 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! |