filetype.py 徹底解説！Pythonでファイルタイプを簡単・高速に判定 🚀

はじめに: なぜファイルタイプ判定が必要なのか？

コンピュータで扱うファイルには、画像、動画、テキスト、実行ファイルなど、様々な種類があります。これらのファイルタイプを正確に識別することは、多くのアプリケーションにとって非常に重要です。例えば、以下のような場面で役立ちます。

• ユーザーがアップロードしたファイルが、意図した形式（例: 画像ファイルのみ許可）であるか検証する。
• ダウンロードしたファイルの種類に応じて、適切な処理（例: 画像ならリサイズ、アーカイブなら展開）を行う。
• ファイルの内容に基づいて、適切な拡張子を付与または修正する。
• セキュリティスキャンで、危険な可能性のあるファイルタイプ（例: 実行ファイル）を検出する。

ファイルタイプを判定する最も一般的な方法は、ファイル名の拡張子（例: .jpg, .pdf, .zip）を見ることです。しかし、拡張子は簡単に偽装されたり、欠落していたりすることがあります。そのため、拡張子だけに頼るのは信頼性が低い場合があります。

そこで登場するのが、ファイルの内容自体を解析して種類を特定する手法です。多くのファイル形式は、ファイルの先頭部分に「マジックナンバー」と呼ばれる特定のバイトシーケンスを持っています。このマジックナンバーを調べることで、拡張子に頼らずともファイルの種類を高い精度で推測できます。

今回ご紹介する filetype.py は、このマジックナンバーを利用してファイルタイプを判定するための、シンプルで軽量なPythonライブラリです。ピュアPythonで実装されており、外部ライブラリへの依存が少ないため、導入が非常に簡単です。✨

この記事では、filetype.py のインストール方法から基本的な使い方、対応フォーマット、そして他の類似ライブラリとの比較まで、詳しく解説していきます。

インストール方法

filetype.py のインストールは、Pythonのパッケージ管理ツールである pip を使って簡単に行えます。ターミナルまたはコマンドプロンプトで以下のコマンドを実行してください。

pip install filetype

特別な依存関係はほとんどなく、多くの環境ですぐに利用を開始できます。✅

# 仮想環境を作成 (例: venv)
python -m venv myenv

# 仮想環境をアクティベート
# Windows
myenv\Scripts\activate
# macOS/Linux
source myenv/bin/activate

# filetypeをインストール
pip install filetype

基本的な使い方

filetype.py の使い方は非常に直感的です。主にファイルパスを指定する方法と、ファイルのバイト列（バイナリデータ）を直接渡す方法があります。

1. ファイルパスから判定する

ローカルにあるファイルのパスを filetype.guess() 関数に渡すことで、ファイルの種類を判定できます。

import filetype

# 判定したいファイルのパスを指定
filepath = 'path/to/your/image.jpg' # 実際のファイルパスに置き換えてください

try:
    kind = filetype.guess(filepath)

    if kind is None:
        print(f'ファイルタイプを特定できませんでした: {filepath}')
    else:
        print(f'ファイルパス: {filepath}')
        print(f'  推測されたMIMEタイプ: {kind.mime}')
        print(f'  推測された拡張子: .{kind.extension}')

except FileNotFoundError:
    print(f'エラー: 指定されたファイルが見つかりません: {filepath}')
except Exception as e:
    print(f'エラーが発生しました: {e}')

filetype.guess() は、判定結果として FileType オブジェクトを返します。このオブジェクトには、推測されたMIMEタイプ (kind.mime) と拡張子 (kind.extension) が含まれています。ファイルタイプが特定できなかった場合や、サポートされていない形式の場合は None が返されます。

指定したファイルが存在しない場合は FileNotFoundError が発生するため、適切なエラーハンドリングを行うことが重要です。

2. バイト列 (bytes) から判定する

ファイルの内容をバイト列として既にメモリ上に持っている場合（例えば、ネットワークから受信したデータや、他の処理で生成されたデータなど）、そのバイト列を直接 filetype.guess() 関数に渡すことができます。この方が、ファイルI/Oを伴わないため高速に処理できる場合があります。

import filetype

