Browse files

Addressed inaccuracies in performance docs

* Move the discussion of CachedStaticFilesStorage to the section about
  HTTP. It's really about client-side caching. It doesn't fit with the
  caching utilities from django.utils.functional.

* Tone down the warning against Pypy as per Alex' feedback. It's a valid
  choice for advanced users who are comfortable using a non-standard

* Generally reworded the 'Using different versions of available software'

* Some other minor adjustments to the document.
  • Loading branch information...
1 parent a991b01 commit 11187386f466075f37cf69a0e99a341c30cdf7ef @aaugustin aaugustin committed with evildmp Sep 21, 2013
Showing with 68 additions and 34 deletions.
  1. +68 −34 docs/topics/performance.txt
@@ -150,8 +150,8 @@ so there can be huge benefit in saving the value to a quickly accessible cache,
ready for the next time it's required.
It's a sufficiently significant and powerful technique that Django includes a
-comprehensive caching framework, as well as numerous other opportunities to
-make use of caching.
+comprehensive caching framework, as well as other smaller pieces of caching
:doc:`The caching framework </topics/cache>`
@@ -168,14 +168,8 @@ Implementing caching should not be regarded as an alternative to improving code
that's performing poorly because it has been written badly. It's one of the
final steps towards producing well-performing code, not a shortcut.
-Other opportunities for caching
-Beyond the caching framework, Django offers other smaller pieces of caching
It's common to have to call a class instances's method more than once. If
that function is expensive, then doing so can be wasteful.
@@ -186,14 +180,8 @@ the saved value rather than re-computing it. Note that this only works on
methods that take ``self`` as their only argument and that it changes the
method to a property.
-:class:`` appends a
-content-dependent tag to the filenames of :doc:`static files
-</ref/contrib/staticfiles>` to make it safe for browsers to cache them
-long-term without missing future changes - when a file changes, so will the
-tag, so browsers will reload the asset automatically.
+Certain Django components also have their own caching functionality; these are
+discussed below in the sections related to those components.
Understanding laziness
@@ -284,11 +272,31 @@ time. Note that GZipMiddleware is currently considered a security risk, and is
vulnerable to attacks that nullify the protection provided by TLS/SSL. See the
warning in :class:`~django.middleware.gzip.GZipMiddleware` for more information.
-Third-party HTTP tools
+Static files
+Static files, which by defintion are not dynamic, make an excellent target for
+optimization gains.
+By taking advantage of web browsers' caching abilities, you can
+eliminate network hits entirely for a given file after the initial download.
+:class:`` appends a
+content-dependent tag to the filenames of :doc:`static files
+</ref/contrib/staticfiles>` to make it safe for browsers to cache them
+long-term without missing future changes - when a file changes, so will the
+tag, so browsers will reload the asset automatically.
-There are numerous third-party Django tools and packages available, notably
-ones that are able to "minify" and compress HTML, CSS and JavaScript.
+Several third-party Django tools and packages provide the ability to "minify"
+HTML, CSS, and JavaScript. They remove uneccessary whitespace, newlines, and
+comments, and shorten variable names, and thus reduce the size of the documents
+that your site publishes.
Template performance
@@ -313,13 +321,19 @@ Using different versions of available software
It can sometimes be worth checking whether different and better-performing
versions of the software that you're using are available.
-This may be helpful, but is unlikely to solve a serious performance problem.
-You won't usually gain performance advantages that are better than marginal.
+These techniques are targeted at more advanced users who want to push the
+boundaries of performance of an already well-optimized Django site.
+However, they are not magic solutions to performance problems, and they're
+unlikely to bring better than marginal gains to sites that don't already do the
+more basic things the right way.
.. note::
It's worth repeating: **reaching for alternatives to software you're
- already using is very rarely the answer to performance problems**.
+ already using is never the first answer to performance problems**. When
+ you reach this level of optimization, you need a formal benchmarking
+ solution.
Newer is often - but not always - better
@@ -369,16 +383,36 @@ templating language.
Alternative software implementations
-It *may* be worth checking whether Python software you're using has been
+It may be worth checking whether Python software you're using has been
provided in a different implementation that can execute the same code faster.
-However, most Django performance problems in well-written code are typically
-not to be found at the Python execution level, but rather in inefficient
-database querying, caching, and templates (and if you're relying on
-poorly-written Python code, your performance problems are very unlikely to be
-solved by having it execute faster).
+However: most performance problems in well-written Django sites aren't at the
+Python execution level, but rather in inefficient database querying, caching,
+and templates. If you're relying on poorly-written Python code, your
+performance problems are unlikely to be solved by having it execute faster.
+Using an alternative implementation may introduce compatibility, deployment,
+portability, or maintenance issues. It goes without saying that before adopting
+a non-standard implementation you should ensure it provides sufficient
+performance gains for your application to outweigh the potential risks.
+With these caveats in mind, you should be aware of:
+`PyPy <>`_
+`PyPy <>`_ is an implementation of Python in Python itself (the
+'standard' Python implementation is in C). PyPy can offer substantial
+performance gains, typically for heavyweight applications.
+A key aim of the PyPy project is `compatibility
+<http:://>`_ with existing Python APIs and libraries.
+Django is compatible, but you will need to check the compatibility of other
+libraries you rely on.
+C implementations of Python libraries
-Avoid using C implementations of Python libraries or non-standard Python
-implementations like `PyPy <>`_ in search of performance gains,
-unless you are sure they are appropriate for your application. Any gains are
-likely to be small, and compatibility issues are common.
+Some Python libraries are also implemented in C, and can be much faster. They
+aim to offer the same APIs. Note that compatibility issues and behaviour
+differences are not unknown (and not always immediately evident).

0 comments on commit 1118738

Please sign in to comment.