Ticket #17935: 0001-cleaning-media-and-static-files-docs-urls.patch
| File 0001-cleaning-media-and-static-files-docs-urls.patch, 67.1 KB (added by , 12 years ago) |
|---|
-
deleted file docs/howto/static-files.txt
From 4966dae988a921034d31c1b856078f96eba7373d Mon Sep 17 00:00:00 2001 From: Adrien Lemaire <lemaire.adrien@gmail.com> Date: Wed, 28 Mar 2012 10:30:39 +0900 Subject: [PATCH] cleaning media and static files docs urls --- docs/howto/static-files.txt | 510 -------------------------------------- docs/index.txt | 4 +- docs/misc/api-stability.txt | 2 +- docs/ref/contrib/staticfiles.txt | 2 +- docs/ref/django-admin.txt | 6 +- docs/ref/models/fields.txt | 6 +- docs/ref/request-response.txt | 2 +- docs/ref/settings.txt | 14 +- docs/releases/1.0-alpha-2.txt | 2 +- docs/releases/1.0.txt | 2 +- docs/releases/1.3-alpha-1.txt | 2 +- docs/releases/1.3-beta-1.txt | 2 +- docs/releases/1.3.txt | 2 +- docs/releases/1.4-alpha-1.txt | 2 +- docs/releases/1.4-beta-1.txt | 2 +- docs/releases/1.4.txt | 2 +- docs/topics/files.txt | 151 ----------- docs/topics/files/media.txt | 153 ++++++++++++ docs/topics/files/static.txt | 510 ++++++++++++++++++++++++++++++++++++++ docs/topics/testing.txt | 2 +- 20 files changed, 690 insertions(+), 688 deletions(-) delete mode 100644 docs/howto/static-files.txt delete mode 100644 docs/topics/files.txt create mode 100644 docs/topics/files/media.txt create mode 100644 docs/topics/files/static.txt diff --git a/docs/howto/static-files.txt b/docs/howto/static-files.txt deleted file mode 100644 index e3a40a1..0000000
+ - 1 =====================2 Managing static files3 =====================4 5 .. versionadded:: 1.36 7 Django developers mostly concern themselves with the dynamic parts of web8 applications -- the views and templates that render anew for each request. But9 web applications have other parts: the static files (images, CSS,10 Javascript, etc.) that are needed to render a complete web page.11 12 For small projects, this isn't a big deal, because you can just keep the13 static files somewhere your web server can find it. However, in bigger14 projects -- especially those comprised of multiple apps -- dealing with the15 multiple sets of static files provided by each application starts to get16 tricky.17 18 That's what ``django.contrib.staticfiles`` is for: it collects static files19 from each of your applications (and any other places you specify) into a20 single location that can easily be served in production.21 22 .. note::23 24 If you've used the `django-staticfiles`_ third-party app before, then25 ``django.contrib.staticfiles`` will look very familiar. That's because26 they're essentially the same code: ``django.contrib.staticfiles`` started27 its life as `django-staticfiles`_ and was merged into Django 1.3.28 29 If you're upgrading from ``django-staticfiles``, please see `Upgrading from30 django-staticfiles`_, below, for a few minor changes you'll need to make.31 32 .. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/33 34 Using ``django.contrib.staticfiles``35 ====================================36 37 Basic usage38 -----------39 40 1. Put your static files somewhere that ``staticfiles`` will find them.41 42 By default, this means within ``static/`` subdirectories of apps in your43 :setting:`INSTALLED_APPS`.44 45 Your project will probably also have static assets that aren't tied to a46 particular app. The :setting:`STATICFILES_DIRS` setting is a tuple of47 filesystem directories to check when loading static files. It's a search48 path that is by default empty. See the :setting:`STATICFILES_DIRS` docs49 how to extend this list of additional paths.50 51 Additionally, see the documentation for the :setting:`STATICFILES_FINDERS`52 setting for details on how ``staticfiles`` finds your files.53 54 2. Make sure that ``django.contrib.staticfiles`` is included in your55 :setting:`INSTALLED_APPS`.56 57 For :ref:`local development<staticfiles-development>`, if you are using58 :ref:`runserver<staticfiles-runserver>` or adding59 :ref:`staticfiles_urlpatterns<staticfiles-development>` to your60 URLconf, you're done with the setup -- your static files will61 automatically be served at the default (for62 :djadmin:`newly created<startproject>` projects) :setting:`STATIC_URL`63 of ``/static/``.64 65 3. You'll probably need to refer to these files in your templates. The66 easiest method is to use the included context processor which allows67 template code like:68 69 .. code-block:: html+django70 71 <img src="{{ STATIC_URL }}images/hi.jpg" />72 73 See :ref:`staticfiles-in-templates` for more details, **including** an74 alternate method using a template tag.75 76 Deploying static files in a nutshell77 ------------------------------------78 79 When you're ready to move out of local development and deploy your project:80 81 1. Set the :setting:`STATIC_URL` setting to the public URL for your static82 files (in most cases, the default value of ``/static/`` is just fine).83 84 2. Set the :setting:`STATIC_ROOT` setting to point to the filesystem path85 you'd like your static files collected to when you use the86 :djadmin:`collectstatic` management command. For example::87 88 STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic"89 90 3. Run the :djadmin:`collectstatic` management command::91 92 ./manage.py collectstatic93 94 This'll churn through your static file storage and copy them into the95 directory given by :setting:`STATIC_ROOT`.96 97 4. Deploy those files by configuring your webserver of choice to serve the98 files in :setting:`STATIC_ROOT` at :setting:`STATIC_URL`.99 100 :ref:`staticfiles-production` covers some common deployment strategies101 for static files.102 103 Those are the **basics**. For more details on common configuration options,104 read on; for a detailed reference of the settings, commands, and other bits105 included with the framework see106 :doc:`the staticfiles reference </ref/contrib/staticfiles>`.107 108 .. note::109 110 In previous versions of Django, it was common to place static assets in111 :setting:`MEDIA_ROOT` along with user-uploaded files, and serve them both112 at :setting:`MEDIA_URL`. Part of the purpose of introducing the113 ``staticfiles`` app is to make it easier to keep static files separate114 from user-uploaded files.115 116 For this reason, you need to make your :setting:`MEDIA_ROOT` and117 :setting:`MEDIA_URL` different from your :setting:`STATIC_ROOT` and118 :setting:`STATIC_URL`. You will need to arrange for serving of files in119 :setting:`MEDIA_ROOT` yourself; ``staticfiles`` does not deal with120 user-uploaded files at all. You can, however, use121 :func:`django.views.static.serve` view for serving :setting:`MEDIA_ROOT`122 in development; see :ref:`staticfiles-other-directories`.123 124 .. _staticfiles-in-templates:125 126 Referring to static files in templates127 ======================================128 129 At some point, you'll probably need to link to static files in your templates.130 You could, of course, simply hardcode the path to you assets in the templates:131 132 .. code-block:: html133 134 <img src="http://static.example.com/static/myimage.jpg" />135 136 Of course, there are some serious problems with this: it doesn't work well in137 development, and it makes it *very* hard to change where you've deployed your138 static files. If, for example, you wanted to switch to using a content139 delivery network (CDN), then you'd need to change more or less every single140 template.141 142 A far better way is to use the value of the :setting:`STATIC_URL` setting143 directly in your templates. This means that a switch of static files servers144 only requires changing that single value. Much better!145 146 Django includes multiple built-in ways of using this setting in your147 templates: a context processor and a template tag.148 149 With a context processor150 ------------------------151 152 The included context processor is the easy way. Simply make sure153 ``'django.core.context_processors.static'`` is in your154 :setting:`TEMPLATE_CONTEXT_PROCESSORS`. It's there by default, and if you're155 editing that setting by hand it should look something like::156 157 TEMPLATE_CONTEXT_PROCESSORS = (158 'django.core.context_processors.debug',159 'django.core.context_processors.i18n',160 'django.core.context_processors.media',161 'django.core.context_processors.static',162 'django.contrib.auth.context_processors.auth',163 'django.contrib.messages.context_processors.messages',164 )165 166 Once that's done, you can refer to :setting:`STATIC_URL` in your templates:167 168 .. code-block:: html+django169 170 <img src="{{ STATIC_URL }}images/hi.jpg" />171 172 If ``{{ STATIC_URL }}`` isn't working in your template, you're probably not173 using :class:`~django.template.RequestContext` when rendering the template.174 175 As a brief refresher, context processors add variables into the contexts of176 every template. However, context processors require that you use177 :class:`~django.template.RequestContext` when rendering templates. This happens178 automatically if you're using a :doc:`generic view </ref/class-based-views>`,179 but in views written by hand you'll need to explicitly use ``RequestContext``180 To see how that works, and to read more details, check out181 :ref:`subclassing-context-requestcontext`.182 183 Another option is the :ttag:`get_static_prefix` template tag that is part of184 Django's core.185 186 With a template tag187 -------------------188 189 The more powerful tool is the :ttag:`static<staticfiles-static>` template190 tag. It builds the URL for the given relative path by using the configured191 :setting:`STATICFILES_STORAGE` storage.192 193 .. code-block:: html+django194 195 {% load staticfiles %}196 <img src="{% static "images/hi.jpg" %}" />197 198 It is also able to consume standard context variables, e.g. assuming a199 ``user_stylesheet`` variable is passed to the template:200 201 .. code-block:: html+django202 203 {% load staticfiles %}204 <link rel="stylesheet" href="{% static user_stylesheet %}" type="text/css" media="screen" />205 206 .. note::207 208 There is also a template tag named :ttag:`static` in Django's core set209 of :ref:`built in template tags<ref-templates-builtins-tags>` which has210 the same argument signature but only uses `urlparse.urljoin()`_ with the211 :setting:`STATIC_URL` setting and the given path. This has the212 disadvantage of not being able to easily switch the storage backend213 without changing the templates, so in doubt use the ``staticfiles``214 :ttag:`static<staticfiles-static>`215 template tag.216 217 .. _`urlparse.urljoin()`: http://docs.python.org/library/urlparse.html#urlparse.urljoin218 219 .. _staticfiles-development:220 221 Serving static files in development222 ===================================223 224 The static files tools are mostly designed to help with getting static files225 successfully deployed into production. This usually means a separate,226 dedicated static file server, which is a lot of overhead to mess with when227 developing locally. Thus, the ``staticfiles`` app ships with a228 **quick and dirty helper view** that you can use to serve files locally in229 development.230 231 This view is automatically enabled and will serve your static files at232 :setting:`STATIC_URL` when you use the built-in233 :ref:`runserver<staticfiles-runserver>` management command.234 235 To enable this view if you are using some other server for local development,236 you'll add a couple of lines to your URLconf. The first line goes at the top237 of the file, and the last line at the bottom::238 239 from django.contrib.staticfiles.urls import staticfiles_urlpatterns240 241 # ... the rest of your URLconf goes here ...242 243 urlpatterns += staticfiles_urlpatterns()244 245 This will inspect your :setting:`STATIC_URL` setting and wire up the view246 to serve static files accordingly. Don't forget to set the247 :setting:`STATICFILES_DIRS` setting appropriately to let248 ``django.contrib.staticfiles`` know where to look for files additionally to249 files in app directories.250 251 .. warning::252 253 This will only work if :setting:`DEBUG` is ``True``.254 255 That's because this view is **grossly inefficient** and probably256 **insecure**. This is only intended for local development, and should257 **never be used in production**.258 259 Additionally, when using ``staticfiles_urlpatterns`` your260 :setting:`STATIC_URL` setting can't be empty or a full URL, such as261 ``http://static.example.com/``.262 263 For a few more details on how the ``staticfiles`` can be used during264 development, see :ref:`staticfiles-development-view`.265 266 .. _staticfiles-other-directories:267 268 Serving other directories269 -------------------------270 271 .. currentmodule:: django.views.static272 .. function:: serve(request, path, document_root, show_indexes=False)273 274 There may be files other than your project's static assets that, for275 convenience, you'd like to have Django serve for you in local development.276 The :func:`~django.views.static.serve` view can be used to serve any directory277 you give it. (Again, this view is **not** hardened for production278 use, and should be used only as a development aid; you should serve these files279 in production using a real front-end webserver).280 281 The most likely example is user-uploaded content in :setting:`MEDIA_ROOT`.282 ``staticfiles`` is intended for static assets and has no built-in handling283 for user-uploaded files, but you can have Django serve your284 :setting:`MEDIA_ROOT` by appending something like this to your URLconf::285 286 from django.conf import settings287 288 # ... the rest of your URLconf goes here ...289 290 if settings.DEBUG:291 urlpatterns += patterns('',292 url(r'^media/(?P<path>.*)$', 'django.views.static.serve', {293 'document_root': settings.MEDIA_ROOT,294 }),295 )296 297 Note, the snippet assumes your :setting:`MEDIA_URL` has a value of298 ``'/media/'``. This will call the :func:`~django.views.static.serve` view,299 passing in the path from the URLconf and the (required) ``document_root``300 parameter.301 302 .. currentmodule:: django.conf.urls.static303 .. function:: static(prefix, view='django.views.static.serve', **kwargs)304 305 Since it can become a bit cumbersome to define this URL pattern, Django306 ships with a small URL helper function307 :func:`~django.conf.urls.static.static` that takes as parameters the prefix308 such as :setting:`MEDIA_URL` and a dotted path to a view, such as309 ``'django.views.static.serve'``. Any other function parameter will be310 transparently passed to the view.311 312 An example for serving :setting:`MEDIA_URL` (``'/media/'``) during313 development::314 315 from django.conf import settings316 from django.conf.urls.static import static317 318 urlpatterns = patterns('',319 # ... the rest of your URLconf goes here ...320 ) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)321 322 .. note::323 324 This helper function will only be operational in debug mode and if325 the given prefix is local (e.g. ``/static/``) and not a URL (e.g.326 ``http://static.example.com/``).327 328 .. _staticfiles-production:329 330 Serving static files in production331 ==================================332 333 The basic outline of putting static files into production is simple: run the334 :djadmin:`collectstatic` command when static files change, then arrange for335 the collected static files directory (:setting:`STATIC_ROOT`) to be moved to336 the static file server and served.337 338 Of course, as with all deployment tasks, the devil's in the details. Every339 production setup will be a bit different, so you'll need to adapt the basic340 outline to fit your needs. Below are a few common patterns that might help.341 342 Serving the app and your static files from the same server343 ----------------------------------------------------------344 345 If you want to serve your static files from the same server that's already346 serving your site, the basic outline gets modified to look something like:347 348 * Push your code up to the deployment server.349 * On the server, run :djadmin:`collectstatic` to copy all the static files350 into :setting:`STATIC_ROOT`.351 * Point your web server at :setting:`STATIC_ROOT`. For example, here's352 :ref:`how to do this under Apache and mod_wsgi <serving-files>`.353 354 You'll probably want to automate this process, especially if you've got355 multiple web servers. There's any number of ways to do this automation, but356 one option that many Django developers enjoy is `Fabric`__.357 358 __ http://fabfile.org/359 360 Below, and in the following sections, we'll show off a few example fabfiles361 (i.e. Fabric scripts) that automate these file deployment options. The syntax362 of a fabfile is fairly straightforward but won't be covered here; consult363 `Fabric's documentation`__, for a complete explanation of the syntax..364 365 __ http://docs.fabfile.org/366 367 So, a fabfile to deploy static files to a couple of web servers might look368 something like::369 370 from fabric.api import *371 372 # Hosts to deploy onto373 env.hosts = ['www1.example.com', 'www2.example.com']374 375 # Where your project code lives on the server376 env.project_root = '/home/www/myproject'377 378 def deploy_static():379 with cd(env.project_root):380 run('./manage.py collectstatic -v0 --noinput')381 382 Serving static files from a dedicated server383 --------------------------------------------384 385 Most larger Django apps use a separate Web server -- i.e., one that's not also386 running Django -- for serving static files. This server often runs a different387 type of web server -- faster but less full-featured. Some good choices are:388 389 * lighttpd_390 * Nginx_391 * TUX_392 * Cherokee_393 * A stripped-down version of Apache_394 395 .. _lighttpd: http://www.lighttpd.net/396 .. _Nginx: http://wiki.nginx.org/Main397 .. _TUX: http://en.wikipedia.org/wiki/TUX_web_server398 .. _Apache: http://httpd.apache.org/399 .. _Cherokee: http://www.cherokee-project.com/400 401 Configuring these servers is out of scope of this document; check each402 server's respective documentation for instructions.403 404 Since your static file server won't be running Django, you'll need to modify405 the deployment strategy to look something like:406 407 * When your static files change, run :djadmin:`collectstatic` locally.408 * Push your local :setting:`STATIC_ROOT` up to the static file server409 into the directory that's being served. ``rsync`` is a good410 choice for this step since it only needs to transfer the411 bits of static files that have changed.412 413 Here's how this might look in a fabfile::414 415 from fabric.api import *416 from fabric.contrib import project417 418 # Where the static files get collected locally419 env.local_static_root = '/tmp/static'420 421 # Where the static files should go remotely422 env.remote_static_root = '/home/www/static.example.com'423 424 @roles('static')425 def deploy_static():426 local('./manage.py collectstatic')427 project.rysnc_project(428 remote_dir = env.remote_static_root,429 local_dir = env.local_static_root,430 delete = True431 )432 433 .. _staticfiles-from-cdn:434 435 Serving static files from a cloud service or CDN436 ------------------------------------------------437 438 Another common tactic is to serve static files from a cloud storage provider439 like Amazon's S3__ and/or a CDN (content delivery network). This lets you440 ignore the problems of serving static files, and can often make for441 faster-loading webpages (especially when using a CDN).442 443 When using these services, the basic workflow would look a bit like the above,444 except that instead of using ``rsync`` to transfer your static files to the445 server you'd need to transfer the static files to the storage provider or CDN.446 447 There's any number of ways you might do this, but if the provider has an API a448 :doc:`custom file storage backend </howto/custom-file-storage>` will make the449 process incredibly simple. If you've written or are using a 3rd party custom450 storage backend, you can tell :djadmin:`collectstatic` to use it by setting451 :setting:`STATICFILES_STORAGE` to the storage engine.452 453 For example, if you've written an S3 storage backend in454 ``myproject.storage.S3Storage`` you could use it with::455 456 STATICFILES_STORAGE = 'myproject.storage.S3Storage'457 458 Once that's done, all you have to do is run :djadmin:`collectstatic` and your459 static files would be pushed through your storage package up to S3. If you460 later needed to switch to a different storage provider, it could be as simple461 as changing your :setting:`STATICFILES_STORAGE` setting.462 463 For details on how you'd write one of these backends,464 :doc:`/howto/custom-file-storage`.465 466 .. seealso::467 468 The `django-storages`__ project is a 3rd party app that provides many469 storage backends for many common file storage APIs (including `S3`__).470 471 __ http://s3.amazonaws.com/472 __ http://code.larlet.fr/django-storages/473 __ http://django-storages.readthedocs.org/en/latest/backends/amazon-S3.html474 475 Upgrading from ``django-staticfiles``476 =====================================477 478 ``django.contrib.staticfiles`` began its life as `django-staticfiles`_. If479 you're upgrading from `django-staticfiles`_ older than 1.0 (e.g. 0.3.4) to480 ``django.contrib.staticfiles``, you'll need to make a few changes:481 482 * Application files should now live in a ``static`` directory in each app483 (`django-staticfiles`_ used the name ``media``, which was slightly484 confusing).485 486 * The management commands ``build_static`` and ``resolve_static`` are now487 called :djadmin:`collectstatic` and :djadmin:`findstatic`.488 489 * The settings ``STATICFILES_PREPEND_LABEL_APPS``,490 ``STATICFILES_MEDIA_DIRNAMES`` and ``STATICFILES_EXCLUDED_APPS`` were491 removed.492 493 * The setting ``STATICFILES_RESOLVERS`` was removed, and replaced by the494 new :setting:`STATICFILES_FINDERS`.495 496 * The default for :setting:`STATICFILES_STORAGE` was renamed from497 ``staticfiles.storage.StaticFileStorage`` to498 ``staticfiles.storage.StaticFilesStorage``499 500 * If using :ref:`runserver<staticfiles-runserver>` for local development501 (and the :setting:`DEBUG` setting is ``True``), you no longer need to add502 anything to your URLconf for serving static files in development.503 504 Learn more505 ==========506 507 This document has covered the basics and some common usage patterns. For508 complete details on all the settings, commands, template tags, and other pieces509 include in ``django.contrib.staticfiles``, see :doc:`the staticfiles reference510 </ref/contrib/staticfiles>`. -
docs/index.txt
diff --git a/docs/index.txt b/docs/index.txt index a5d2e13..11ddc41 100644
a b The view layer 102 102 :doc:`Overview <topics/http/file-uploads>` | 103 103 :doc:`File objects <ref/files/file>` | 104 104 :doc:`Storage API <ref/files/storage>` | 105 :doc:`Managing files <topics/files>` |105 :doc:`Managing media files <topics/files/media` | 106 106 :doc:`Custom storage <howto/custom-file-storage>` 107 107 108 108 * **Generic views:** … … The development process 158 158 :doc:`FastCGI/SCGI/AJP <howto/deployment/fastcgi>` | 159 159 :doc:`Apache/mod_python (deprecated) <howto/deployment/modpython>` | 160 160 :doc:`Apache authentication <howto/apache-auth>` | 161 :doc:` Handling static files <howto/static-files>` |161 :doc:`Managing static files <topics/files/static>` | 162 162 :doc:`Tracking code errors by email <howto/error-reporting>` 163 163 164 164 Other batteries included -
docs/misc/api-stability.txt
diff --git a/docs/misc/api-stability.txt b/docs/misc/api-stability.txt index 75fa6b4..08e9496 100644
a b of 1.0. This includes these APIs: 47 47 48 48 - :doc:`Sending email </topics/email>`. 49 49 50 - :doc:` File handling and storage </topics/files>`50 - :doc:`Managing media files </topics/files/media` 51 51 52 52 - :doc:`Forms </topics/forms/index>` 53 53 -
docs/ref/contrib/staticfiles.txt
diff --git a/docs/ref/contrib/staticfiles.txt b/docs/ref/contrib/staticfiles.txt index 1dbd00b..119b559 100644
a b can easily be served in production. 14 14 .. seealso:: 15 15 16 16 For an introduction to the static files app and some usage examples, see 17 :doc:`/ howto/static-files`.17 :doc:`/topics/files/static`. 18 18 19 19 .. _staticfiles-settings: 20 20 -
docs/ref/django-admin.txt
diff --git a/docs/ref/django-admin.txt b/docs/ref/django-admin.txt index 5ea7280..deaa0eb 100644
a b Serving static files with the development server 766 766 767 767 By default, the development server doesn't serve any static files for your site 768 768 (such as CSS files, images, things under :setting:`MEDIA_URL` and so forth). If 769 you want to configure Django to serve static media, read :doc:`/ howto/static-files`.769 you want to configure Django to serve static media, read :doc:`/topics/files/static`. 770 770 771 771 shell 772 772 ----- … … collectstatic 1268 1268 ~~~~~~~~~~~~~ 1269 1269 1270 1270 This command is only available if the :doc:`static files application 1271 </ howto/static-files>` (``django.contrib.staticfiles``) is installed.1271 </topics/files/static>` (``django.contrib.staticfiles``) is installed. 1272 1272 1273 1273 Please refer to its :djadmin:`description <collectstatic>` in the 1274 1274 :doc:`staticfiles </ref/contrib/staticfiles>` documentation. … … findstatic 1277 1277 ~~~~~~~~~~ 1278 1278 1279 1279 This command is only available if the :doc:`static files application 1280 </ howto/static-files>` (``django.contrib.staticfiles``) is installed.1280 </topics/files/static>` (``django.contrib.staticfiles``) is installed. 1281 1281 1282 1282 Please refer to its :djadmin:`description <findstatic>` in the :doc:`staticfiles 1283 1283 </ref/contrib/staticfiles>` documentation. -
docs/ref/models/fields.txt
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt index 36bf60e..fe4f60d 100644
a b Also has one optional argument: 533 533 .. attribute:: FileField.storage 534 534 535 535 Optional. A storage object, which handles the storage and retrieval of your 536 files. See :doc:`/topics/files `for details on how to provide this object.536 files. See :doc:`/topics/files/media for details on how to provide this object. 537 537 538 538 The admin represents this field as an ``<input type="file">`` (a file-upload 539 539 widget). … … If you wanted to retrieve the uploaded file's on-disk filename, or the file's 569 569 size, you could use the :attr:`~django.core.files.File.name` and 570 570 :attr:`~django.core.files.File.size` attributes respectively; for more 571 571 information on the available attributes and methods, see the 572 :class:`~django.core.files.File` class reference and the :doc:`/topics/files `572 :class:`~django.core.files.File` class reference and the :doc:`/topics/files/media 573 573 topic guide. 574 574 575 575 .. note:: … … Or you can construct one from a Python string like this:: 645 645 from django.core.files.base import ContentFile 646 646 myfile = ContentFile("hello world") 647 647 648 For more information, see :doc:`/topics/files `.648 For more information, see :doc:`/topics/files/media. 649 649 650 650 .. method:: FieldFile.delete(save=True) 651 651 -
docs/ref/request-response.txt
diff --git a/docs/ref/request-response.txt b/docs/ref/request-response.txt index c0ae73e..99a3e63 100644
a b All attributes except ``session`` should be considered read-only. 128 128 ``FILES`` is the ``name`` from the ``<input type="file" name="" />``. Each 129 129 value in ``FILES`` is an :class:`UploadedFile` as described below. 130 130 131 See :doc:`/topics/files `for more information.131 See :doc:`/topics/files/media for more information. 132 132 133 133 Note that ``FILES`` will only contain data if the request method was POST 134 134 and the ``<form>`` that posted to the request had -
docs/ref/settings.txt
diff --git a/docs/ref/settings.txt b/docs/ref/settings.txt index c06ef1a..ecc8c83 100644
a b DEFAULT_FILE_STORAGE 877 877 Default: :class:`django.core.files.storage.FileSystemStorage` 878 878 879 879 Default file storage class to be used for any file-related operations that don't 880 specify a particular storage system. See :doc:`/topics/files `.880 specify a particular storage system. See :doc:`/topics/files/media. 881 881 882 882 .. setting:: DEFAULT_FROM_EMAIL 883 883 … … Default:: 1030 1030 ("django.core.files.uploadhandler.MemoryFileUploadHandler", 1031 1031 "django.core.files.uploadhandler.TemporaryFileUploadHandler",) 1032 1032 1033 A tuple of handlers to use for uploading. See :doc:`/topics/files `for details.1033 A tuple of handlers to use for uploading. See :doc:`/topics/files/media for details. 1034 1034 1035 1035 .. setting:: FILE_UPLOAD_MAX_MEMORY_SIZE 1036 1036 … … FILE_UPLOAD_MAX_MEMORY_SIZE 1040 1040 Default: ``2621440`` (i.e. 2.5 MB). 1041 1041 1042 1042 The maximum size (in bytes) that an upload will be before it gets streamed to 1043 the file system. See :doc:`/topics/files `for details.1043 the file system. See :doc:`/topics/files/media for details. 1044 1044 1045 1045 .. setting:: FILE_UPLOAD_PERMISSIONS 1046 1046 … … The directory to store data temporarily while uploading files. If ``None``, 1079 1079 Django will use the standard temporary directory for the operating system. For 1080 1080 example, this will default to '/tmp' on \*nix-style operating systems. 1081 1081 1082 See :doc:`/topics/files `for details.1082 See :doc:`/topics/files/media for details. 1083 1083 1084 1084 .. setting:: FIRST_DAY_OF_WEEK 1085 1085 … … MEDIA_ROOT 1402 1402 Default: ``''`` (Empty string) 1403 1403 1404 1404 Absolute path to the directory that holds media for this installation, used 1405 for :doc:`managing stored files </topics/files>`.1405 for :doc:`managing media files </topics/files/media`. 1406 1406 1407 1407 Example: ``"/home/media/media.lawrence.com/"`` 1408 1408 … … MEDIA_URL 1416 1416 Default: ``''`` (Empty string) 1417 1417 1418 1418 URL that handles the media served from :setting:`MEDIA_ROOT`, used 1419 for :doc:`managing stored files </topics/files>`.1419 for :doc:`managing media files </topics/files/media`. 1420 1420 1421 1421 Example: ``"http://media.lawrence.com/"`` 1422 1422 … … Example: ``"/home/example.com/static/"`` 1886 1886 If the :doc:`staticfiles</ref/contrib/staticfiles>` contrib app is enabled 1887 1887 (default) the :djadmin:`collectstatic` management command will collect static 1888 1888 files into this directory. See the howto on :doc:`managing static 1889 files</ howto/static-files>` for more details about usage.1889 files</topics/files/static>` for more details about usage. 1890 1890 1891 1891 .. warning:: 1892 1892 -
docs/releases/1.0-alpha-2.txt
diff --git a/docs/releases/1.0-alpha-2.txt b/docs/releases/1.0-alpha-2.txt index a26a214..85483d0 100644
a b Pluggable file storage 36 36 Django's built-in ``FileField`` and ``ImageField`` now can take advantage of 37 37 pluggable file-storage backends, allowing extensive customization of where 38 38 and how uploaded files get stored by Django. For details, see :doc:`the 39 files documentation </topics/files >`; big thanks go to Marty Alchin for39 files documentation </topics/files/media`; big thanks go to Marty Alchin for 40 40 putting in the hard work to get this completed. 41 41 42 42 Jython compatibility -
docs/releases/1.0.txt
diff --git a/docs/releases/1.0.txt b/docs/releases/1.0.txt index e752b02..8678f2a 100644
a b Pluggable file storage 141 141 Django's built-in ``FileField`` and ``ImageField`` now can take advantage of 142 142 pluggable file-storage backends, allowing extensive customization of where and 143 143 how uploaded files get stored by Django. For details, see :doc:`the files 144 documentation </topics/files >`; big thanks go to Marty Alchin for putting in the144 documentation </topics/files/media`; big thanks go to Marty Alchin for putting in the 145 145 hard work to get this completed. 146 146 147 147 Jython compatibility -
docs/releases/1.3-alpha-1.txt
diff --git a/docs/releases/1.3-alpha-1.txt b/docs/releases/1.3-alpha-1.txt index f1ff23b..983bcbb 100644
a b arrange for serving of files in :setting:`MEDIA_ROOT` yourself; 73 73 74 74 See the :doc:`reference documentation of the app </ref/contrib/staticfiles>` 75 75 for more details or learn how to :doc:`manage static files 76 </ howto/static-files>`.76 </topics/files/static>`. 77 77 78 78 ``unittest2`` support 79 79 ~~~~~~~~~~~~~~~~~~~~~ -
docs/releases/1.3-beta-1.txt
diff --git a/docs/releases/1.3-beta-1.txt b/docs/releases/1.3-beta-1.txt index 02c038f..f5fd101 100644
a b Based on feedback from the community this release adds two new options to the 37 37 38 38 See the :doc:`staticfiles reference documentation </ref/contrib/staticfiles>` 39 39 for more details, or learn :doc:`how to manage static files 40 </ howto/static-files>`.40 </topics/files/static>`. 41 41 42 42 Translation comments 43 43 ~~~~~~~~~~~~~~~~~~~~ -
docs/releases/1.3.txt
diff --git a/docs/releases/1.3.txt b/docs/releases/1.3.txt index 224cd47..3bdbc49 100644
a b at :setting:`STATIC_URL`. 115 115 116 116 See the :doc:`reference documentation of the app </ref/contrib/staticfiles>` 117 117 for more details or learn how to :doc:`manage static files 118 </ howto/static-files>`.118 </topics/files/static>`. 119 119 120 120 unittest2 support 121 121 ~~~~~~~~~~~~~~~~~ -
docs/releases/1.4-alpha-1.txt
diff --git a/docs/releases/1.4-alpha-1.txt b/docs/releases/1.4-alpha-1.txt index b5ec782..09aa4a1 100644
a b If you've previously used a URL path for ``ADMIN_MEDIA_PREFIX`` (e.g. 578 578 ``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT` 579 579 are configured and your web server serves the files correctly. The development 580 580 server continues to serve the admin files just like before. Don't hesitate to 581 consult the :doc:`static files howto </howto/static-files>` for further581 consult the :doc:`static files topic </topics/files/static>` for further 582 582 details. 583 583 584 584 In case your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g. -
docs/releases/1.4-beta-1.txt
diff --git a/docs/releases/1.4-beta-1.txt b/docs/releases/1.4-beta-1.txt index 88f32ea..8213425 100644
a b If you've previously used a URL path for ``ADMIN_MEDIA_PREFIX`` (e.g. 646 646 ``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT` 647 647 are configured and your web server serves the files correctly. The development 648 648 server continues to serve the admin files just like before. Don't hesitate to 649 consult the :doc:`static files howto </howto/static-files>` for further649 consult the :doc:`static files topic </topics/files/static>` for further 650 650 details. 651 651 652 652 In case your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g. -
docs/releases/1.4.txt
diff --git a/docs/releases/1.4.txt b/docs/releases/1.4.txt index 51766dc..b999fcc 100644
a b If you've previously used a URL path for ``ADMIN_MEDIA_PREFIX`` (e.g. 708 708 ``/media/``) simply make sure :setting:`STATIC_URL` and :setting:`STATIC_ROOT` 709 709 are configured and your Web server serves those files correctly. The 710 710 development server continues to serve the admin files just like before. Read 711 the :doc:`static files howto </howto/static-files>` for more details.711 the :doc:`static files topic </topics/files/static>` for more details. 712 712 713 713 If your ``ADMIN_MEDIA_PREFIX`` is set to an specific domain (e.g. 714 714 ``http://media.example.com/admin/``), make sure to also set your -
deleted file docs/topics/files.txt
diff --git a/docs/topics/files.txt b/docs/topics/files.txt deleted file mode 100644 index 9ab8d5c..0000000
+ - 1 ==============2 Managing files3 ==============4 5 This document describes Django's file access APIs.6 7 By default, Django stores files locally, using the :setting:`MEDIA_ROOT` and8 :setting:`MEDIA_URL` settings. The examples below assume that you're using these9 defaults.10 11 However, Django provides ways to write custom `file storage systems`_ that12 allow you to completely customize where and how Django stores files. The13 second half of this document describes how these storage systems work.14 15 .. _file storage systems: `File storage`_16 17 Using files in models18 =====================19 20 When you use a :class:`~django.db.models.FileField` or21 :class:`~django.db.models.ImageField`, Django provides a set of APIs you can use22 to deal with that file.23 24 Consider the following model, using an :class:`~django.db.models.ImageField` to25 store a photo::26 27 class Car(models.Model):28 name = models.CharField(max_length=255)29 price = models.DecimalField(max_digits=5, decimal_places=2)30 photo = models.ImageField(upload_to='cars')31 32 Any ``Car`` instance will have a ``photo`` attribute that you can use to get at33 the details of the attached photo::34 35 >>> car = Car.objects.get(name="57 Chevy")36 >>> car.photo37 <ImageFieldFile: chevy.jpg>38 >>> car.photo.name39 u'cars/chevy.jpg'40 >>> car.photo.path41 u'/media/cars/chevy.jpg'42 >>> car.photo.url43 u'http://media.example.com/cars/chevy.jpg'44 45 This object -- ``car.photo`` in the example -- is a ``File`` object, which means46 it has all the methods and attributes described below.47 48 .. note::49 The file is saved as part of saving the model in the database, so the actual50 file name used on disk cannot be relied on until after the model has been51 saved.52 53 54 The ``File`` object55 ===================56 57 Internally, Django uses a :class:`django.core.files.File` instance any time it58 needs to represent a file. This object is a thin wrapper around Python's59 `built-in file object`_ with some Django-specific additions.60 61 .. _built-in file object: http://docs.python.org/library/stdtypes.html#bltin-file-objects62 63 Most of the time you'll simply use a ``File`` that Django's given you (i.e. a64 file attached to a model as above, or perhaps an uploaded file).65 66 If you need to construct a ``File`` yourself, the easiest way is to create one67 using a Python built-in ``file`` object::68 69 >>> from django.core.files import File70 71 # Create a Python file object using open()72 >>> f = open('/tmp/hello.world', 'w')73 >>> myfile = File(f)74 75 Now you can use any of the documented attributes and methods76 of the :class:`~django.core.files.File` class.77 78 File storage79 ============80 81 Behind the scenes, Django delegates decisions about how and where to store files82 to a file storage system. This is the object that actually understands things83 like file systems, opening and reading files, etc.84 85 Django's default file storage is given by the :setting:`DEFAULT_FILE_STORAGE`86 setting; if you don't explicitly provide a storage system, this is the one that87 will be used.88 89 See below for details of the built-in default file storage system, and see90 :doc:`/howto/custom-file-storage` for information on writing your own file91 storage system.92 93 Storage objects94 ---------------95 96 Though most of the time you'll want to use a ``File`` object (which delegates to97 the proper storage for that file), you can use file storage systems directly.98 You can create an instance of some custom file storage class, or -- often more99 useful -- you can use the global default storage system::100 101 >>> from django.core.files.storage import default_storage102 >>> from django.core.files.base import ContentFile103 104 >>> path = default_storage.save('/path/to/file', ContentFile('new content'))105 >>> path106 u'/path/to/file'107 108 >>> default_storage.size(path)109 11110 >>> default_storage.open(path).read()111 'new content'112 113 >>> default_storage.delete(path)114 >>> default_storage.exists(path)115 False116 117 See :doc:`/ref/files/storage` for the file storage API.118 119 The built-in filesystem storage class120 -------------------------------------121 122 Django ships with a built-in ``FileSystemStorage`` class (defined in123 ``django.core.files.storage``) which implements basic local filesystem file124 storage. Its initializer takes two arguments:125 126 ====================== ===================================================127 Argument Description128 ====================== ===================================================129 ``location`` Optional. Absolute path to the directory that will130 hold the files. If omitted, it will be set to the131 value of your :setting:`MEDIA_ROOT` setting.132 ``base_url`` Optional. URL that serves the files stored at this133 location. If omitted, it will default to the value134 of your :setting:`MEDIA_URL` setting.135 ====================== ===================================================136 137 For example, the following code will store uploaded files under138 ``/media/photos`` regardless of what your :setting:`MEDIA_ROOT` setting is::139 140 from django.db import models141 from django.core.files.storage import FileSystemStorage142 143 fs = FileSystemStorage(location='/media/photos')144 145 class Car(models.Model):146 ...147 photo = models.ImageField(storage=fs)148 149 :doc:`Custom storage systems </howto/custom-file-storage>` work the same way:150 you can pass them in as the ``storage`` argument to a151 :class:`~django.db.models.FileField`. -
new file docs/topics/files/media.txt
diff --git a/docs/topics/files/media.txt b/docs/topics/files/media.txt new file mode 100644 index 0000000..ec82fab
- + 1 ==================== 2 Managing media files 3 ==================== 4 5 This document describes Django's file access APIs for media files. 6 Il you want to handle static files (JS, CSS, etc), see 7 :doc:`/topics/files/static` 8 9 By default, Django stores files locally, using the :setting:`MEDIA_ROOT` and 10 :setting:`MEDIA_URL` settings. The examples below assume that you're using these 11 defaults. 12 13 However, Django provides ways to write custom `file storage systems`_ that 14 allow you to completely customize where and how Django stores files. The 15 second half of this document describes how these storage systems work. 16 17 .. _file storage systems: `File storage`_ 18 19 Using files in models 20 ===================== 21 22 When you use a :class:`~django.db.models.FileField` or 23 :class:`~django.db.models.ImageField`, Django provides a set of APIs you can use 24 to deal with that file. 25 26 Consider the following model, using an :class:`~django.db.models.ImageField` to 27 store a photo:: 28 29 class Car(models.Model): 30 name = models.CharField(max_length=255) 31 price = models.DecimalField(max_digits=5, decimal_places=2) 32 photo = models.ImageField(upload_to='cars') 33 34 Any ``Car`` instance will have a ``photo`` attribute that you can use to get at 35 the details of the attached photo:: 36 37 >>> car = Car.objects.get(name="57 Chevy") 38 >>> car.photo 39 <ImageFieldFile: chevy.jpg> 40 >>> car.photo.name 41 u'cars/chevy.jpg' 42 >>> car.photo.path 43 u'/media/cars/chevy.jpg' 44 >>> car.photo.url 45 u'http://media.example.com/cars/chevy.jpg' 46 47 This object -- ``car.photo`` in the example -- is a ``File`` object, which means 48 it has all the methods and attributes described below. 49 50 .. note:: 51 The file is saved as part of saving the model in the database, so the actual 52 file name used on disk cannot be relied on until after the model has been 53 saved. 54 55 56 The ``File`` object 57 =================== 58 59 Internally, Django uses a :class:`django.core.files.File` instance any time it 60 needs to represent a file. This object is a thin wrapper around Python's 61 `built-in file object`_ with some Django-specific additions. 62 63 .. _built-in file object: http://docs.python.org/library/stdtypes.html#bltin-file-objects 64 65 Most of the time you'll simply use a ``File`` that Django's given you (i.e. a 66 file attached to a model as above, or perhaps an uploaded file). 67 68 If you need to construct a ``File`` yourself, the easiest way is to create one 69 using a Python built-in ``file`` object:: 70 71 >>> from django.core.files import File 72 73 # Create a Python file object using open() 74 >>> f = open('/tmp/hello.world', 'w') 75 >>> myfile = File(f) 76 77 Now you can use any of the documented attributes and methods 78 of the :class:`~django.core.files.File` class. 79 80 File storage 81 ============ 82 83 Behind the scenes, Django delegates decisions about how and where to store files 84 to a file storage system. This is the object that actually understands things 85 like file systems, opening and reading files, etc. 86 87 Django's default file storage is given by the :setting:`DEFAULT_FILE_STORAGE` 88 setting; if you don't explicitly provide a storage system, this is the one that 89 will be used. 90 91 See below for details of the built-in default file storage system, and see 92 :doc:`/howto/custom-file-storage` for information on writing your own file 93 storage system. 94 95 Storage objects 96 --------------- 97 98 Though most of the time you'll want to use a ``File`` object (which delegates to 99 the proper storage for that file), you can use file storage systems directly. 100 You can create an instance of some custom file storage class, or -- often more 101 useful -- you can use the global default storage system:: 102 103 >>> from django.core.files.storage import default_storage 104 >>> from django.core.files.base import ContentFile 105 106 >>> path = default_storage.save('/path/to/file', ContentFile('new content')) 107 >>> path 108 u'/path/to/file' 109 110 >>> default_storage.size(path) 111 11 112 >>> default_storage.open(path).read() 113 'new content' 114 115 >>> default_storage.delete(path) 116 >>> default_storage.exists(path) 117 False 118 119 See :doc:`/ref/files/storage` for the file storage API. 120 121 The built-in filesystem storage class 122 ------------------------------------- 123 124 Django ships with a built-in ``FileSystemStorage`` class (defined in 125 ``django.core.files.storage``) which implements basic local filesystem file 126 storage. Its initializer takes two arguments: 127 128 ====================== =================================================== 129 Argument Description 130 ====================== =================================================== 131 ``location`` Optional. Absolute path to the directory that will 132 hold the files. If omitted, it will be set to the 133 value of your :setting:`MEDIA_ROOT` setting. 134 ``base_url`` Optional. URL that serves the files stored at this 135 location. If omitted, it will default to the value 136 of your :setting:`MEDIA_URL` setting. 137 ====================== =================================================== 138 139 For example, the following code will store uploaded files under 140 ``/media/photos`` regardless of what your :setting:`MEDIA_ROOT` setting is:: 141 142 from django.db import models 143 from django.core.files.storage import FileSystemStorage 144 145 fs = FileSystemStorage(location='/media/photos') 146 147 class Car(models.Model): 148 ... 149 photo = models.ImageField(storage=fs) 150 151 :doc:`Custom storage systems </howto/custom-file-storage>` work the same way: 152 you can pass them in as the ``storage`` argument to a 153 :class:`~django.db.models.FileField`. -
new file docs/topics/files/static.txt
diff --git a/docs/topics/files/static.txt b/docs/topics/files/static.txt new file mode 100644 index 0000000..e3a40a1
- + 1 ===================== 2 Managing static files 3 ===================== 4 5 .. versionadded:: 1.3 6 7 Django developers mostly concern themselves with the dynamic parts of web 8 applications -- the views and templates that render anew for each request. But 9 web applications have other parts: the static files (images, CSS, 10 Javascript, etc.) that are needed to render a complete web page. 11 12 For small projects, this isn't a big deal, because you can just keep the 13 static files somewhere your web server can find it. However, in bigger 14 projects -- especially those comprised of multiple apps -- dealing with the 15 multiple sets of static files provided by each application starts to get 16 tricky. 17 18 That's what ``django.contrib.staticfiles`` is for: it collects static files 19 from each of your applications (and any other places you specify) into a 20 single location that can easily be served in production. 21 22 .. note:: 23 24 If you've used the `django-staticfiles`_ third-party app before, then 25 ``django.contrib.staticfiles`` will look very familiar. That's because 26 they're essentially the same code: ``django.contrib.staticfiles`` started 27 its life as `django-staticfiles`_ and was merged into Django 1.3. 28 29 If you're upgrading from ``django-staticfiles``, please see `Upgrading from 30 django-staticfiles`_, below, for a few minor changes you'll need to make. 31 32 .. _django-staticfiles: http://pypi.python.org/pypi/django-staticfiles/ 33 34 Using ``django.contrib.staticfiles`` 35 ==================================== 36 37 Basic usage 38 ----------- 39 40 1. Put your static files somewhere that ``staticfiles`` will find them. 41 42 By default, this means within ``static/`` subdirectories of apps in your 43 :setting:`INSTALLED_APPS`. 44 45 Your project will probably also have static assets that aren't tied to a 46 particular app. The :setting:`STATICFILES_DIRS` setting is a tuple of 47 filesystem directories to check when loading static files. It's a search 48 path that is by default empty. See the :setting:`STATICFILES_DIRS` docs 49 how to extend this list of additional paths. 50 51 Additionally, see the documentation for the :setting:`STATICFILES_FINDERS` 52 setting for details on how ``staticfiles`` finds your files. 53 54 2. Make sure that ``django.contrib.staticfiles`` is included in your 55 :setting:`INSTALLED_APPS`. 56 57 For :ref:`local development<staticfiles-development>`, if you are using 58 :ref:`runserver<staticfiles-runserver>` or adding 59 :ref:`staticfiles_urlpatterns<staticfiles-development>` to your 60 URLconf, you're done with the setup -- your static files will 61 automatically be served at the default (for 62 :djadmin:`newly created<startproject>` projects) :setting:`STATIC_URL` 63 of ``/static/``. 64 65 3. You'll probably need to refer to these files in your templates. The 66 easiest method is to use the included context processor which allows 67 template code like: 68 69 .. code-block:: html+django 70 71 <img src="{{ STATIC_URL }}images/hi.jpg" /> 72 73 See :ref:`staticfiles-in-templates` for more details, **including** an 74 alternate method using a template tag. 75 76 Deploying static files in a nutshell 77 ------------------------------------ 78 79 When you're ready to move out of local development and deploy your project: 80 81 1. Set the :setting:`STATIC_URL` setting to the public URL for your static 82 files (in most cases, the default value of ``/static/`` is just fine). 83 84 2. Set the :setting:`STATIC_ROOT` setting to point to the filesystem path 85 you'd like your static files collected to when you use the 86 :djadmin:`collectstatic` management command. For example:: 87 88 STATIC_ROOT = "/home/jacob/projects/mysite.com/sitestatic" 89 90 3. Run the :djadmin:`collectstatic` management command:: 91 92 ./manage.py collectstatic 93 94 This'll churn through your static file storage and copy them into the 95 directory given by :setting:`STATIC_ROOT`. 96 97 4. Deploy those files by configuring your webserver of choice to serve the 98 files in :setting:`STATIC_ROOT` at :setting:`STATIC_URL`. 99 100 :ref:`staticfiles-production` covers some common deployment strategies 101 for static files. 102 103 Those are the **basics**. For more details on common configuration options, 104 read on; for a detailed reference of the settings, commands, and other bits 105 included with the framework see 106 :doc:`the staticfiles reference </ref/contrib/staticfiles>`. 107 108 .. note:: 109 110 In previous versions of Django, it was common to place static assets in 111 :setting:`MEDIA_ROOT` along with user-uploaded files, and serve them both 112 at :setting:`MEDIA_URL`. Part of the purpose of introducing the 113 ``staticfiles`` app is to make it easier to keep static files separate 114 from user-uploaded files. 115 116 For this reason, you need to make your :setting:`MEDIA_ROOT` and 117 :setting:`MEDIA_URL` different from your :setting:`STATIC_ROOT` and 118 :setting:`STATIC_URL`. You will need to arrange for serving of files in 119 :setting:`MEDIA_ROOT` yourself; ``staticfiles`` does not deal with 120 user-uploaded files at all. You can, however, use 121 :func:`django.views.static.serve` view for serving :setting:`MEDIA_ROOT` 122 in development; see :ref:`staticfiles-other-directories`. 123 124 .. _staticfiles-in-templates: 125 126 Referring to static files in templates 127 ====================================== 128 129 At some point, you'll probably need to link to static files in your templates. 130 You could, of course, simply hardcode the path to you assets in the templates: 131 132 .. code-block:: html 133 134 <img src="http://static.example.com/static/myimage.jpg" /> 135 136 Of course, there are some serious problems with this: it doesn't work well in 137 development, and it makes it *very* hard to change where you've deployed your 138 static files. If, for example, you wanted to switch to using a content 139 delivery network (CDN), then you'd need to change more or less every single 140 template. 141 142 A far better way is to use the value of the :setting:`STATIC_URL` setting 143 directly in your templates. This means that a switch of static files servers 144 only requires changing that single value. Much better! 145 146 Django includes multiple built-in ways of using this setting in your 147 templates: a context processor and a template tag. 148 149 With a context processor 150 ------------------------ 151 152 The included context processor is the easy way. Simply make sure 153 ``'django.core.context_processors.static'`` is in your 154 :setting:`TEMPLATE_CONTEXT_PROCESSORS`. It's there by default, and if you're 155 editing that setting by hand it should look something like:: 156 157 TEMPLATE_CONTEXT_PROCESSORS = ( 158 'django.core.context_processors.debug', 159 'django.core.context_processors.i18n', 160 'django.core.context_processors.media', 161 'django.core.context_processors.static', 162 'django.contrib.auth.context_processors.auth', 163 'django.contrib.messages.context_processors.messages', 164 ) 165 166 Once that's done, you can refer to :setting:`STATIC_URL` in your templates: 167 168 .. code-block:: html+django 169 170 <img src="{{ STATIC_URL }}images/hi.jpg" /> 171 172 If ``{{ STATIC_URL }}`` isn't working in your template, you're probably not 173 using :class:`~django.template.RequestContext` when rendering the template. 174 175 As a brief refresher, context processors add variables into the contexts of 176 every template. However, context processors require that you use 177 :class:`~django.template.RequestContext` when rendering templates. This happens 178 automatically if you're using a :doc:`generic view </ref/class-based-views>`, 179 but in views written by hand you'll need to explicitly use ``RequestContext`` 180 To see how that works, and to read more details, check out 181 :ref:`subclassing-context-requestcontext`. 182 183 Another option is the :ttag:`get_static_prefix` template tag that is part of 184 Django's core. 185 186 With a template tag 187 ------------------- 188 189 The more powerful tool is the :ttag:`static<staticfiles-static>` template 190 tag. It builds the URL for the given relative path by using the configured 191 :setting:`STATICFILES_STORAGE` storage. 192 193 .. code-block:: html+django 194 195 {% load staticfiles %} 196 <img src="{% static "images/hi.jpg" %}" /> 197 198 It is also able to consume standard context variables, e.g. assuming a 199 ``user_stylesheet`` variable is passed to the template: 200 201 .. code-block:: html+django 202 203 {% load staticfiles %} 204 <link rel="stylesheet" href="{% static user_stylesheet %}" type="text/css" media="screen" /> 205 206 .. note:: 207 208 There is also a template tag named :ttag:`static` in Django's core set 209 of :ref:`built in template tags<ref-templates-builtins-tags>` which has 210 the same argument signature but only uses `urlparse.urljoin()`_ with the 211 :setting:`STATIC_URL` setting and the given path. This has the 212 disadvantage of not being able to easily switch the storage backend 213 without changing the templates, so in doubt use the ``staticfiles`` 214 :ttag:`static<staticfiles-static>` 215 template tag. 216 217 .. _`urlparse.urljoin()`: http://docs.python.org/library/urlparse.html#urlparse.urljoin 218 219 .. _staticfiles-development: 220 221 Serving static files in development 222 =================================== 223 224 The static files tools are mostly designed to help with getting static files 225 successfully deployed into production. This usually means a separate, 226 dedicated static file server, which is a lot of overhead to mess with when 227 developing locally. Thus, the ``staticfiles`` app ships with a 228 **quick and dirty helper view** that you can use to serve files locally in 229 development. 230 231 This view is automatically enabled and will serve your static files at 232 :setting:`STATIC_URL` when you use the built-in 233 :ref:`runserver<staticfiles-runserver>` management command. 234 235 To enable this view if you are using some other server for local development, 236 you'll add a couple of lines to your URLconf. The first line goes at the top 237 of the file, and the last line at the bottom:: 238 239 from django.contrib.staticfiles.urls import staticfiles_urlpatterns 240 241 # ... the rest of your URLconf goes here ... 242 243 urlpatterns += staticfiles_urlpatterns() 244 245 This will inspect your :setting:`STATIC_URL` setting and wire up the view 246 to serve static files accordingly. Don't forget to set the 247 :setting:`STATICFILES_DIRS` setting appropriately to let 248 ``django.contrib.staticfiles`` know where to look for files additionally to 249 files in app directories. 250 251 .. warning:: 252 253 This will only work if :setting:`DEBUG` is ``True``. 254 255 That's because this view is **grossly inefficient** and probably 256 **insecure**. This is only intended for local development, and should 257 **never be used in production**. 258 259 Additionally, when using ``staticfiles_urlpatterns`` your 260 :setting:`STATIC_URL` setting can't be empty or a full URL, such as 261 ``http://static.example.com/``. 262 263 For a few more details on how the ``staticfiles`` can be used during 264 development, see :ref:`staticfiles-development-view`. 265 266 .. _staticfiles-other-directories: 267 268 Serving other directories 269 ------------------------- 270 271 .. currentmodule:: django.views.static 272 .. function:: serve(request, path, document_root, show_indexes=False) 273 274 There may be files other than your project's static assets that, for 275 convenience, you'd like to have Django serve for you in local development. 276 The :func:`~django.views.static.serve` view can be used to serve any directory 277 you give it. (Again, this view is **not** hardened for production 278 use, and should be used only as a development aid; you should serve these files 279 in production using a real front-end webserver). 280 281 The most likely example is user-uploaded content in :setting:`MEDIA_ROOT`. 282 ``staticfiles`` is intended for static assets and has no built-in handling 283 for user-uploaded files, but you can have Django serve your 284 :setting:`MEDIA_ROOT` by appending something like this to your URLconf:: 285 286 from django.conf import settings 287 288 # ... the rest of your URLconf goes here ... 289 290 if settings.DEBUG: 291 urlpatterns += patterns('', 292 url(r'^media/(?P<path>.*)$', 'django.views.static.serve', { 293 'document_root': settings.MEDIA_ROOT, 294 }), 295 ) 296 297 Note, the snippet assumes your :setting:`MEDIA_URL` has a value of 298 ``'/media/'``. This will call the :func:`~django.views.static.serve` view, 299 passing in the path from the URLconf and the (required) ``document_root`` 300 parameter. 301 302 .. currentmodule:: django.conf.urls.static 303 .. function:: static(prefix, view='django.views.static.serve', **kwargs) 304 305 Since it can become a bit cumbersome to define this URL pattern, Django 306 ships with a small URL helper function 307 :func:`~django.conf.urls.static.static` that takes as parameters the prefix 308 such as :setting:`MEDIA_URL` and a dotted path to a view, such as 309 ``'django.views.static.serve'``. Any other function parameter will be 310 transparently passed to the view. 311 312 An example for serving :setting:`MEDIA_URL` (``'/media/'``) during 313 development:: 314 315 from django.conf import settings 316 from django.conf.urls.static import static 317 318 urlpatterns = patterns('', 319 # ... the rest of your URLconf goes here ... 320 ) + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) 321 322 .. note:: 323 324 This helper function will only be operational in debug mode and if 325 the given prefix is local (e.g. ``/static/``) and not a URL (e.g. 326 ``http://static.example.com/``). 327 328 .. _staticfiles-production: 329 330 Serving static files in production 331 ================================== 332 333 The basic outline of putting static files into production is simple: run the 334 :djadmin:`collectstatic` command when static files change, then arrange for 335 the collected static files directory (:setting:`STATIC_ROOT`) to be moved to 336 the static file server and served. 337 338 Of course, as with all deployment tasks, the devil's in the details. Every 339 production setup will be a bit different, so you'll need to adapt the basic 340 outline to fit your needs. Below are a few common patterns that might help. 341 342 Serving the app and your static files from the same server 343 ---------------------------------------------------------- 344 345 If you want to serve your static files from the same server that's already 346 serving your site, the basic outline gets modified to look something like: 347 348 * Push your code up to the deployment server. 349 * On the server, run :djadmin:`collectstatic` to copy all the static files 350 into :setting:`STATIC_ROOT`. 351 * Point your web server at :setting:`STATIC_ROOT`. For example, here's 352 :ref:`how to do this under Apache and mod_wsgi <serving-files>`. 353 354 You'll probably want to automate this process, especially if you've got 355 multiple web servers. There's any number of ways to do this automation, but 356 one option that many Django developers enjoy is `Fabric`__. 357 358 __ http://fabfile.org/ 359 360 Below, and in the following sections, we'll show off a few example fabfiles 361 (i.e. Fabric scripts) that automate these file deployment options. The syntax 362 of a fabfile is fairly straightforward but won't be covered here; consult 363 `Fabric's documentation`__, for a complete explanation of the syntax.. 364 365 __ http://docs.fabfile.org/ 366 367 So, a fabfile to deploy static files to a couple of web servers might look 368 something like:: 369 370 from fabric.api import * 371 372 # Hosts to deploy onto 373 env.hosts = ['www1.example.com', 'www2.example.com'] 374 375 # Where your project code lives on the server 376 env.project_root = '/home/www/myproject' 377 378 def deploy_static(): 379 with cd(env.project_root): 380 run('./manage.py collectstatic -v0 --noinput') 381 382 Serving static files from a dedicated server 383 -------------------------------------------- 384 385 Most larger Django apps use a separate Web server -- i.e., one that's not also 386 running Django -- for serving static files. This server often runs a different 387 type of web server -- faster but less full-featured. Some good choices are: 388 389 * lighttpd_ 390 * Nginx_ 391 * TUX_ 392 * Cherokee_ 393 * A stripped-down version of Apache_ 394 395 .. _lighttpd: http://www.lighttpd.net/ 396 .. _Nginx: http://wiki.nginx.org/Main 397 .. _TUX: http://en.wikipedia.org/wiki/TUX_web_server 398 .. _Apache: http://httpd.apache.org/ 399 .. _Cherokee: http://www.cherokee-project.com/ 400 401 Configuring these servers is out of scope of this document; check each 402 server's respective documentation for instructions. 403 404 Since your static file server won't be running Django, you'll need to modify 405 the deployment strategy to look something like: 406 407 * When your static files change, run :djadmin:`collectstatic` locally. 408 * Push your local :setting:`STATIC_ROOT` up to the static file server 409 into the directory that's being served. ``rsync`` is a good 410 choice for this step since it only needs to transfer the 411 bits of static files that have changed. 412 413 Here's how this might look in a fabfile:: 414 415 from fabric.api import * 416 from fabric.contrib import project 417 418 # Where the static files get collected locally 419 env.local_static_root = '/tmp/static' 420 421 # Where the static files should go remotely 422 env.remote_static_root = '/home/www/static.example.com' 423 424 @roles('static') 425 def deploy_static(): 426 local('./manage.py collectstatic') 427 project.rysnc_project( 428 remote_dir = env.remote_static_root, 429 local_dir = env.local_static_root, 430 delete = True 431 ) 432 433 .. _staticfiles-from-cdn: 434 435 Serving static files from a cloud service or CDN 436 ------------------------------------------------ 437 438 Another common tactic is to serve static files from a cloud storage provider 439 like Amazon's S3__ and/or a CDN (content delivery network). This lets you 440 ignore the problems of serving static files, and can often make for 441 faster-loading webpages (especially when using a CDN). 442 443 When using these services, the basic workflow would look a bit like the above, 444 except that instead of using ``rsync`` to transfer your static files to the 445 server you'd need to transfer the static files to the storage provider or CDN. 446 447 There's any number of ways you might do this, but if the provider has an API a 448 :doc:`custom file storage backend </howto/custom-file-storage>` will make the 449 process incredibly simple. If you've written or are using a 3rd party custom 450 storage backend, you can tell :djadmin:`collectstatic` to use it by setting 451 :setting:`STATICFILES_STORAGE` to the storage engine. 452 453 For example, if you've written an S3 storage backend in 454 ``myproject.storage.S3Storage`` you could use it with:: 455 456 STATICFILES_STORAGE = 'myproject.storage.S3Storage' 457 458 Once that's done, all you have to do is run :djadmin:`collectstatic` and your 459 static files would be pushed through your storage package up to S3. If you 460 later needed to switch to a different storage provider, it could be as simple 461 as changing your :setting:`STATICFILES_STORAGE` setting. 462 463 For details on how you'd write one of these backends, 464 :doc:`/howto/custom-file-storage`. 465 466 .. seealso:: 467 468 The `django-storages`__ project is a 3rd party app that provides many 469 storage backends for many common file storage APIs (including `S3`__). 470 471 __ http://s3.amazonaws.com/ 472 __ http://code.larlet.fr/django-storages/ 473 __ http://django-storages.readthedocs.org/en/latest/backends/amazon-S3.html 474 475 Upgrading from ``django-staticfiles`` 476 ===================================== 477 478 ``django.contrib.staticfiles`` began its life as `django-staticfiles`_. If 479 you're upgrading from `django-staticfiles`_ older than 1.0 (e.g. 0.3.4) to 480 ``django.contrib.staticfiles``, you'll need to make a few changes: 481 482 * Application files should now live in a ``static`` directory in each app 483 (`django-staticfiles`_ used the name ``media``, which was slightly 484 confusing). 485 486 * The management commands ``build_static`` and ``resolve_static`` are now 487 called :djadmin:`collectstatic` and :djadmin:`findstatic`. 488 489 * The settings ``STATICFILES_PREPEND_LABEL_APPS``, 490 ``STATICFILES_MEDIA_DIRNAMES`` and ``STATICFILES_EXCLUDED_APPS`` were 491 removed. 492 493 * The setting ``STATICFILES_RESOLVERS`` was removed, and replaced by the 494 new :setting:`STATICFILES_FINDERS`. 495 496 * The default for :setting:`STATICFILES_STORAGE` was renamed from 497 ``staticfiles.storage.StaticFileStorage`` to 498 ``staticfiles.storage.StaticFilesStorage`` 499 500 * If using :ref:`runserver<staticfiles-runserver>` for local development 501 (and the :setting:`DEBUG` setting is ``True``), you no longer need to add 502 anything to your URLconf for serving static files in development. 503 504 Learn more 505 ========== 506 507 This document has covered the basics and some common usage patterns. For 508 complete details on all the settings, commands, template tags, and other pieces 509 include in ``django.contrib.staticfiles``, see :doc:`the staticfiles reference 510 </ref/contrib/staticfiles>`. -
docs/topics/testing.txt
diff --git a/docs/topics/testing.txt b/docs/topics/testing.txt index 829e059..a72a2b7 100644
a b out the `full reference`_ for more details. 1946 1946 .. note:: 1947 1947 1948 1948 ``LiveServerTestCase`` makes use of the :doc:`staticfiles contrib app 1949 </ howto/static-files>` so you'll need to have your project configured1949 </topics/files/static>` so you'll need to have your project configured 1950 1950 accordingly (in particular by setting :setting:`STATIC_URL`). 1951 1951 1952 1952 .. note::