# ファイルをバイナリモードで読み込む
filepath = 'path/to/your/document.pdf' # 実際のファイルパスに置き換えてください
file_bytes = b'' # 空のバイト列で初期化

try:
    with open(filepath, 'rb') as f:
        # ファイルの先頭部分だけ読み込んでも判定できることが多い
        # filetypeは効率的に必要なバイト数だけ読み込もうと試みますが、
        # 明示的にバイト列を渡す場合は、ある程度のサイズが必要です。
        # 一般的には先頭261バイトあれば多くの形式をカバーできます。
        file_bytes = f.read(261) # 例として先頭261バイト読み込み

except FileNotFoundError:
    print(f'エラー: 指定されたファイルが見つかりません: {filepath}')
    # 必要に応じて処理を中断するなどの対応
    exit()
except Exception as e:
    print(f'ファイルの読み込み中にエラーが発生しました: {e}')
    # 必要に応じて処理を中断するなどの対応
    exit()


if file_bytes: # バイト列が正常に読み込めた場合のみ判定
    kind = filetype.guess(file_bytes)

    if kind is None:
        print('バイト列からファイルタイプを特定できませんでした。')
    else:
        print(f'ファイル: {filepath} (バイト列から判定)')
        print(f'  推測されたMIMEタイプ: {kind.mime}')
        print(f'  推測された拡張子: .{kind.extension}')
else:
    print('判定対象のバイト列が空です。')

バイト列から判定する場合、ファイル全体を読み込む必要はありません。filetype.py はファイルの先頭部分にあるマジックナンバーを基に判定するため、通常はファイルの先頭数百バイト程度があれば十分です。公式ドキュメントによると、多くの一般的なフォーマットは先頭 261バイト 以内にマジックナンバーが含まれているため、この程度のバイト数を渡せば効率的に判定できます。

3. MIMEタイプまたは拡張子のみを取得する

MIMEタイプだけ、あるいは拡張子だけが必要な場合は、それぞれ専用の関数を使うこともできます。

import filetype

filepath = 'path/to/your/archive.zip' # 実際のファイルパス

try:
    # MIMEタイプのみを取得
    mime_type = filetype.guess_mime(filepath)
    if mime_type:
        print(f'MIMEタイプ: {mime_type}')
    else:
        print('MIMEタイプを特定できませんでした。')

    # 拡張子のみを取得
    extension = filetype.guess_extension(filepath)
    if extension:
        print(f'拡張子: .{extension}')
    else:
        print('拡張子を特定できませんでした。')

except FileNotFoundError:
    print(f'エラー: ファイルが見つかりません: {filepath}')
except Exception as e:
    print(f'エラーが発生しました: {e}')

これらの関数は、内部的には filetype.guess() を呼び出していますが、結果を特定の形式で返すため、コードが少し簡潔になる場合があります。特定できなかった場合は None を返します。

対応ファイルフォーマット

filetype.py は、幅広い種類のファイルフォーマットに対応しています。画像、動画、音声、アーカイブ、フォント、ドキュメントなど、一般的な形式の多くをカバーしています。

以下は、filetype.py が対応している主要なファイルフォーマットの例です（完全なリストではありません）。最新の対応状況は、ライブラリのソースコードやドキュメントを確認することをお勧めします。

このように、filetype.py は非常に多くの一般的なフォーマットに対応していることがわかります。ただし、世の中には無数のファイルフォーマットが存在するため、すべての形式に対応しているわけではありません。特定のニッチなフォーマットや新しいフォーマットについては、対応していない可能性があります。

高度な使い方・機能

1. 複数の候補を返す可能性 (guess() の挙動)

通常、filetype.guess() は最も可能性の高いファイルタイプを一つだけ返します。しかし、内部的には複数の「マッチャー」がファイルの内容をチェックし、条件に合致するものを探します。将来的には、複数の候補が返される可能性も考慮されているようですが、現在のバージョン (v1.2.0 時点) では、最初に見つかった最も確からしいタイプが返されるのが一般的です。

重要なのは、filetype.guess() が返す結果はあくまで「推測」であるという点です。100%の確実性が保証されるわけではありません。特に、意図的にマジックナンバーが偽装されている場合や、複数のファイルタイプが類似のマジックナンバーを持つ場合などは、誤判定の可能性もゼロではありません。⚠️

