カスタムのストレージシステムを作成する
=======================================

:revision-up-to: 17812 (1.4)

.. currentmodule:: django.core.files.storage

ファイルを遠隔のシステム上に保存したい場合など、カスタムのファイルストレー
ジを作成したいときには、カスタムストレージクラスを定義します。カスタムスト
レージは、以下のステップに従って作成します:

#. ストレージシステムは ``django.core.files.storage.Storage`` のサブクラス
   として実装します:: 

        from django.core.files.storage import Storage

        class MyStorage(Storage):
            ...

#. Django はストレージシステムを引数なしでインスタンス化します。従って、
   ストレージシステムに関する設定は、全て ``django.conf.settings`` から取り
   出します::

        from django.conf import settings
        from django.core.files.storage import Storage

        class MyStorage(Storage):
            def __init__(self, option=None):
                if not option:
                    option = settings.CUSTOM_STORAGE_OPTIONS
                ...

#. ストレージクラスは、 ``_open()`` および ``_save()`` メソッドを実装せねば
   なりません。また、実現したいストレージクラスによってはその他にも適切なメ
   ソッドを実装せねばなりません。これらのメソッドについては下記を参照してく
   ださい。

   さらに、ローカルのファイルを扱うストレージを提供する場合は、 ``path()``
   メソッドを提供せねばなりません。

カスタムのストレージシステムでは、以下のストレージメソッドをオーバライドで
きます。メソッドの詳細は :doc:`/ref/files/storage` で解説していますが、少な
くとも以下のメソッドは **実装せねばなりません** :

* :meth:`Storage.delete`
* :meth:`Storage.exists`
* :meth:`Storage.listdir`
* :meth:`Storage.size`
* :meth:`Storage.url`

また、ストレージオブジェクトの自作用に用意されている以下のフックをよく使う
ことでしょう:

``_open(name, mode='rb')``
~~~~~~~~~~~~~~~~~~~~~~~~~~

**必須のメソッドです**.

``Storage.open()`` によって呼び出されます。このメソッドには、ストレージク
ラスがファイルをオープンするときの実際のメカニズムを実装します。このメソッ
ドは ``File`` クラスのオブジェクトを返さねばなりません。たいていのケースで
は、バックエンドストレージに固有のロジックを備えた ``File`` のサブクラスを
返すことでしょう。

``_save(name, content)``
~~~~~~~~~~~~~~~~~~~~~~~~

``Storage.save()`` から呼び出されます。 ``name`` は ``get_valid_name()``
や ``get_available_name()`` で処理済の名前で、 ``content`` は ``File`` オブ
ジェクトです。

実際に保存されたファイルの名前を返さねばなりません (ファイル名は通常
``name`` と同じになるはずですが、ストレージシステムの都合でファイル名を変更
せねばならないときには、変更後の新しい名前を返してください)。

``get_valid_name(name)``
~~~~~~~~~~~~~~~~~~~~~~~~

背後にあるストレージシステムで扱うのに適したファイル名を生成して返します。
このメソッドに渡す ``name`` 引数は、サーバに送信されたもとのファイルパスか
ら、パス部分を取り除いたファイルの名前です。標準に従わないファイル名を安全
な形式に変換す仕組みをカスタマイズしたければ、このメソッドをオーバライドし
てください。

``Storage`` の実装では、ファイル名から英数文字、ピリオド、アンダースコアを
除く全ての文字を取り去ります。

``get_available_name(name)``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

``name`` に指定された名前をもとに、ストレージ機構で扱えるファイル名を構築し
て返します。通常、 ``name`` 引数は、上で述べた ``get_valid_name()`` メソッ
ドによって、ストレージシステムで扱うのに適した名前に変換済みです。

``Storage`` の実装では、対象ディレクトリ下でファイル名が重複しそうな場合、
一意になるまで ``"_1"``, ``"_2"`` などを付加したファイル名を作成して返しま
す。