.. _howto-custom-file-storage:

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

:revision-up-to: 8961 (1.0)

.. 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()``
   メソッドを提供せねばなりません。

カスタムのストレージシステムでは、以下のストレージメソッドをオーバライドで
きます。メソッドの詳細は :ref:`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`` オブ
ジェクトです。このメソッドの戻り値はありません。

``get_valid_name(name)``
------------------------

背後にあるストレージシステムで扱うのに適したファイル名を生成して返します。
通常、このメソッドの ``name`` 引数は、サーバに送信されたもとのファイルパス
ら、パス部分を取り除いたファイルの名前です。標準の方法とは違うやりかたで安
全なファイル名への変換を行いたいなら、このメソッドをオーバライドしてくださ
い。

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

``get_available_name(name)``
----------------------------

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

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