登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  文章 >  python教程

Python tarfile.TarInfo.replace 怎样复制归档成员属性

来源:17golang原创

时间:2026-11-20 12:54:30 308浏览 收藏

TarInfo.replace() 返回一个新的归档成员属性对象,并替换指定的 name、mtime、mode 等字段;原对象的对应字段不变。默认使用深复制。它复制的是元数据,不会读取文件内容,也不会自动修改已经存在的 tar 文件。

官方文档:https://docs.python.org/3.14/library/tarfile.html#tarfile.TarInfo.replace

先区分成员元数据与文件内容

TarInfo 描述归档成员的名称、大小、权限、时间与所有者等信息。要给同一份内容生成另一套属性,直接改原对象会让后续代码也看到修改。replace 将“保留原属性”和“生成新属性”明确分开,更适合一个成员需要多种输出表示的场景。

例如一份说明文件原来叫 notes/source.txt,归档输出希望叫 docs/readme.txt,并使用统一时间和权限。这里需要改变的是成员元数据;文件内容仍是另一份输入。方法自 Python 3.12 提供,本文以 Python 3.14 接口为依据。

用 replace 选择性修改属性

import tarfile

# 构造成员属性,不读取或修改磁盘文件
original = tarfile.TarInfo("notes/source.txt")
original.size = 4
original.mtime = 1700000000
original.mode = 0o600

# 返回新对象,未指定的 size 等属性保留
updated = original.replace(
    name="docs/readme.txt",
    mtime=0,
    mode=0o644,
)
print(original.name, oct(original.mode), original.mtime)
print(updated.name, oct(updated.mode), updated.mtime)
print(original is updated, updated.size)

示例预期原对象仍是 notes/source.txt、权限 0o600、原来的时间戳;新对象是 docs/readme.txt、权限 0o644、时间戳 0。两个对象不是同一个对象,新对象仍保留 size 为 4。本文未运行代码,这些值供读者本地复现时比对。

支持选择性替换的公开参数包括 name、mtime、mode、linkname、uid、gid、uname、gname,均按关键字传入。不要把 size 当作 replace 的参数;需要调整内容大小时,应在新的 TarInfo 对象上设置与实际字节内容相符的 size。未指定字段与显式传入零不是一回事:mtime=0 正是一次有效替换。

图1:属性复制结构说明图。原属性与新属性分组展示,字段关联表示选择性替换及未指定属性的保留。
图1:属性复制结构说明图。原属性与新属性分组展示,字段关联表示选择性替换及未指定属性的保留。

图中“原 TarInfo”“原名称”“原大小”属于输入,“新 TarInfo”“新名称”“保留大小”属于副本。连线不表示归档文件已被改写。

深复制与浅复制怎样选择

import tarfile

original = tarfile.TarInfo("notes.txt")
original.pax_headers = {"comment": "source"}

# 默认深复制:新字典与原字典独立
independent = original.replace(name="independent.txt")
independent.pax_headers["comment"] = "independent"
print(original.pax_headers["comment"])

# 浅复制仍是新的 TarInfo,但内部字典共享
shared = original.replace(name="shared.txt", deep=False)
shared.pax_headers["comment"] = "shared"
print(original.pax_headers["comment"])
print(shared is original, shared.pax_headers is original.pax_headers)

第一次修改独立副本的 pax_headers,预期原字典中的 comment 仍为 source。第二次修改浅副本的同一个字典,预期原对象读取到 shared。最后一行预期分别为 False、True:TarInfo 是新对象,但 pax_headers 指向同一个字典。

所以 shallow 的关键是内部引用共享,不能简单理解为“所有修改都会同步”。对浅副本重新赋值 name 不会给原对象重新赋值;对共享字典进行原地修改才会影响另一方。默认深复制适合需要独立编辑元数据的情况,deep=False 适合已经明确接受共享关系的调用方。

图2:深浅复制结构说明图。独立字典与共享字典分别属于不同引用关系,不是运行结果截图。
图2:深浅复制结构说明图。独立字典与共享字典分别属于不同引用关系,不是运行结果截图。

图中的“原对象”“原字典”“深副本”“独立字典”“浅副本”“共享引用”解释引用结构:深副本关联独立字典,浅副本的共享引用关联原字典。

把修改后的属性交给归档写入

只有把新对象交给写入接口,才会创建使用新属性的归档成员。下面全部在内存里操作,内容长度由实际 payload 计算,不覆盖任何已有文件。

import io
import tarfile

payload = b"memo\n"
original = tarfile.TarInfo("notes/source.txt")
original.size = len(payload)
original.mode = 0o600

# 新属性对象和内容流分别提供给写入接口
updated = original.replace(name="docs/readme.txt", mode=0o644, mtime=0)
archive_buffer = io.BytesIO()
with tarfile.open(fileobj=archive_buffer, mode="w") as archive:
    with io.BytesIO(payload) as content:
        archive.addfile(updated, content)

# 仅在内存读取成员属性,不解压到磁盘
archive_buffer.seek(0)
with tarfile.open(fileobj=archive_buffer, mode="r:") as archive:
    member = archive.getmember("docs/readme.txt")
    print(member.name, member.size, oct(member.mode), member.mtime)

预期读取到 docs/readme.txt、大小 5、权限 0o644、时间戳 0。addfile 需要的成员描述与内容流分别提供,replace 不承担内容复制。with 负责关闭 TarFile 和内容流;归档缓冲区在重新读取前回到开头。

对于已有对象的 pax_headers,如果它包含 path、mtime 等与目标字段对应的扩展项,还应明确处理这些扩展值的一致性。replace 是复制后赋值,不会替调用方自动清理所有可能覆盖字段的 PAX 扩展。本文示例从全新对象开始,避免把已有扩展元数据混入属性演示。

实现参考:https://github.com/python/cpython/blob/3.14/Lib/tarfile.py

兼容性与常见问题

需求对应做法
替换名称、权限或时间使用 replace 的对应关键字
副本字典独立编辑保留默认 deep=True
接受内部对象共享明确选择 deep=False
生成新归档成员向 addfile 提供新元数据和内容流

replace 会改变原 tar 文件吗?

不会。它只返回新的 Python 元数据对象,持久化需要另行写入归档。

deep=False 是否返回原对象?

不是。返回的仍是副本,只是 pax_headers 等内部对象可以共享。

Python 3.11 可以直接使用吗?

这个方法自 3.12 提供。维护旧版本代码时应明确最低版本,或另行使用复制后赋值的兼容实现,不把两种接口混写。

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>