2. 未対応ファイル・判定不能の場合

filetype.guess(), guess_mime(), guess_extension() は、ファイルタイプを特定できなかった場合、一貫して None を返します。これは、以下のような場合に発生します。

• ファイルが空 (0バイト) または非常に小さい。
• ファイルの先頭部分に必要なマジックナンバーが含まれていない。
• filetype.py が対応していないファイルフォーマットである。
• ファイルが破損している。

したがって、これらの関数を使用する際は、必ず返り値が None でないかを確認する処理を入れる必要があります。

import filetype

filepath = 'path/to/unknown/or/empty/file'

kind = filetype.guess(filepath)

if kind:
    # ファイルタイプが特定できた場合の処理
    print(f"MIME: {kind.mime}, Extension: {kind.extension}")
else:
    # ファイルタイプが特定できなかった場合の処理
    print("ファイルタイプを特定できませんでした。デフォルトの処理を実行します。")
    # 例えば、拡張子から推測する、不明なファイルとして扱うなど
    import os
    _, ext = os.path.splitext(filepath)
    if ext:
        print(f"拡張子から推測: {ext}")
    else:
        print("拡張子もありません。")

3. カスタムタイプの追加 (Matcher)

filetype.py は、独自のファイルタイプ定義（マッチャー）を追加する機能も提供しています。これにより、ライブラリが標準でサポートしていないファイル形式や、特定のアプリケーション独自のファイル形式に対応させることが可能です。

カスタムマッチャーは、filetype.matchers.Matcher クラスを継承して作成します。最低限、判定ロジックを実装した match(buf) メソッドと、ファイルタイプ情報 (MIME、拡張子) を返すクラス変数を定義する必要があります。

import filetype
from filetype.matchers.matcher import Matcher

# 例: 特定のテキストシグネチャを持つカスタムファイルタイプ 'abc'
class AbcMatcher(Matcher):
    MIME = 'application/x-abc'
    EXTENSION = 'abc'

    def __init__(self):
        super().__init__(mime=AbcMatcher.MIME, extension=AbcMatcher.EXTENSION)

    def match(self, buf):
        # bufはファイルの先頭バイト列 (bytes)
        # ここでファイルタイプを判定するロジックを実装
        # 例: 先頭が b'ABC_FILE_SIGNATURE' で始まるかチェック
        return buf.startswith(b'ABC_FILE_SIGNATURE')

# 作成したカスタムマッチャーをfiletypeに追加
filetype.add_matcher(AbcMatcher())

# --- テスト用のダミーファイルを作成 ---
custom_file_content = b'ABC_FILE_SIGNATURE\nThis is a custom file.'
dummy_filepath = 'my_custom_file.abc'
with open(dummy_filepath, 'wb') as f:
    f.write(custom_file_content)
# ------------------------------------

# カスタムタイプを判定してみる
kind = filetype.guess(dummy_filepath)

if kind:
    print(f"カスタムファイル '{dummy_filepath}' の判定結果:")
    print(f"  MIME: {kind.mime}") # 出力: application/x-abc
    print(f"  Extension: {kind.extension}") # 出力: abc
else:
    print(f"カスタムファイル '{dummy_filepath}' を判定できませんでした。")

# --- 後片付け ---
import os
os.remove(dummy_filepath)
# ---------------

match(buf) メソッドは、引数としてファイルの先頭バイト列 buf を受け取ります。このバイト列を解析し、定義したカスタムファイルタイプに一致するかどうかを判定して True または False を返します。

作成したマッチャークラスのインスタンスを filetype.add_matcher() 関数で登録することで、以降の filetype.guess() などでこのカスタムタイプが認識されるようになります。

この機能により、特定のプロジェクトや業務に特化したファイルタイプ判定ロジックを簡単に追加でき、filetype.py の汎用性を高めることができます。👍

4. パフォーマンスについて

filetype.py はピュアPythonで実装されており、軽量であることが特徴です。ファイルパスを指定した場合、必要なバイト数だけを効率的に読み込むように設計されています。バイト列を直接渡す場合は、ファイルI/Oが発生しないため、さらに高速に動作する可能性があります。

