From aa772a5c215024331fb75c97305c00f7d09471dc Mon Sep 17 00:00:00 2001
From: Daniel Lindsley <daniel@toastdriven.com>
Date: Sun, 28 Jul 2013 14:24:20 -0700
Subject: [PATCH] Added Python 3 compatibility notes.

---
 docs/index.rst   |  1 +
 docs/python3.rst | 59 ++++++++++++++++++++++++++++++++++++++++++++++++
 docs/toc.rst     |  1 +
 3 files changed, 61 insertions(+)
 create mode 100644 docs/python3.rst

diff --git a/docs/index.rst b/docs/index.rst
index 25cc44d38..ae83c654b 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -44,6 +44,7 @@ you up and running:
    debugging
 
    migration_from_1_to_2
+   python3
    contributing
 
 
diff --git a/docs/python3.rst b/docs/python3.rst
new file mode 100644
index 000000000..23c288065
--- /dev/null
+++ b/docs/python3.rst
@@ -0,0 +1,59 @@
+.. _ref-python3:
+
+================
+Python 3 Support
+================
+
+As of Haystack v2.1.0, it has been ported to support both Python 2 & Python 3
+within the same codebase. This builds on top of what `six`_ & `Django`_ provide.
+
+No changes are required for anyone running an existing Haystack
+installation. The API is completely backward-compatible, so you should be able
+to run your existing software without modification.
+
+Virtually all tests pass under both Python 2 & 3, with a small number of
+expected failures under Python (typically related to ordering, see below).
+
+.. _`six`: http://pythonhosted.org/six/
+.. _`Django`: https://docs.djangoproject.com/en/1.5/topics/python3/#str-and-unicode-methods
+
+
+Supported Backends
+==================
+
+The following backends are fully supported under Python 3. However, you may
+need to update these dependencies if you have a pre-existing setup.
+
+* Solr (pysolr>=3.1.0)
+* Elasticsearch (pyelasticsearch>=0.5)
+
+
+Partially Supported Backends
+============================
+
+Most aspects of Whoosh work fine under Python 3. However, the built-in
+highlighting fails under Python 3.3.2. Using the Haystack-provided template tag
+highlighting is a good stopgap until
+https://bitbucket.org/mchaput/whoosh/324/highlighting-under-python-3-fails is
+resolved.
+
+* Whoosh (whoosh>=2.5.0)
+
+
+Notes
+=====
+
+Testing
+-------
+
+If you were testing things such as the query generated by a given
+``SearchQuerySet`` or how your forms would render, under Python 3.3.2+,
+`hash randomization`_ is in effect, which means that the ordering of
+dictionaries is no longer consistent, even on the same platform.
+
+Haystack took the approach of abandoning making assertions about the entire
+structure. Instead, we either simply assert that the new object contains the
+right things or make a call to ``sorted(...)`` around it to ensure order. It is
+recommended you take a similar approach.
+
+.. _`hash randomization`: http://docs.python.org/3/whatsnew/3.3.html#builtin-functions-and-types
diff --git a/docs/toc.rst b/docs/toc.rst
index 021e5b5cb..46ed9bba8 100644
--- a/docs/toc.rst
+++ b/docs/toc.rst
@@ -20,6 +20,7 @@ Table Of Contents
    debugging
 
    migration_from_1_to_2
+   python3
    contributing
 
    best_practices