django-staticfiles

Warning

このドキュメントは django-staticfiles の翻訳です。

これは静的ファイルを配信するためのヘルパーを提供するDjangoアプリケーションです。

ほとんどのDjango開発者は、ウェブアプリケーションにはリクエスト毎に新しくビューやテンプレートをレンダリングする動的な部分があって、それ以外にも、一つのウェブページの全て表示するためには画像、CSS、JavaScriptなどの静的なメディアファイルを扱う部分もあるということも考慮しなければいけません。

小さなプロジェクトでは、これは重要なことではない。なぜなら、Webサーバがメディアファイルの置いている場所を見つけることができるように置いておくだけだからです。しかしより大きなプロジェクト(特に複数のアプリケーションで構成される場合)では、個々のアプリケーションが複数の静的ファイルをまとめて使うと複雑になってきます。

静的ファイルとは何を指しているのでしょう? :

Djangoアプリケーションの個々の静的ファイルを一つの場所(他に指定した任意の場所)に集めることは本番環境で静的ファイルを配信することが容易になります。

django-staticfilesのメインのウェブサイトは github.com/jezdez/django-staticfiles で、チケットを作成することもできます。

Note

django-staticfilesはDjango 1.3から django.contrib.staticfiles としてDjangoの一部になりました。

django-staticfilesの0.3.Xは1.0のリリース後はセキュリティとデータがなくなるバグのバグフィックスしか行いません。 Django 1.2.X で 0.3.X 以下のバージョンを使っている場合は、django-staticfilesのバージョン1.0以上を使うかDjango 1.3のstaticfilesにアップグレードしてください。

django-staticfilesで先に新しい機能がリリースされるので、django-staticfilesを使いたい場合は、Django付属のstaticfilesアプリケーションの代わりにdjango-staticfilesを使うことができます。

インストール

  • PyPI から staticfiles をインストールするための好きなPythonのパッケージツールが使えます。例として

    pip install django-staticfiles
    

    pip install django-staticfiles==dev とすると、django-staticfilesの in-development version をインストールすることができます。

  • INSTALLED_APPS"staticfiles" を追加して下さい。

    INSTALLED_APPS = [
        # ...
        "staticfiles",
    ]
    
  • STATIC_URL に静的ファイルを配信させたいURLを設定して下さい。

    STATIC_URL = "/static/"
    
  • 開発モード(DEBUG = True の時)の時に、 runserver コマンドで静的ファイルを自動的に配信します。

    python manage.py runserver

  • サイトの全ての静的ファイルをデプロイする準備ができたら、 collectstatic 管理コマンドを使って下さい。

    python manage.py collectstatic
    

    デプロイするディレクトリ(STATIC_ROOT)に配信するための設定方法は、ウェブサーバーのドキュメントを見てください。

  • (オプション) Djangoのadminアプリケーションを使う場合は、 ADMIN_MEDIA_PREFIX の設定を STATIC_URL のサブパスに正しく設定して下さい。

    ADMIN_MEDIA_PREFIX = STATIC_URL + "admin/"
    

django.contrib.staticfiles との違い

Djangoの staticfiles では サポートしていない django-staticfiles の機能:

  • Django 1.2.X で動作します。
  • STATICFILES_EXCLUDED_APPS は、静的ファイルを探す時に、無視すべきものをドット区切りのアプリケーションのパスのシーケンスで指定します。
  • STATICFILES_IGNORE_PATTERNS は、 collectstatic を実行した時に無視するファイルやディレクトリのパターンを指定します。
  • 静的ファイルのファインダは、ほとんどのサードパーティのアプリケーションの静的ファイルの場所をサポートします。

より詳細な情報は 設定 を見てください。

Contents

管理コマンド

collectstatic

インストールしている全てのアプリケーションから静的ファイルを集めて STATICFILES_STORAGE にコピーします。

ファイル名の重複は、テンプレートが処理と同じような方法で解決するようにしています。ファイルは STATICFILES_DIRS に指定した場所や INSTALLED_APPS の設定で指定した順にアプリケーションの場所から最初に検索されます。

