Registry / serialization / backports-tarfile

backports-tarfile

library1.2.0pypypi✓ verified 25d ago

backports.tarfile provides a backport of the CPython standard library's `tarfile` module, allowing users on older Python versions (>=3.8) to access newer features and bug fixes related to tar archive handling. The current version is 1.2.0, released recently, with several updates in Spring 2024.

serialization

pip install backports-tarfile

github ↗package ↗

INSTALL

IMPORT

SIG · BACKPORTS-TARFILE

backports-tarfile

serializationpythonv1.2.0

Install

1.8s avg

Import

30ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.030s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.8s · import 0.030s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

tarfile

✓ from backports import tarfile

✗ import tarfile

Using `import tarfile` will only load the standard library's `tarfile` module. To access the backported features, you must import it from the `backports` namespace.

This example demonstrates how to create and extract a gzipped tar archive using the backported `tarfile` module. The API is identical to the standard library's `tarfile`.

import os from backports import tarfile # Create a dummy file with open('example.txt', 'w') as f: f.write('Hello, backported tarfile!') # Create a tar.gz archive with tarfile.open('example.tar.gz', 'w:gz') as tar: tar.add('example.txt') print('Archive created: example.tar.gz') # Extract the archive with tarfile.open('example.tar.gz', 'r:gz') as tar: tar.extractall(path='./extracted_archive') print('Archive extracted to ./extracted_archive') # Clean up os.remove('example.txt') os.remove('example.tar.gz') os.remove('./extracted_archive/example.txt') os.rmdir('./extracted_archive')

Debug

Known issues

gotchaImportError due to namespace package conflicts, particularly with `setuptools` versions (e.g., 71.0.0+). Users might encounter `ImportError: cannot import name 'tarfile' from 'backports'`.

fix

Ensure `backports-tarfile` is explicitly installed. Sometimes, temporarily downgrading `setuptools` or using conditional `pip install backports.tarfile` can resolve it.

affects: All versions, especially with specific `setuptools` and older Python combinations (e.g., Python 3.8).

gotchaSecurity Vulnerabilities in Backported `tarfile` Extraction Filtering (pre-Python 3.12). The backported tarfile extraction filtering feature, intended for security, was incomplete and could introduce new security issues if projects switched from custom inspection to relying solely on these filters.

fix

Exercise caution when using extraction filtering on older Python versions. Always refer to CVE records for the most up-to-date security information and consider additional validation.

affects: Python versions prior to 3.12, where `tarfile` extraction filtering was backported.

gotchaMisunderstanding its purpose: This library is a backport. If your Python version natively includes the `tarfile` features you need, you should use the standard library's `tarfile` directly, rather than the backport, to avoid unnecessary dependencies or potential conflicts.

fix

Only install and use `backports.tarfile` if your Python runtime explicitly lacks the `tarfile` features you require and the backport provides them (e.g., specific compression algorithms or filters only available in newer Python stdlib versions). Use conditional imports (e.g., `if sys.version_info < (3, 14): from backports.zstd import tarfile`) if targeting a range of Python versions.

affects: All versions, for users on Python versions that already include the desired `tarfile` features.

gotchaPython 3.14 will, by default, filter extracted tar archives and reject files or modify their metadata. This DeprecationWarning appears when `tarfile.extractall()` or `tar.extract()` is called without explicitly providing the `filter` argument.

fix

Explicitly use the `filter` argument (e.g., `filter='data'`, `filter='fully_trusted'`, or `filter='tar'`) when extracting tar archives to control this behavior and suppress the deprecation warning. This ensures forward compatibility and consistent behavior with Python 3.14 and later versions.

affects: Appears in Python 3.13+ when using `tarfile` extraction without specifying a `filter` argument, due to a breaking change in default behavior in Python 3.14+.

Errors

Common errors & fixes

ImportError: cannot import name 'tarfile' from 'backports'

This error often occurs due to conflicts with the `setuptools` library or issues with Python's namespace package handling, where an 'empty' `backports` package might be shadowing the intended `backports.tarfile` module, especially on Python versions where `setuptools` vendors parts of `backports`.

fix

Ensure `backports.tarfile` is explicitly installed and potentially try uninstalling and reinstalling it (`pip uninstall backports.tarfile && pip install backports.tarfile>=1.2.0`). If `setuptools` is involved, upgrading `setuptools` or ensuring its dependencies are correctly handled might resolve the conflict. Sometimes, removing a conflicting 'empty' `backports` namespace package (a directory containing only an `__init__.py` file) can also help.

ModuleNotFoundError: No module named 'backports'

This means the `backports` namespace package, which `backports.tarfile` resides under, is not installed or discoverable in your Python environment.

fix

Install the `backports.tarfile` package using pip: `pip install backports-tarfile`.

AttributeError: module 'tarfile' has no attribute 'data_filter'

This error arises when trying to use newer features of the `tarfile` module, such as `data_filter`, which were introduced in later Python versions (e.g., Python 3.12+), on an older Python environment where `backports.tarfile` is either not correctly replacing the standard library module or the Python version is too old to support even the backported feature.

fix

Ensure `backports.tarfile` is installed and that your code correctly imports and uses the backported module. If you're explicitly importing `tarfile` directly, ensure that the `backports.tarfile` is taking precedence or is directly imported (e.g., `import backports.tarfile as tarfile`). If the issue persists, verify your Python version meets the minimum requirements for the specific feature you are trying to backport, or consider upgrading your Python environment if the feature is not supported by `backports.tarfile` on your current version. If using `pip`, ensure it's up-to-date (`pip install --upgrade pip`).

Upgrade

Version history

1.2.0latest on PyPI · released May 28, 2024

Audit

Dependencies

pythonrequiredRuntime dependency, specifically for Python versions where `tarfile` features are not yet native.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/jaraco/backports.tarfile ↗

packagehttps://pypi.org/project/backports-tarfile/ ↗