tarfile --- tar アーカイブファイルの読み書き¶
ソースコード: Lib/tarfile.py
tarfile モジュールは、gzip、bz2、および lzma 圧縮されたものを含む、tar アーカイブを読み書きできます。.zip ファイルの読み書きには zipfile モジュールか、あるいは shutil の高水準関数を使用してください。
いくつかの事実と形態:
POSIX.1-1988 (ustar) フォーマットの読み書きをサポートしています。
longname および longlink 拡張を含む GNU tar フォーマットの読み書きをサポートしています。スパースファイルの復元を含む sparse 拡張は読み込みのみサポートしています。
POSIX.1-2001 (pax) フォーマットの読み書きをサポートしています。
ディレクトリ、一般ファイル、ハードリンク、シンボリックリンク、fifo、キャラクターデバイスおよびブロックデバイスを処理します。また、タイムスタンプ、アクセス許可や所有者のようなファイル情報の取得および保存が可能です。
バージョン 3.3 で変更: lzma 圧縮をサポートしました。
-
tarfile.open(name=None, mode='r', fileobj=None, bufsize=10240, **kwargs)¶ パス名 name の
TarFileオブジェクトを返します。TarFileオブジェクトと、利用できるキーワード引数に関する詳細な情報については、TarFile オブジェクト 節を参照してください。mode は
'filemode[:compression]'の形式をとる文字列でなければなりません。デフォルトの値は'r'です。以下に mode のとりうる組み合わせすべてを示します:mode
action
'r' または 'r:*'圧縮方法に関して透過的に、読み込み用にオープンします (推奨)。
'r:'非圧縮で読み込み用に排他的にオープンします。
'r:gz'gzip 圧縮で読み込み用にオープンします。
'r:bz2'bzip2 圧縮で読み込み用にオープンします。
'r:xz'lzma 圧縮で読み込み用にオープンします。
'x'or'x:'圧縮せずに tarfile を排他的に作成します。tarfile が既存の場合
FileExistsError例外を送出します。'x:gz'gzip 圧縮で tarfile を作成します。tarfile が既存の場合
FileExistsError例外を送出します。'x:bz2'bzip2 圧縮で tarfile を作成します。tarfile が既存の場合
FileExistsError例外を送出します。'x:xz'lzma 圧縮で tarfile を作成します。tarfile が既存の場合
FileExistsError例外を送出します。'a' または 'a:'非圧縮で追記用にオープンします。ファイルが存在しない場合は新たに作成されます。
'w' または 'w:'非圧縮で書き込み用にオープンします。
'w:gz'gzip 圧縮で書き込み用にオープンします。
'w:bz2'bzip2 圧縮で書き込み用にオープンします。
'w:xz'lzma 圧縮で書き込み用にオープンします。
'a:gz'、'a:bz2'、'a:xz'は利用できないことに注意して下さい。もし mode が、ある (圧縮した) ファイルを読み込み用にオープンするのに適していないなら、ReadErrorが送出されます。これを防ぐには mode'r'を使って下さい。もし圧縮方式がサポートされていなければ、CompressionErrorが送出されます。もし fileobj が指定されていれば、それは name でバイナリモードでオープンされた ファイルオブジェクト の代替として使うことができます。そのファイルオブジェクトの位置が 0 であることを前提に動作します。
'w:gz'、'r:gz'、'w:bz2'、'r:bz2','x:gz','x:bz2'モードの場合、tarfile.open()はファイルの圧縮レベルを指定するキーワード引数 compresslevel (デフォルトは9) を受け付けます。特別な目的のために、mode には 2 番目の形式:
'ファイルモード|[圧縮]'があります。この形式を使うと、tarfile.open()が返すのは、データをブロックからなるストリームとして扱うTarFileオブジェクトになります。この場合、ファイルに対してランダムなシークが行えなくなります。fileobj を指定する場合、read()およびwrite()メソッドを持つ (mode に依存した) 任意のオブジェクトにできます。bufsize にはブロックサイズを指定します。デフォルトは20 * 512バイトです。sys.stdin、ソケット file object、あるいはテープデバイスと組み合わせる場合にはこの形式を使ってください。ただし、このようなTarFileオブジェクトにはランダムアクセスを行えないという制限があります。使用例 節を参照してください。現在可能なモードは以下のとおりです。モード
動作
'r|*'tar ブロックの stream を圧縮方法に関して透過的に読み込み用にオープンします。
'r|'非圧縮 tar ブロックの stream を読み込み用にオープンします。
'r|gz'gzip 圧縮の stream を読み込み用にオープンします。
'r|bz2'bzip2 圧縮の stream を読み込み用にオープンします。
'r|xz'lzma 圧縮の stream を読み込み用にオープンします。
'w|'非圧縮の stream を書き込み用にオープンします。
'w|gz'gzip 圧縮の stream を書き込み用にオープンします。
'w|bz2'bzip2 圧縮の stream を書き込み用にオープンします。
'w|xz'lzma 圧縮の stream を書き込み用にオープンします。
バージョン 3.5 で変更:
'x'(排他的作成) モードが追加されました。バージョン 3.6 で変更: name パラメタが path-like object を受け付けるようになりました。
-
class
tarfile.TarFile¶ tar アーカイブを読み書きするためのクラスです。このクラスを直接使わないこと: 代わりに
tarfile.open()を使ってください。TarFile オブジェクト を参照してください。
tarfile モジュールは以下の例外を定義しています:
-
exception
tarfile.CompressionError¶ 圧縮方法がサポートされていないか、あるいはデータを正しくデコードできない時に送出されます。
-
exception
tarfile.ExtractError¶ TarFile.extract()を使った時に 致命的でない エラーに対して送出されます。ただしTarFile.errorlevel== 2の場合に限ります。
-
exception
tarfile.HeaderError¶ TarInfo.frombuf()メソッドが取得したバッファーが不正だったときに送出されます。
モジュールレベルで以下の定数が利用できます。
-
tarfile.ENCODING¶ 既定の文字エンコーディング。Windows では
'utf-8'、それ以外ではsys.getfilesystemencoding()の返り値です。
以下の各定数は、tarfile モジュールが作成できる tar アーカイブフォーマットを定義しています。詳細は、サポートしている tar フォーマット を参照してください。
-
tarfile.USTAR_FORMAT¶ POSIX.1-1988 (ustar) フォーマット。
-
tarfile.GNU_FORMAT¶ GNU tar フォーマット。
-
tarfile.PAX_FORMAT¶ POSIX.1-2001 (pax) フォーマット。
-
tarfile.DEFAULT_FORMAT¶ アーカイブを作成する際のデフォルトのフォーマット。現在は
GNU_FORMATです。
参考
zipfileモジュールzipfile標準モジュールのドキュメント。- アーカイブ化操作
shutilが提供するより高水準のアーカイブ機能についてのドキュメント。- GNU tar manual, Basic Tar Format
GNU tar 拡張機能を含む、tar アーカイブファイルのためのドキュメント。
TarFile オブジェクト¶
TarFile オブジェクトは、tar アーカイブへのインターフェースを提供します。tar アーカイブは一連のブロックです。アーカイブメンバー (保存されたファイル) は、ヘッダーブロックとそれに続くデータブロックで構成されています。一つの tar アーカイブにファイルを何回も保存することができます。各アーカイブメンバーは、TarInfo オブジェクトで確認できます。詳細については TarInfo オブジェクト を参照してください。
TarFile オブジェクトは with 文のコンテキストマネージャーとして利用できます。with ブロックが終了したときにオブジェクトはクローズされます。例外が発生した時、内部で利用されているファイルオブジェクトのみがクローズされ、書き込み用にオープンされたアーカイブのファイナライズは行われないことに注意してください。使用例 節のユースケースを参照してください。
バージョン 3.2 で追加: コンテキスト管理のプロトコルがサポートされました。
-
class
tarfile.TarFile(name=None, mode='r', fileobj=None, format=DEFAULT_FORMAT, tarinfo=TarInfo, dereference=False, ignore_zeros=False, encoding=ENCODING, errors='surrogateescape', pax_headers=None, debug=0, errorlevel=1) 以下のすべての引数はオプションで、インスタンス属性としてもアクセスできます。
name はアーカイブのパス名です。name は path-like object でも構いません。fileobj が渡された場合は省略可能です。その場合、ファイルオブジェクトに
name属性があれば、それを利用します。mode は、既存のアーカイブから読み込むための
'r'、既存のアーカイブに追記するための'a'、既存のファイルがあれば上書きして新しいファイルを作成する'w'、あるいは存在しない場合にのみ新しいファイルを作成する'x'のいずれかです。fileobj が与えられていれば、それを使ってデータを読み書きします。もしそれが決定できれば、mode は fileobj のモードで上書きされます。fileobj は位置 0 から利用されます。
注釈
TarFileをクローズした時、fileobj はクローズされません。format はアーカイブのフォーマットを制御します。モジュールレベルで定義されている、
USTAR_FORMAT、GNU_FORMAT、あるいはPAX_FORMATのいずれかである必要があります。tarinfo 引数を利用して、デフォルトの
TarInfoクラスを別のクラスで置き換えることができます。dereference が
Falseだった場合、シンボリックリンクやハードリンクがアーカイブに追加されます。Trueだった場合、リンクのターゲットとなるファイルの内容がアーカイブに追加されます。シンボリックリンクをサポートしていないシステムでは効果がありません。ignore_zeros が
Falseだった場合、空ブロックをアーカイブの終端として扱います。Trueだった場合、空の (無効な) ブロックをスキップして、可能な限り多くのメンバーを取得しようとします。このオプションは、連結されたり、壊れたアーカイブファイルを扱うときにのみ、意味があります。debug は
0(デバッグメッセージ無し) から3(全デバッグメッセージ) まで設定できます。このメッセージはsys.stderrに書き込まれます。errorlevel が
0の場合、TarFile.extract()使用時にすべてのエラーが無視されます。エラーが無視された場合でも、debug が有効であれば、エラーメッセージは出力されます。1の場合、すべての 致命的な(fatal) エラーはOSErrorを送出します。2の場合、すべての 致命的でない(non-fatal) エラーもTarError例外として送出されます。引数 encoding および errors にはアーカイブの読み書きやエラー文字列の変換に使用する文字エンコーディングを指定します。ほとんどのユーザーはデフォルト設定のままで動作します。詳細に関しては Unicode に関する問題 節を参照してください。
引数 pax_headers は、オプションの文字列辞書で、format が
PAX_FORMATだった場合に pax グローバルヘッダーに追加されます。バージョン 3.2 で変更: 引数 errors のデフォルトが
'surrogateescape'になりました。バージョン 3.5 で変更:
'x'(排他的作成) モードが追加されました。バージョン 3.6 で変更: name パラメタが path-like object を受け付けるようになりました。
-
classmethod
TarFile.open(...)¶ 代替コンストラクターです。モジュールレベルでの
tarfile.open()関数は、実際はこのクラスメソッドへのショートカットです。
-
TarFile.getmember(name)¶ メンバー name に対する
TarInfoオブジェクトを返します。name がアーカイブに見つからなければ、KeyErrorが送出されます。注釈
アーカイブ内にメンバーが複数ある場合は、最後に出現するものが最新のバージョンとみなされます。
-
TarFile.getnames()¶ メンバーをその名前のリストを返します。これは
getmembers()で返されるリストと同じ順番です。
-
TarFile.list(verbose=True, *, members=None)¶ 内容の一覧を
sys.stdoutに出力します。verbose がFalseの場合、メンバー名のみ表示します。Trueの場合、 ls -l に似た出力を生成します。オプションの members を与える場合、getmembers()が返すリストのサブセットである必要があります。バージョン 3.5 で変更: members 引数が追加されました。.
-
TarFile.next()¶ TarFileが読み込み用にオープンされている時、アーカイブの次のメンバーをTarInfoオブジェクトとして返します。もしそれ以上利用可能なものがなければ、Noneを返します。
-
TarFile.extractall(path=".", members=None, *, numeric_owner=False)¶ すべてのメンバーをアーカイブから現在の作業ディレクトリまたは path に抽出します。オプションの members が与えられるときには、
getmembers()で返されるリストの一部でなければなりません。所有者、変更時刻、アクセス権限のようなディレクトリ情報はすべてのメンバーが抽出された後にセットされます。これは二つの問題を回避するためです。一つはディレクトリの変更時刻はその中にファイルが作成されるたびにリセットされるということ、もう一つはディレクトリに書き込み許可がなければその中のファイル抽出は失敗してしまうということです。numeric_owner が
Trueの場合、tarfile の uid と gid 数値が抽出されたファイルのオーナー/グループを設定するために使用されます。False の場合、tarfile の名前付きの値が使用されます。警告
内容を信頼できない tar アーカイブを、事前の内部チェック前に展開してはいけません。ファイルが path の外側に作られる可能性があります。例えば、
"/"で始まる絶対パスのファイル名や、2 重ドット".."で始まるパスのファイル名です。バージョン 3.5 で変更: numeric_owner 引数が追加されました。
バージョン 3.6 で変更: path パラメタが path-like object を受け付けるようになりました。
-
TarFile.extract(member, path="", set_attrs=True, *, numeric_owner=False)¶ アーカイブからメンバーの完全な名前を使って、現在のディレクトリに展開します。ファイル情報はできる限り正確に展開されます。 member はファイル名もしくは
TarInfoオブジェクトです。 path を使って別のディレクトリを指定することもできます。 path は path-like object でも構いません。set_attrs が false でない限り、ファイルの属性 (所有者、最終更新時刻、モード) は設定されます。numeric_owner が
Trueの場合、tarfile の uid と gid 数値が抽出されたファイルのオーナー/グループを設定するために使用されます。False の場合、tarfile の名前付きの値が使用されます。注釈
extract()メソッドはいくつかの展開に関する問題を扱いません。ほとんどの場合、extractall()メソッドの利用を考慮するべきです。警告
extractall()の警告を参してください。バージョン 3.2 で変更: パラメーターに set_attrs を追加しました。
バージョン 3.5 で変更: numeric_owner 引数が追加されました。
バージョン 3.6 で変更: path パラメタが path-like object を受け付けるようになりました。
-
TarFile.extractfile(member)¶ アーカイブからメンバーをファイルオブジェクトとして抽出します。member はファイル名でも
TarInfoオブジェクトでも構いません。member が一般ファイルまたはリンクの場合、io.BufferedReaderオブジェクトが返されます。それ以外の場合、Noneが返されます。バージョン 3.3 で変更: 戻り値が
io.BufferedReaderオブジェクトになりました。
-
TarFile.add(name, arcname=None, recursive=True, *, filter=None)¶ ファイル name をアーカイブに追加します。 name は、任意のファイルタイプ (ディレクトリ、fifo、シンボリックリンク等)です。 arcname が与えられている場合は、それはアーカイブ内のファイルの代替名を指定します。 デフォルトではディレクトリは再帰的に追加されます。 これは、 recursive を
Falseに設定すると避けられます。 再帰処理はソートされた順序でエントリーを追加します。 filter が与えられた場合、それはTarInfoオブジェクトを引数として受け取り、操作したTarInfoオブジェクトを返す関数でなければなりません。 代わりにNoneを返した場合、TarInfoオブジェクトはアーカイブから除外されます。 使用例 にある例を参照してください。バージョン 3.2 で変更: filter パラメータが追加されました。
バージョン 3.7 で変更: 再帰処理はソートされた順序でエントリーを追加するようになりました。
-
TarFile.addfile(tarinfo, fileobj=None)¶ TarInfoオブジェクト tarinfo をアーカイブに追加します。fileobj を与える場合、binary file にしなければならず、tarinfo.sizeバイトがそれから読まれ、アーカイブに追加されます。TarInfoオブジェクトを直接作成するか、gettarinfo()を使って作成することができます。
-
TarFile.gettarinfo(name=None, arcname=None, fileobj=None)¶ os.stat()の結果か、既存のファイルに相当するものから、TarInfoオブジェクトを作成します。このファイルは、name で名付けられるか、ファイル記述子を持つ file object fileobj として指定されます。name は:term:path-like object でも構いません。 arcname が与えられた場合、アーカイブ内のファイルに対して代替名を指定します。与えられない場合、名前は fileobj のname属性 name 属性から取られます。名前はテキスト文字列にしてください。TarInfoの属性の一部は、addfile()を使用して追加する前に修正できます。ファイルオブジェクトが、ファイルの先頭にある通常のファイルオブジェクトでない場合、sizeなどの属性は修正が必要かもしれません。これは、GzipFileなどの属性に当てはまります。nameも修正できるかもしれず、この場合、arcname はダミーの文字列にすることができます。バージョン 3.6 で変更: name パラメタが path-like object を受け付けるようになりました。
-
TarFile.pax_headers¶ pax グローバルヘッダーに含まれる key-value ペアの辞書です。
TarInfo オブジェクト¶
TarInfo オブジェクトは TarFile の一つのメンバーを表します。ファイルに必要なすべての属性 (ファイルタイプ、ファイルサイズ、時刻、アクセス権限、所有者等のような) を保存する他に、そのタイプを決定するのに役に立ついくつかのメソッドを提供します。これにはファイルのデータそのものは 含まれません 。
TarInfo オブジェクトは TarFile のメソッド getmember()、 getmembers() および gettarinfo() によって返されます。
-
classmethod
TarInfo.frombuf(buf, encoding, errors)¶ TarInfoオブジェクトを文字列バッファー buf から作成して返します。バッファーが不正な場合
HeaderErrorを送出します。
-
classmethod
TarInfo.fromtarfile(tarfile)¶ TarFileオブジェクトの tarfile から、次のメンバーを読み込んで、それをTarInfoオブジェクトとして返します。
-
TarInfo.tobuf(format=DEFAULT_FORMAT, encoding=ENCODING, errors='surrogateescape')¶ TarInfoオブジェクトから文字列バッファーを作成します。引数についての情報は、TarFileクラスのコンストラクターを参照してください。バージョン 3.2 で変更: 引数 errors のデフォルトが
'surrogateescape'になりました。
TarInfo オブジェクトには以下のデータ属性があります:
-
TarInfo.name¶ アーカイブメンバーの名前。
-
TarInfo.size¶ バイト単位でのサイズ。
-
TarInfo.mtime¶ 最後に変更された時刻。
-
TarInfo.mode¶ 許可ビット。
-
TarInfo.type¶ ファイルタイプ。type は通常、定数
REGTYPE、AREGTYPE、LNKTYPE、SYMTYPE、DIRTYPE、FIFOTYPE、CONTTYPE、CHRTYPE、BLKTYPE、あるいはGNUTYPE_SPARSEのいずれかです。TarInfoオブジェクトのタイプをもっと簡単に解決するには、下記のis*()メソッドを使って下さい。
-
TarInfo.uid¶ ファイルメンバーを保存した元のユーザーのユーザー ID。
-
TarInfo.gid¶ ファイルメンバーを保存した元のユーザーのグループ ID。
-
TarInfo.uname¶ ファイルメンバーを保存した元のユーザーのユーザー名。
-
TarInfo.gname¶ ファイルメンバーを保存した元のユーザーのグループ名。
-
TarInfo.pax_headers¶ pax 拡張ヘッダーに関連付けられた、key-value ペアの辞書。
TarInfo オブジェクトは便利な照会用のメソッドもいくつか提供しています:
コマンドラインインターフェイス¶
バージョン 3.4 で追加.
tarfile モジュールは、 tar アーカイブを操作するための簡単なコマンドラインインターフェースを提供しています。
tar アーカイブを新規に作成したい場合、-c オプションの後にまとめたいファイル名のリストを指定してください:
$ python -m tarfile -c monty.tar spam.txt eggs.txt
ディレクトリを渡すこともできます:
$ python -m tarfile -c monty.tar life-of-brian_1979/
tar アーカイブをカレントディレクトリに展開したい場合、-e オプションを使用してください:
$ python -m tarfile -e monty.tar
ディレクトリ名を渡すことで tar アーカイブを別のディレクトリに取り出すこともできます:
$ python -m tarfile -e monty.tar other-dir/
tar アーカイブ内のファイル一覧を表示するには -l を使用してください:
$ python -m tarfile -l monty.tar
コマンドラインオプション¶
-
-c<tarfile> <source1> ... <sourceN>¶ -
--create<tarfile> <source1> ... <sourceN>¶ ソースファイルから tarfile を作成します。
-
-e<tarfile> [<output_dir>]¶ -
--extract<tarfile> [<output_dir>]¶ output_dir が指定されていない場合、カレントディレクトリに tarfile を展開します。
-
-v,--verbose¶ 詳細も出力します。
使用例¶
tar アーカイブから現在のディレクトリにすべて抽出する方法:
import tarfile
tar = tarfile.open("sample.tar.gz")
tar.extractall()
tar.close()
tar アーカイブの一部を、リストの代わりにジェネレーター関数を利用して TarFile.extractall() で展開する方法:
import os
import tarfile
def py_files(members):
for tarinfo in members:
if os.path.splitext(tarinfo.name)[1] == ".py":
yield tarinfo
tar = tarfile.open("sample.tar.gz")
tar.extractall(members=py_files(tar))
tar.close()
非圧縮 tar アーカイブをファイル名のリストから作成する方法:
import tarfile
tar = tarfile.open("sample.tar", "w")
for name in ["foo", "bar", "quux"]:
tar.add(name)
tar.close()
with 文を利用した同じ例:
import tarfile
with tarfile.open("sample.tar", "w") as tar:
for name in ["foo", "bar", "quux"]:
tar.add(name)
gzip 圧縮 tar アーカイブを作成してメンバー情報のいくつかを表示する方法:
import tarfile
tar = tarfile.open("sample.tar.gz", "r:gz")
for tarinfo in tar:
print(tarinfo.name, "is", tarinfo.size, "bytes in size and is ", end="")
if tarinfo.isreg():
print("a regular file.")
elif tarinfo.isdir():
print("a directory.")
else:
print("something else.")
tar.close()
TarFile.add() 関数の filter 引数を利用してユーザー情報をリセットしながらアーカイブを作成する方法:
import tarfile
def reset(tarinfo):
tarinfo.uid = tarinfo.gid = 0
tarinfo.uname = tarinfo.gname = "root"
return tarinfo
tar = tarfile.open("sample.tar.gz", "w:gz")
tar.add("foo", filter=reset)
tar.close()
サポートしている tar フォーマット¶
tarfile モジュールは 3 種類の tar フォーマットを作成することができます:
POSIX.1-1988 ustar format (
USTAR_FORMAT). ファイル名の長さは256文字までで、リンク名の長さは100文字までです。最大のファイルサイズは8GiBです。このフォーマットは古くて制限が多いですが、広くサポートされています。GNU tar format (
GNU_FORMAT). 長いファイル名とリンク名、8GiBを超えるファイルやスパース(sparse)ファイルをサポートしています。これは GNU/Linux システムにおいてデファクト・スタンダードになっています。tarfileモジュールは長いファイル名を完全にサポートしています。 スパースファイルは読み込みのみサポートしています。POSIX.1-2001 pax フォーマット (
PAX_FORMAT)。最も柔軟性があり、ほぼ制限が無いフォーマットです。長いファイル名やリンク名、大きいファイルをサポートし、パス名をポータブルな方法で保存します。しかし、現在のところ、すべての tar の実装が pax フォーマットを正しく扱えるわけではありません。pax フォーマットは既存の ustar フォーマットの拡張です。ustar では保存できない情報を追加のヘッダーを利用して保存します。pax には 2 種類のヘッダーがあります。1 つ目は拡張ヘッダーで、その次のファイルヘッダーに影響します。2 つ目はグローバルヘッダーで、アーカイブ全体に対して有効で、それ以降のすべてのファイルに影響します。すべての pax ヘッダーの内容は、ポータブル性のために UTF-8 で保存されます。
他にも、読み込みのみサポートしている tar フォーマットがいくつかあります:
ancient V7 フォーマット。これは Unix 7th Edition から存在する、最初の tar フォーマットです。通常のファイルとディレクトリのみ保存します。名前は 100 文字を超えてはならず、ユーザー/グループ名に関する情報は保存されません。いくつかのアーカイブは、フィールドが ASCII でない文字を含む場合に、ヘッダーのチェックサムの計算を誤ります。
SunOS tar 拡張フォーマット。POSIX.1-2001 pax フォーマットの亜流ですが、互換性がありません。
Unicode に関する問題¶
tar フォーマットは、もともとテープドライブにファイルシステムのバックアップをとる目的で設計されました。現在、tarアーカイブはファイルを配布する際に一般的に用いられ、ネットワーク上で交換されています。オリジナルフォーマットが抱える一つの問題は (他の多くのフォーマットでも同じですが)、様々な文字エンコーディングのサポートについて考慮していないことです。例えば、UTF-8 システム上で作成された通常の tar アーカイブは、非 ASCII 文字を含んでいた場合、Latin-1 システムでは正しく読み取ることができません。テキストのメタデータ (ファイル名、リンク名、ユーザー/グループ名など) は破壊されます。残念なことに、アーカイブのエンコーディングを自動検出する方法はありません。pax フォーマットはこの問題を解決するために設計されました。これは非 ASCII メタデータをユニバーサル文字エンコーディング UTF-8 を使用して格納します。
tarfile における文字変換処理の詳細は TarFile クラスのキーワード引数 encoding および errors によって制御されます。
encoding はアーカイブのメタデータに使用する文字エンコーディングを指定します。デフォルト値は sys.getfilesystemencoding() で、フォールバックとして 'ascii' が使用されます。アーカイブの読み書き時に、メタデータはそれぞれデコードまたはエンコードしなければなりません。encoding に適切な値が設定されていない場合、その変換は失敗することがあります。
引数 errors は文字を変換できない時の扱いを指定します。指定できる値は エラーハンドラ 節を参照してください。デフォルトのスキームは 'surrogateescape' で、Python はそのファイルシステムの呼び出しも使用します。ファイル名、コマンドライン引数、および環境変数 を参照してください。
PAX_FORMAT アーカイブの場合、メタデータはすべて UTF-8 で格納されるため、encoding は通常指定する必要はありません。encoding は、まれにある、バイナリの pax ヘッダーがデコードされた場合、あるいはサロゲート文字を含む文字列が格納されていた場合に使用されます。