.. _ref-files-file:

``File`` オブジェクト
======================

:revision-up-to: 11321 (1.1)

.. currentmodule:: django.core.files

.. class:: File(file_object)

属性とメソッド
----------------

Django の ``File`` 型は、以下の属性とメソッドを備えています:

.. attribute:: File.name

    :setting:`MEDIA_ROOT` からの相対パスを含む、ファイルの名前です。

.. attribute:: File.path

    ローカルのファイルシステムにおけるファイルの絶対パスです。

    :ref:`カスタムのファイルストレージシステム <howto-custom-file-storage>`
    の場合、必ずしもローカルにファイルを保存しません。ローカルにファイルを
    保存しないシステムでは、 ``path`` は ``None`` です。

.. attribute:: File.url

    ファイルを取得できる URL です。 :ref:`templates <topics-templates>` で
    使う場合に便利です。例えば、ファイル :ref:`topics-files` の ``Car``
    の例で、車の写真を表示するテンプレートは以下のように書けます:
    
    .. code-block:: html+django

        <img src='{{ car.photo.url }}' alt='{{ car.name }}' />

.. attribute:: File.size

    バイト単位のファイルサイズです。

.. method:: File.open(mode=None)

    ファイルをオープンまたは再オープン (かつ ``File.seek(0)``) します。
    ``mode`` 引数には、 Python の標準の関数 ``open()`` と同じ引数を指定でき
    ます。

    ファイルを再オープンした場合、 ``mode`` は最初にオープンしたときのファ
    イルモードをオーバライドします。 ``None`` を指定すると、最初のモードと
    同じモードを使います。

.. method:: File.read(num_bytes=None)

    ファイルからコンテンツを読み出します。オプションの ``num_bytes``
    は読み出すデータの長さです。指定しなければ、末尾まで読み出します。

.. method:: File.__iter__()

    ファイルを一度に一行づつ繰り返して読み出します。

.. method:: File.chunks(chunk_size=None)

    ファイルを ``chunk_size`` に指定したサイズのチャンク ("chunk") づつ繰り
    返して読み出します。 ``chunk_size`` のデフォルトサイズは 64KB です。

    このメソッドは、ファイル全体をメモリに保存しなくても、ディスクからスト
    リーム読み出しできるので、巨大なファイルを読むときに便利です。

.. method:: File.multiple_chunks(chunk_size=None)

    ファイルが大きくて、長さ ``chunk_size`` のチャンクに分けて複数回アクセ
    スできる場合に ``True`` を返します。

.. method:: File.write(content)

    ``content`` に指定した文字列をファイルに書き込みます。背後にあるストレー
    ジシステムによっては、 ``close()`` を呼ぶまで ``content`` がコミットさ
    れない場合があります。

.. method:: File.close()

    ファイルを閉じます。

``ImageField`` 固有の属性
---------------------------

.. attribute:: File.width
    
    画像の幅です。

.. attribute:: File.height

    画像の高さです。

オブジェクトに結び付いているファイル特有のメソッド
----------------------------------------------------

.. highlight:: python

(``Car.photo`` のように) オブジェクトに結び付いてる :class:`File` には、
以下の二つのメソッドがあります:

.. method:: File.save(name, content, save=True)

    ファイル名 ``name`` とコンテンツ ``content`` を使って新たなファイルを生
    成し、保存します。このメソッドは既存のファイルを置き換えるのではなく、
    新たなファイルを作成して、オブジェクトがそのファイルを指すようにします。
    ``save`` を ``True`` にすると、ファイルが保存されたときに ``save()`` メ
    ソッドを呼び出します。すなわち、以下の 2 行::
    
        >>> car.photo.save('myphoto.jpg', contents, save=False)
        >>> car.save()
    
    は、以下の 1 行と同じです::
    
        >>> car.photo.save('myphoto.jpg', contents, save=True)
    
    ``content`` 引数は :class:`File` またはそのサブクラスのインスタンスでな
    ければなりません。

.. method:: File.delete(save=True)

    ファイルをモデルインスタンスから除去して、背後にあるファイルも削除しま
    す。 ``save`` 引数は上のメソッドと同じです。