Merge branch 'master' into releases/1.2.x

Author: spectras

README.rst

@@ -28,6 +28,9 @@ Features
 * **Reliable** - more than 300 test cases and counting. |coverage| |build|
 * **Compatible** with Django 1.4 to 1.8, running Python 2.7, 3.3 or 3.4.
 
+Django-hvad also features support for `Django REST framework`_ 3.1 or newer, including
+translation-aware serializers.
+
 Example Uses
 ------------
 
@@ -133,6 +136,7 @@ Jonas Obrist (https://github.com/ojii) for making django-nani and for helping me
 .. _release notes: https://django-hvad.readthedocs.org/en/latest/public/release_notes.html
 .. _issue tracker: https://github.com/KristianOellegaard/django-hvad/issues
 .. _PyPI: https://pypi.python.org/pypi/django-hvad
+.. _Django REST framework: http://www.django-rest-framework.org/
 .. _installation guide: http://django-hvad.readthedocs.org/en/latest/public/installation.html
 .. _quickstart guide: http://django-hvad.readthedocs.org/en/latest/public/quickstart.html
 

docs/conf.py

@@ -11,7 +11,9 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
+import sys, os, sphinx
+
+readthedocs = os.environ.get('READTHEDOCS', None) == 'True'
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
@@ -23,156 +25,51 @@
 
 # -- General configuration -----------------------------------------------------
 
-# If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = '1.0'
-
-# Add any Sphinx extension module names here, as strings. They can be extensions
-# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.intersphinx', 'djangodocs', 'github']
+extensions = [
+    'sphinx.ext.intersphinx',
+    'djangodocs',
+    'github'
+]
 intersphinx_mapping = {
     'python': ('http://docs.python.org/2.7', None),
     'django': ('http://readthedocs.org/docs/django/en/latest/', None),
 }
 
-# Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
-
-# The suffix of source filenames.
 source_suffix = '.rst'
-
-# The encoding of source files.
-#source_encoding = 'utf-8-sig'
-
-# The master toctree document.
+exclude_patterns = ['_build']
 master_doc = 'index'
 
 # General information about the project.
 project = u'django-hvad'
 copyright = u'2011-2015, Kristian Øllegaard, Jonas Obrist & contributors'
 
-# The version info for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents.
-#
-# The short X.Y version.
 version = '1.2'
-# The full version, including alpha/beta/rc tags.
 release = '1.2.0'
 
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-exclude_patterns = ['_build']
-
-# The reST default role (used for this markup: `text`) to use for all documents.
-#default_role = None
-
-# If true, '()' will be appended to :func: etc. cross-reference text.
-#add_function_parentheses = True
-
-# If true, the current module name will be prepended to all description
-# unit titles (such as .. function::).
-#add_module_names = True
-
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'trac'
 
-# A list of ignored prefixes for module index sorting.
-#modindex_common_prefix = []
-
-
 # -- Options for HTML output ---------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-html_theme = 'classic'
-
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
+if sphinx.version_info >= (1, 3):
+    html_theme = 'default' if readthedocs else 'classic'
+else:
+    html_theme = 'default'
 html_theme_options = {
     'externalrefs': True,
 }
 
 html_style = 'stylesheet.css'
-
-# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-#html_title = None
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-#html_short_title = None
-
-# The name of an image file (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-
-# If true, SmartyPants will be used to convert quotes and dashes to
-# typographically correct entities.
 html_use_smartypants = True
+html_show_sourcelink = False
 
 # Custom sidebar templates, maps document names to template names.
 html_sidebars = {'**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']}
 
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_domain_indices = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-html_show_sourcelink = False
-
-# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-#html_show_sphinx = True
-
-# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# This is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = None
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'Projectdoc'
@@ -193,29 +90,6 @@
    u'Jonas Obrist & contributors', 'manual'),
 ]
 
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# If true, show page references after internal links.
-#latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-#latex_show_urls = False
-
-# Additional stuff for the LaTeX preamble.
-#latex_preamble = ''
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_domain_indices = True
-
 
 # -- Options for manual page output --------------------------------------------
 

docs/internal/index.rst

@@ -31,4 +31,5 @@ This part of the documentation is grouped by file, not by topic.
     forms
     manager
     models
+    query
     utils

docs/internal/manager.rst

@@ -542,6 +542,20 @@ FallbackQueryset
     A queryset that can optionally use fallbacks and by default only fetches the
     :term:`Shared Model`.
 
+    There are actually two underlying implementations, the ``LegacyFallbackQueryset``
+    and the ``SelfJoinFallbackQueryset``. Implementation is chosen at initialization
+    based on the ``HVAD_LEGACY_FALLBACKS`` setting. It defaults to ``False``
+    (use SelfJoin) on Django 1.6 and newer, and ``True`` (use Legacy) on older
+    versions.
+
+    The ``LegacyFallbackQueryset`` generates lots of queries as it walks through
+    batches of models, fetches their translations and matches them onto the models.
+
+    The ``SelfJoinFallbackQueryset`` uses a single self outer join to achieve the same
+    result in only one (complex) query. Performance is good as the number of items
+    per model in the cross-product is limited to the number of languages that
+    Django supports. Implementation digs deeper into Django internals, though.
+
     .. attribute:: _translation_fallbacks
 
         List of fallbacks to use (or ``None``).