一般的に使用するオプションは次のとおりです:

--noinput

あらゆる種類の入力を求めるプロンプトを表示しない。

-i PATTERN or --ignore=PATTERN

glob-styleのパターンに一致したファイルやディレクトリは無視します。さらに無視するには何回も使用して下さい。

-n or --dry-run

ファイルシステムを変更する以外のすべてを実行することができます。

-l or --link

コピーの代わりに、それぞれのファイルへのシンボリックリンクを作成します。

--no-default-ignore

'CVS''.*''*~' のプライベートのglob-styleのパターンに無視しません。

-c or --clear

New in version 1.1.

コピーかオリジナルのファイルにリンクする前に既にあるファイル消去します。

--no-post-process

New in version 1.1.

設定済みの STATICFILES_STORAGE ストレージバックエンドの post_process() メソッドを実行しません。

オプションの全てのリストについては、collectstaticの管理コマンドでhelpを実行して確認して下さい。

$ python manage.py collectstatic --help

findstatic

有効化されているファインダーで一つ以上の相対パスを探索します。

$ python manage.py findstatic css/base.css admin/js/core.css
/home/special.polls.com/core/media/css/base.css
/home/polls.com/core/media/css/base.css
/home/polls.com/src/django/contrib/admin/media/js/core.js

デフォルトでは、一致するすべての場所が検索されます。``–first``オプションを使うと、それぞれの相対パスから最初に一致したものを返します。

$ python manage.py findstatic css/base.css --first
/home/special.polls.com/core/media/css/base.css

これはデバッグ用で、静的ファイルが指定されたパスから正しく集められたか表示します。

runserver

staticfiles アプリケーションが( INSTALLED_APPS に)インストールされている場合、Djangoの runserver コマンドが上書きされます。静的ファイルの自動的な配信機能と以下の新しいオプションが追加されました。

--nostatic

--nostatic オプションを使うと、staticfiles アプリケーションで静的ファイルの配信できないようにします。 このオプションはセッティングのプロジェクトの INSTALLED_APPS の設定で staticfiles がインストールされている時のみ使えます。

使用例

django-admin.py runserver --nostatic

--insecure

--insecure オプションを使うと、設定の DEBUGFalse にしていても staticfiles アプリケーションで静的ファイルを強制的に配信します。

Warning

これを使用することで、 非効率的セキュアではない ということを気に留めておいてください。

ローカル環境とセッティングの INSTALLED_APPSstaticfiles がインストールされている時のみを対象としているので、 本番の環境では使わないで下さい

使用例

django-admin.py runserver --insecure

ヘルパー関数

コンテキストプロセッサ-

static コンテキストプロセッサ
context_processors.static()

コンテキストプロセッサは {{ STATIC_URL }} に変数としてテンプレートに STATIC_URL を追加します。 それを使うためには、 TEMPLATE_CONTEXT_PROCESSORS の設定のどこかに 'staticfiles.context_processors.static' があるか確認して下さい。

RequestContext は任意のコンテキストプロセッサによって集められたデータにアクセスしてテンプレートをレンダリングすることしかしないことを覚えていて下さい。

テンプレートタグ

static
templatetags.staticfiles.static()

New in version 1.1.

相対パスを与えて、完全なURLを作成するために設定済みの STATICFILES_STORAGE ストレージを使います。例として

{% load staticfiles %}
<img src="{% static "css/base.css" %}" />

上の例は、 "css/base.css"STATICFILES_STORAGE のインスタンスの url メソッドを実行するのと同じことです。 ローカルではないストレージバックエンドから deploy files to a CDN に使う時は特に有効です。

get_static_prefix
templatetags.static.get_static_prefix()

RequestContext を使っていない場合、テンプレート内で STATIC_URL 、代わりに get_static_prefix テンプレートタグを使えます。

{% load static %}
<img src="{% get_static_prefix %}images/hi.jpg" />