しかし、非常に大量のファイルを高速に処理する必要がある場合や、対応フォーマットの網羅性が最優先される場合は、後述する python-magic のようなCライブラリベースのソリューションの方が適している可能性もあります。パフォーマンスは環境や対象ファイルによって異なるため、実際のユースケースでベンチマークを取ることが推奨されます。

filetype.py vs python-magic

Pythonでファイルタイプを判定するライブラリとして、filetype.py の他に有名なものに python-magic があります。python-magic は、多くのUnix系システムで標準的に使われている libmagic ライブラリのPythonラッパーです。

どちらのライブラリもマジックナンバーに基づいてファイルタイプを判定しますが、いくつかの重要な違いがあります。

どちらを選ぶべきか？ 🤔

• filetype.py が適しているケース:
  • 外部ライブラリへの依存を避けたい。
  • Windows環境など、libmagic のセットアップが面倒な場合。
  • 一般的なファイルフォーマットの判定で十分。
  • 導入の手軽さを重視したい。
  • カスタムタイプの追加機能を活用したい。
• python-magic が適しているケース:
  • 対応フォーマットの網羅性を最優先したい。
  • 非常に大量のファイルを可能な限り高速に処理したい。
  • libmagic のインストール・管理に抵抗がない、または既に環境が整っている。
  • Unix系システムでの利用がメイン。

結論として、多くの一般的なユースケースでは、filetype.py の手軽さと十分な機能性 が魅力となるでしょう。一方で、より専門的で広範なファイルタイプ判定や、極限のパフォーマンスが求められる場面では、python-magic が有力な選択肢となります。プロジェクトの要件や開発環境に合わせて、適切なライブラリを選択してください。

ユースケース例

filetype.py は、様々な場面で活用できます。具体的なユースケースをいくつかご紹介します。

1. ファイルアップロード機能の強化:

   Webアプリケーションなどでユーザーがファイルをアップロードする際に、拡張子だけでなくファイルの内容をチェックして、許可されたファイルタイプ（例: 画像のみ、PDFのみ）かどうかを検証します。これにより、不正なファイルや意図しない形式のファイルがアップロードされるのを防ぎます。

   import filetype
             import os
   
             ALLOWED_MIMES = {'image/jpeg', 'image/png', 'image/gif'}
   
             def is_allowed_file(file_path):
                 if not os.path.exists(file_path):
                     return False
                 kind = filetype.guess(file_path)
                 if kind is None:
                     # 特定できない場合は、例えば拡張子で判断するなどのフォールバックも可能
                     # ここでは単純に不許可とする
                     return False
                 print(f"Detected MIME type: {kind.mime}")
                 return kind.mime in ALLOWED_MIMES
   
             # --- テスト ---
             # uploaded_file = '/path/to/uploaded/image.jpg' # 実際のパスに置き換え
             # if is_allowed_file(uploaded_file):
             #     print("アップロードを許可します。")
             # else:
             #     print("許可されていないファイルタイプです。")
             

