How do you write a custom tarfile extraction filter on top of tarfile.data_filter?

## The contract PEP 706's `filter` argument is not limited to the three built-in names. It also accepts a callable, and the contract is small enough to recite: ``` filter(member: tarfile.TarInfo, dest_path: str) -> tarfile.TarInfo | None ``` It is called **once per member, before that member is extracted**, with the member's metadata and the destination directory. Three outcomes: * **Return a `TarInfo`** — extract it, using the returned object's attributes. It need not be the object you were handed. * **Return `None`** — skip this member silently and carry on with the rest of the archive. * **Raise** — abort. Raising a `tarfile.FilterError` subclass keeps you consistent with the built-in policies, but any exception propagates out of `extractall()`. That three-way outcome is the part candidates get wrong: returning `False` does not skip anything (a `TarInfo` is truthy, `False` is not a `TarInfo`), and `None` does not abort. ## Delegate, then decide A custom filter should almost never start from scratch. `tarfile.data_filter` encodes checks that took the core team a PEP and a security backport to get right: separator stripping, resolution of the target under the destination, absolute and escaping link targets, refusal of device and FIFO members, clearing of ownership, and mode normalisation. Call it first and build on what it returns: ```python def image_filter(member, dest): member = tarfile.data_filter(member, dest) # every standard check still runs if member.issym() or member.islnk(): return None # skip links data would have allowed if member.isreg() and member.size > MAX_MEMBER: raise ValueError(f"member too large: {member.name}") return member.replace(mode=0o600, deep=False) ``` Note what the delegation buys: `data_filter` already refused an absolute link target, so the `issym()` branch is tightening policy (this service wants no links at all, not even contained ones) rather than fixing a hole. ## Modify with `replace`, not by mutation `TarInfo.replace()`, added alongside the filters in 3.12, returns a copy with the named attributes changed — `name`, `mode`, `mtime`, `linkname`, `uid`, `gid`, `uname`, `gname` — and takes a `deep` keyword controlling whether nested structures are copied too. Prefer it to assigning attributes on the member you were given: the same `TarInfo` objects are reachable through `TarFile.getmembers()`, and mutating them makes the archive object disagree with what was extracted, which is a genuinely confusing thing to debug. Passing `deep=False` is the cheap path when you only touch scalar fields. ## Where the filter is attached Three places, in increasing scope: * `tar.extractall(dest, filter=image_filter)` — per call, and the clearest to read. * `tar.extraction_filter = image_filter` — per `TarFile` instance, useful when the extraction call is inside a helper you do not control. * `tarfile.TarFile.extraction_filter = staticmethod(image_filter)` — process-wide default. The `staticmethod` wrapper matters, because a bare function assigned to a class attribute would be bound as a method and receive the `TarFile` as its first argument. `shutil.unpack_archive()` also grew a keyword-only `filter` in 3.12 that it forwards to `tarfile`, so a helper built on it is not stuck with the default. ## What a filter can and cannot do It sees **metadata, not content**. There is no hook for "reject this member if its first bytes are not a valid image header" — that check belongs after extraction, on the file, in your scratch directory. It also runs per member with no state of its own, so a *total* budget across the archive needs a closure or a small callable object holding the running sum; and even then the filter only sees each member's declared size rather than bytes written. For tar that declared size is what extraction actually reads, so a per-member `member.size` check is a real bound — but the running total still has to be yours. Two smaller traps. Skipping a directory member does not skip its children; each member is filtered independently, and extraction will create missing parent directories with platform defaults. And a filter that raises leaves the destination partly populated, which is the same reason the built-in policies do: extract into a temporary directory and promote it only when the call returns normally. ## When not to write one A custom filter is worth reaching for when your policy is genuinely narrower than `data` and can be decided from metadata: this service accepts only regular files, only under a known prefix, only below a size, with no links of any kind. It is the wrong tool when the rule depends on content, on totals across the archive, or on anything the extractor cannot see. And it is worth asking whether the archive needs unpacking at all: reading members as streams through `TarFile.extractfile()` and never writing them to disk removes every path question at once, which is often the better answer for a service that only wants to look at what arrived.