複数回使う場合は、余分な処理を避けるために二つ目の方法も使えます。:

{% load static %}
{% get_static_prefix as STATIC_PREFIX %}

<img src="{{ STATIC_PREFIX }}images/hi.jpg" />
<img src="{{ STATIC_PREFIX }}images/hi2.jpg" />
get_media_prefix
templatetags.static.get_media_prefix()

get_static_prefix() と似ていますが、代わりに MEDIA_URL の設定が使えます。

ストレージ

StaticFilesStorage
class storage.StaticFilesStorage

FileSystemStorage クラスのサブクラスで、 STATIC_URL をベースのURLとして、 STATIC_ROOT の設定をファイルシステムのベースの場所として使われます。

post_process(paths, **options)

New in version 1.1.

このメソッドはコマンドラインオプションと同じように、 collectstatic 管理コマンドによって呼び出された後、見つかったファイルのパスが渡されて処理されます。

CachedStaticFilesStorage クラスは、背後でハッシュ化されたパスの置き換えとキャッシュを適切にアップデートします。

CachedStaticFilesStorage
class storage.CachedStaticFilesStorage

New in version 1.1.

StaticFilesStorage クラスのサブクラスはファイルの内容のMD5ハッシュをファイル名に付けて保存して、ファイルをキャッシュします。例えば、 css/styles.css ファイルは、 css/styles.55e7cbb9ba48.css として保存されます。

このストレージの目的は、あるページにおいて、サードパーティのプロキシサーバーによってキャッシュされた古いファイルを参照してファイルを配信し続けることです。さらに、訪問済みのページで読み込み時間をスピードアップするためにデプロイしたファイルに far future Expires headers を適用したい場合は、非常に便利です。

ストレージバックエンドは、(post_process() メソッドを使って)キャッシュされたコピーのパスで他の保存されているファイルにマッチしたファイルを探すパスを自動的に書き換えます。 正規表現を使うとこれらのパス Cascading Style Sheets の文 例えば、 'css/styles.css' ファイルです。

@import url("../admin/css/base.css");

CachedStaticFilesStorage ストレージバックエンドの url() メソッドを呼ぶことで、置き換えられます。

@import url("/static/admin/css/base.27e20196a850.css");

CachedStaticFilesStorage を有効化するために、以下を確認して下さい。 :

  • STATICFILES_STORAGE の設定は、 'staticfiles.storage.CachedStaticFilesStorage' に設定して下さい。
  • DEBUGFalse にして下さい。
  • staticfiles テンプレートで静的ファイルを参照するために static() というテンプレートタグを使います。
  • collectstatic 管理コマンドを使って全ての静的ファイル集めます。

MD5ハッシュを使ってサイトのパフォーマンスに負担がかかりますが、 staticfiles はDjangoのキャッシュフレームワークを使ってファイルのパスをキャッシュしようとします。もし、使っているストレージにキャッシュのオプションを上書きしたいなら、 ‘デフォルト’ のキャッシュバックエンドを使ってフォールバックします。

Static file development view
staticfiles.views.serve(request, path)

開発時に静的ファイルを配信するビュー関数です。

Warning

このビュー関数は DEBUGTrue になっている場合のみ有効になります。

なぜなら、このビュー関数は 非効率的セキュアではない からです。ローカルの開発環境でのみ使って、 本番環境では使わない で下さい。

このビュー関数は runserver (DEBUGTrue になっている場合)で自動的に有効化されます。別のローカルの開発サーバーでこのビュー関数を使う場合は、メインのURL設定の最後に次のようなスニペットを追加してください。

from django.conf import settings

if settings.DEBUG:
    urlpatterns += patterns('staticfiles.views',
        url(r'^static/(?P<path>.*)$', 'serve'),
    )

URLパターンの最初(r'^static/')は、 STATIC_URL で設定したものにして下さい。

URLパターン関数
staticfiles.urls.staticfiles_urlpatterns()

Warning