2. ダウンロードファイルの自動整理:

   インターネットからダウンロードしたファイルや、メールの添付ファイルなどを、ファイルタイプに応じて自動的にフォルダに振り分けるスクリプトを作成できます。

   import filetype
             import os
             import shutil
   
             DOWNLOAD_DIR = '/path/to/downloads' # ダウンロードフォルダ
             SORTED_DIR = '/path/to/sorted_files' # 整理先フォルダ
   
             # 整理先のフォルダ構造 (例)
             DEST_FOLDERS = {
                 'images': ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
                 'videos': ['video/mp4', 'video/quicktime', 'video/x-matroska'],
                 'audio': ['audio/mpeg', 'audio/ogg', 'audio/x-wav'],
                 'documents': ['application/pdf', 'application/msword', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'],
                 'archives': ['application/zip', 'application/vnd.rar', 'application/x-7z-compressed'],
                 'others': [] # 上記以外
             }
   
             # 整理先フォルダを作成 (存在しない場合)
             for folder_name in DEST_FOLDERS.keys():
                 os.makedirs(os.path.join(SORTED_DIR, folder_name), exist_ok=True)
   
             # ダウンロードフォルダ内のファイルを処理
             for filename in os.listdir(DOWNLOAD_DIR):
                 source_path = os.path.join(DOWNLOAD_DIR, filename)
                 if os.path.isfile(source_path): # ファイルのみを対象
                     kind = filetype.guess(source_path)
                     dest_folder_name = 'others' # デフォルト
   
                     if kind:
                         for name, mimes in DEST_FOLDERS.items():
                             if kind.mime in mimes:
                                 dest_folder_name = name
                                 break # 最初に見つかったカテゴリに移動
   
                     dest_path = os.path.join(SORTED_DIR, dest_folder_name, filename)
   
                     try:
                         print(f"Moving '{filename}' ({kind.mime if kind else 'Unknown'}) to '{dest_folder_name}' folder...")
                         shutil.move(source_path, dest_path)
                     except Exception as e:
                         print(f"Error moving file {filename}: {e}")
   
             print("ファイルの整理が完了しました。")
             

   注意: 上記の整理スクリプトは基本的な例です。実際に使用する場合は、エラーハンドリング、同名ファイルの処理、ログ記録などをより堅牢にする必要があります。また、大量のファイルを移動する際は、十分なテストを行ってください。
3. データ処理パイプライン:

   様々なソースから集めたファイルを処理するパイプラインにおいて、ファイルタイプに応じて適切な処理モジュールに振り分けるために利用します。例えば、画像ファイルなら画像処理ライブラリへ、テキストファイルなら自然言語処理ライブラリへ渡す、といった制御が可能になります。

4. ファイル拡張子の検証・修正:

   ファイル名に付与されている拡張子が、実際の内容と一致しているかを確認し、もし異なっていれば正しい拡張子に修正する、といったツールを作成できます。

   import filetype
             import os
   
             def check_and_suggest_extension(filepath):
                 if not os.path.isfile(filepath):
                     print(f"ファイルが存在しません: {filepath}")
                     return
   
                 _, current_extension = os.path.splitext(filepath)
                 current_extension = current_extension.lower().lstrip('.') # ドットを除去し小文字に
   
                 kind = filetype.guess(filepath)
   
                 if kind:
                     suggested_extension = kind.extension
                     print(f"ファイル: {filepath}")
                     print(f"  現在の拡張子: .{current_extension}")
                     print(f"  内容から推測される拡張子: .{suggested_extension}")
                     if current_extension != suggested_extension:
                         print(f"  ⚠️ 拡張子が内容と一致しない可能性があります！ -> .{suggested_extension} への変更を推奨")
                     else:
                         print(f"  ✅ 拡張子は内容と一致しています。")
                 else:
                     print(f"ファイル: {filepath}")
                     print(f"  現在の拡張子: .{current_extension}")
                     print(f"  内容からファイルタイプを特定できませんでした。")
   
             # --- テスト ---
             # test_file = 'path/to/some/file.maybe_wrong_ext'
             # check_and_suggest_extension(test_file)
             

まとめ

filetype.py は、Pythonでファイルの種類を判定するための、非常に便利で使いやすいライブラリです。主な特徴をまとめると以下のようになります。

• ✅ シンプル: filetype.guess() 関数を中心に、直感的なAPIを提供。
• ✅ 軽量: ピュアPython実装で、外部ライブラリへの依存が少ない。
• ✅ 導入が容易: pip install filetype だけで簡単にインストール可能。
• ✅ 幅広い対応フォーマット: 画像、動画、音声、アーカイブなど、一般的な形式を多数サポート。
• ✅ 拡張性: カスタムマッチャーを追加して、独自のファイルタイプに対応可能。
• ✅ 柔軟性: ファイルパスだけでなく、バイト列からも判定可能。

拡張子に頼らず、ファイルの内容に基づいて種類を特定できるため、より信頼性の高いファイル処理が実現できます。ファイルアップロードの検証、ダウンロードファイルの整理、データ処理パイプラインの制御など、その応用範囲は広いです。

依存関係の少なさや導入の手軽さから、多くのプロジェクトで第一候補となりうるライブラリです。Pythonでファイルタイプ判定が必要になった際には、ぜひ filetype.py の利用を検討してみてください。きっと開発の助けになるはずです！ 😊