@@ -571,26 +585,6 @@ FallbackQueryset
         Injects *translation_fallbacks* into *kwargs* and calls the superclass.
 
 
-**************************
-TranslationFallbackManager
-**************************
-
-.. warning:: This class is deprecated and will be removed in next release.
-                Please use :meth:`~hvad.manager.TranslationManager.untranslated`
-                instead.
-
-.. class:: TranslationFallbackManager
-
-    .. method:: use_fallbacks(self, *fallbacks)
-    
-        Proxies to :meth:`FallbackQueryset.use_fallbacks` by calling
-        :meth:`get_queryset` first.
-
-    .. method:: get_queryset(self)
-    
-        Returns an instance of :class:`FallbackQueryset` for this manager.
-
-
 ************************
 TranslationAwareQueryset
 ************************
@@ -742,7 +736,9 @@ TranslationAwareQueryset
         object provided in *extra_filters* and returns a queryset from the
         superclass, so that the methods that call this method can directely
         access methods on the superclass to reduce boilerplate code.
-    
+
+        .. warning:: This internal method returns a ``super()`` proxy object,
+                     be sure to understand the implications before using it.
 
 ***********************
 TranslationAwareManager

docs/internal/query.rst

@@ -0,0 +1,43 @@
+#################
+:mod:`hvad.query`
+#################
+
+.. module:: hvad.query
+
+This modules containts abstractions for accessing some internal parts of Django
+ORM that are used in hvad. The intent is that anytime some code in hvad needs
+to access some Django internals, it should do so through a function in this module.
+
+.. function:: query_terms(model, path)
+
+    This iterator yields all terms in the specified ``path``, along with full
+    introspection data. Each term is output as a named tuple with the following
+    members:
+
+    * ``depth``:  how deep in the path is this term. Counted from zero.
+    * ``term``: the term string.
+    * ``model: `` the model the term is attached to. It will start with passed
+      ``model`` then walk through relations as terms are enumerated.
+    * ``field``: the actual field, on the model, the term refers to.
+    * ``translated``: whether the field is a translated field (True) or a shared fielf (False).
+    * ``target``: the target model of the relation, or ``None`` if not a relational field.
+    * ``many``: whether the target can be multiple (that is, it is a M2M or reverse FK).
+
+    If a field is not recognized, it is assumed the path is complete and everything
+    that follows is a query expression (such as ``__year__in``). Query expression
+    terms will be yielded with ``field`` set to ``None``.
+
+.. function:: q_children(q)
+
+    Iterator that recursively yields all key-value pairs of a ``Q`` object. Each
+    pair is yielded as a 3-tuple: the pair itself, its container and its index in
+    the container. This allows modifying it.
+
+.. function:: expression_nodes(expression)
+
+    Iterator that recursively yields all nodes in an expression tree.
+
+.. function:: where_node_children(node)
+
+    Iterator that recursively yields all fields of a where node. It is used to
+    determine whether a custom ``Q`` object included a ``language_code`` filter.

docs/internal/utils.rst

@@ -42,9 +42,9 @@
 
     Returns the translation for an instance.
 
-    * If ``enforce`` is false, then ``language`` is used as a default language,
+    * If ``enforce`` is False, then ``language`` is used as a default language,
       if the ``instance`` has no language currently loaded.
-    * If ``enforce`` is true, then ``language`` will be enforced upon the
+    * If ``enforce`` is True, then ``language`` will be enforced upon the
       translation, ignoring cached translation if it is not in the given
       language.
 
@@ -66,11 +66,47 @@
     (meta) of Django models that raises a more useful exception when one tries
     to access translated fields with the wrong manager.
 
+    This descriptor is pending deprecation as the associated method is being
+    removed from Django.
+
     .. method:: __init__(self, real)
+
+        Retains a reference to the actual method this descriptor is replacing.
 
     .. method:: __call__(self, meta, name)
 
-.. function:: permissive_field_by_name(self, name)
-    
-    Returns the field from the :term:`Shared Model` or
-    :term:`Translations Model`, if it is on either.
+        Catches improper use of the ``get_field_by_name`` method to access
+        translated fields and raise a ``WrongManager`` exception.
+
+.. class:: SmartGetField
+
+    Smart version of the standard :meth:`get_field` on the options
+    (meta) of Django models that raises a more useful exception when one tries
+    to access translated fields with the wrong manager.
+
+    .. method:: __init__(self, real)
+
+        Retains a reference to the actual method this descriptor is replacing.
+
+    .. method:: __call__(self, meta, name)
+
+        Catches improper use of the ``get_field`` method to access
+        translated fields and raise a ``WrongManager`` exception.
+
+.. class:: _MinimumDjangoVersionDescriptor
+
+    Helper class used by :func:`minimumDjangoVersion` decorator.
+
+.. function:: minimumDjangoVersion(*args)
+
+    Decorator that will catch attempts to use methods on a Django version that
+    does not support them and raise a helpful exception.
+
+    Arguments must be the minimum allowable Django version, the will be compared
+    against the ``django.VERSION`` tuple.
+
+.. function:: settings_updater(func):
+
+    Decorator for setting globals depending on Django settings. It simply invokes
+    the decorated function immediately, then calls it again every time the
+    ``setting_changed`` signal is sent by Django.