このヘルパー関数は、設定の DEBUGTrue の時と、 STATIC_URL が空ではなくて、 http://static.example.com/ のようにURLが指定されていない時に有効です。

URLパターンを設定することは面倒なので、あなたの代わりに設定してくれるヘルパー関数があります。

これは、既に定義したURKパターンのリストから静的ファイルを配信するための適切なURLパターンを返します。以下のように使います。

from staticfiles.urls import staticfiles_urlpatterns

# ... the rest of your URLconf here ...

urlpatterns += staticfiles_urlpatterns()

設定

STATIC_ROOT

Default:'' (空の文字列)

collectstatic を使うときに、静的コンテンツを置いているディレクトリへの絶対パスを指定します。

例: "/home/example.com/static/"

collectstatic の管理コマンドを使って、静的ファイルを集めた時、STATIC_URL_で指定したURLで配信されることになります。

これは collectstatic を使うのに 必須 です。STATICFILES_STORAGE_を上書きしない限り、独自のストレージバックエンドが使われます。

Warning

これはバージョン管理で静的ファイルをずっと置いておくための場所ではありません。STATICFILES_FINDERS_で見つけられたディレクトリでそうするべきです。(アプリケーション毎の 'static' サブディレクトリと、STATICFILES_DIRS_で設定したディレクトリがデフォルトで) この場所にあるファイルはSTATIC_ROOT_に集められます。

STATIC_URL_も確認して下さい。

STATIC_URL

Default:None

開発モード(DEBUG = True の時)で、 runserver を使った時に STATIC_ROOT から配信されたファイルを処理するためのURLを指定します。

Example: "/site_media/static/" or "http://static.example.com/"

値を空白にしない場合はスラッシュを最後にしなければいけません。

STATIC_ROOT_も確認して下さい。

STATICFILES_DIRS

Default:[]

この設定は FileSystemFinder ファインダが有効化されるか collectstaticfindstatic の管理コマンドを使うか、

これは、ファイルディレクトリのフルパスの文字列をリストかタプルとして設定してください。例として

STATICFILES_DIRS = (
    "/home/special.polls.com/polls/static",
    "/home/polls.com/polls/static",
    "/opt/webfiles/common",
)
プレフィックス(オプション)

新たな名前空間でファイルを置く場合、 (prefix, path) のようにタプルでプリフィックス指定してください。例として

STATICFILES_DIRS = (
    # ...
    ("downloads", "/opt/webfiles/stats"),
)

例:

STATIC_URL_に '/static/' と設定しているものとすると、 collectstatic 管理コマンドはSTATIC_ROOT_のサブディレクトリ 'downloads' にある静的ファイルを集めるでしょう。

テンプレートで '/static/downloads/polls_20101022.tar.gz' とすると、ローカルファイルの '/opt/webfiles/stats/polls_20101022.tar.gz' を参照するようになります。例として

<a href="{{ STATIC_URL }}downloads/polls_20101022.tar.gz">

STATICFILES_EXCLUDED_APPS

Default:[]

静的ファイルを探索する時に無視するアプリケーションのパスを順番に指定します。

STATICFILES_EXCLUDED_APPS = (
    'annoying.app',
    'old.company.app',
)

STATICFILES_STORAGE

Default:'staticfiles.storage.StaticFileStorage'

collectstatic 管理コマンドで静的ファイルを集めるときに使うファイルストレージエンジンです。

STATICFILES_FINDERS

Default:('staticfiles.finders.FileSystemFinder', 'staticfiles.finders.AppDirectoriesFinder')

様々な場所にある静的ファイルをどのように探索するかを処理するファインダバックエンドのリストです。

デフォルトでSTATICFILES_DIRS_で設定した場所(staticfiles.finders.FileSystemFinder を使って) と、個々のアプリケーション内の static サブディレクトリ内(staticfiles.finders.AppDirectoriesFinder を使って)に置かれているファイルを探します。

デフォルトで staticfiles.finders.DefaultStorageFinder は無効化されています。 STATICFILES_FINDERS_に設定を追加する場合、 DEFAULT_FILE_STORAGE の設定で指定されたデフォルトのファイルストレージ内の静的ファイルを探します。

Note

AppDirectoriesFinder ファインダを使う時は、staticfilesによって確実に見つけることができます。サイトの INSTALLED_APPS の設定にアプリケーションを追加するのは簡単です。

静的ファイルのファインダは現在非公開で、ドキュメント化されていません。

古い ‘media’ ディレクトリのファインダ(オプション)

staticfiles を使っていないDjangoプロジェクトのアップグレードの負担を軽減するために、オプションの staticfiles.finders.LegacyAppDirectoriesFinder ファインダーバックエンドは django-staticfiles の一部として追加されました。 STATICFILES_FINDERS に設定を追加した時に、 INSTALLED_APPS にあるアプリケーションの media を使うために staticfilesstaticfiles.finders.AppDirectoriesFinder と同じように有効にして下さい。

これは、サードパーティのアプリケーションが media の代わりに static ディレクトリを使うように切り替えられていない場合は特に有効です。 staticmedia の両方を使う場合、STATICFILES_FINDERS_に staticfiles.finders.AppDirectoriesFinder を入れるのも忘れないで下さい。

変更履歴

v1.2.1 (2012-02-16)

collectstatic 管理コマンドを実行した時に、一度にたくさんのファイルを開かないようにする変更を、Django trunkに反映させました。

v1.2 (2012-02-12)

collectstatic 管理コマンドを実行した時に、グローバルに無視するファイルを STATICFILES_IGNORE_PATTERNS に設定できるようにしました。

CachedFilesMixin をリファクタリングして、

CachedStaticFilesStorage にURLの一部をサポートする機能を追加しました。

インストールの時に問題があるので再びversiontools_を使うのを止めました。

v1.1.2 (2011-08-25)

  • django-appconf の使われ方の小さなバグをフィックスしました。

v1.1.1 (2011-08-22)

  • CachedStaticFilesStorage で相対パスの解決方法をフィックスしました。

v1.1 (2011-08-18)

  • Djangoの変更からpullしました。

    • STATICFILES_STORAGE ストレージバックエンドで保管したファイルを参照するための``static`` テンプレートタグを。 ストレージで url メソッドを使って、クラウドサービスからファイルを配信するような高度な機能を使う
    • CachedStaticFilesStorage は、ファイル( collectstatic 管理コマンドを実行した時に集めたファイル)をキャッシュする時にファイルの内容からMD5ハッシュを使ってファイル名を付けて保存します。
    • STATICFILES_STORAGE の代わりに staticfiles.storage.staticfiles_storage を追加しました。
    • 管理コマンドの --clear オプションはファイルを収集する前に、目的のディレクトリ(デフォルトでは STATIC_ROOT)を消去します。
    • serve ビューに含まれているディレクトリのインデックスを表示するのをやめました。
    • 静的ファイル用のURLパターンのヘルパー関数を使う時に、URLパターンにキーワード引数
  • 管理コマンドでDjangoの最新バージョンで導入されたself.stdoutではなく、sys.stdoutを使っています。
  • Refactored AppSettings helper class to be only a proxy for Django’s settings object instead of a singleton on its own.
  • サポートするDjangoのバージョンを1.2.X、1.3.X、1.4.Xに修正しました。
  • サポートするPythonのバージョンを2.5.X、2.6.X、2.7.Xに修正しました。

v1.0.1 (2011-03-28)

  • テスト時にエンコーディングに関する問題のバグをフィックスしました。
  • Django 1.3のtarballtox configuration to useをアップデートしました。
  • ドキュメントを少し追加しました。

v1.0 (2011-03-23)

Note

django-staticfiles は、Django contribのstaticfilesアプリケーションを移植したものです。 django-staticfiles < 1.0 からアップグレードする場合は何点か修正をしなければいけません。以下の修正点を見てください。

  • StaticFileStorageStaticFilesStorage に名前を変えました。
  • アプリケーションのファイルは個々のアプリケーションの static ディレクトリ( django-staticfiles の以前のバージョンでは media というディレクトリ名)に置いて下さい。
  • build_staticresolve_static の管理コマンドを、 collectstaticfindstatic に変えました。
  • STATICFILES_PREPEND_LABEL_APPSSTATICFILES_MEDIA_DIRNAMES の設定を削除しました。
  • STATICFILES_RESOLVERS の設定を削除して、新しく STATICFILES_FINDERS で設定するように変えました。
  • STATICFILES_STORAGE のデフォルト値を staticfiles.storage.StaticFileStorage から staticfiles.storage.StaticFilesStorage に変えました。
  • ローカルの開発環境で runserver (設定の DEBUGTrue に設定している)を使った場合、 開発時に静的ファイルを配信するURLをURLconfに追加する必要はない。

v0.3.4 (2010-12-25)

  • ドキュメントを少しアップデートしました。

v0.3.3 (2010-12-23)

Warning

django-staticfilesはDjango 1.3から django.contrib.staticfiles としてDjangoの一部になりました。

django-staticfilesの0.3.Xは1.0のリリース後はセキュリティとデータがなくなるバグのバグフィックスしか行いません。 Django 1.2.X で 0.3.X 以下のバージョンを使っている場合は、django-staticfilesのバージョン1.0以上を使うかDjango 1.3のstaticfilesにアップグレードしてください。

django-staticfilesで先に新しい機能がリリースされるので、django-staticfilesを使いたい場合は、Django付属のstaticfilesアプリケーションの代わりにdjango-staticfilesを使うことができます。

  • 目的のストレージで listdir メソッドが実装されていない場合に、 build_static 管理コマンドで、防げるようにフィックスしました。
  • build_static を実行したときにローカルではないストレージバックエンドでファイルの保管に失敗する問題をフィックスしました。

v0.3.2 (2010-08-27)

  • 簡単な変更をしました。

v0.3.1 (2010-08-21)

  • Sphinxのコンフィグファイルを追加して、READMEをいくつかのファイルに分割しました。

    ドキュメントは以下の場所にあります。 django-staticfiles.readthedocs.org

v0.3.0 (2010-08-18)

  • staticfilesがファイルを探すベースとなるAPIを追加しました。
  • トップレベルのurls.pyが煩雑になってきたので、URLpatternから全てのURLを探索するのを避けるために、staticfiles.urls.staticfiles_urlpatternsを追加しました。これは、Brian Rosnerからのフォークです。
  • ドキュメントを少し修正しました。
  • Django 1.1.X と 1.2.X で動作するテストをアップデートしました。
  • ストレージバックエンドを読み込む独自のコードを削除しました。

v0.2.0 (2009-11-25)

  • Django で使われている “media” (アップロード用)と “static” ファイルの用語において、紛らわしさを避けるために、管理コマンドのbuild_mediaとresolve_mediaをbuild_staticとresolve_mediaに変えました。
  • 管理コマンドからコア関数の内部処理のほとんどを書き直しました。
  • デフォルトでシステムストレージバックエンドのファイルを、カスタムストレージバックエンドで上書きできるようにしました。
  • 静的ファイルの処理する–interactiveオプションを削除しました。
  • 拡張テストを追加しました。
  • 標準のloggingを使うようにしました。

v0.1.2 (2009-09-02)

  • settings.pyのタイプミスをフィックスしました。
  • 名前空間が決まっていないアプリケーションのメディアファイルと同じ相対パスの他のファイルとの 間のbuild_media(今はbuild_static)内のコンフリクトをフィックスしました。

v0.1.1 (2009-09-02)

  • ドキュメントの一部として、READMEを追加しました。

v0.1.0 (2009-09-02)

  • Pinaxのソースからの最初のチェックイン。
  • STATIC_ROOT ディレクトリがない場合は作成します。