ssify/variables.py

   1 # -*- coding: utf-8 -*-
   2 # This file is part of django-ssify, licensed under GNU Affero GPLv3 or later.
   3 # Copyright © Fundacja Nowoczesna Polska. See README.md for more information.
   4 #
   5 """
   6 Utilities for defining SSI variables.
   7
   8 SSI variables are a way of providing values that need to be computed
   9 at request time to the prerendered templates.
  10
  11 """
  12 from __future__ import unicode_literals
  13 from hashlib import md5
  14 from django import template
  15 from django.utils.encoding import force_text, python_2_unicode_compatible
  16 from django.utils.functional import Promise
  17 from django.utils.safestring import mark_safe
  18 from .exceptions import SsiVarsDependencyCycleError
  19
  20
  21 @python_2_unicode_compatible
  22 class SsiVariable(object):
  23     """
  24     Represents a variable computed by a template tag with given arguments.
  25
  26     Instance of this class is returned from any template tag created
  27     with `decorators.ssi_variable` decorator. If renders as SSI echo
  28     statement, but you can also use it as an argument to {% ssi_include %},
  29     to other ssi_variable, or create SSI if statements by using
  30     its `if`, `else`, `endif` properties.
  31
  32     Variable's name, as used in SSI statements, is a hash of its definition,
  33     so the user never has to deal with it directly.
  34
  35     """
  36     def __init__(self, tagpath=None, args=None, kwargs=None, name=None):
  37         self.tagpath = tagpath
  38         self.args = list(args or [])
  39         self.kwargs = kwargs or {}
  40         self._name = name
  41
  42     @property
  43     def name(self):
  44         """Variable name is a hash of its definition."""
  45         if self._name is None:
  46             self._name = 'v' + md5(json_encode(self.definition).encode('ascii')).hexdigest()
  47         return self._name
  48
  49     def rehash(self):
  50         """
  51         Sometimes there's a need to reset the variable name.
  52
  53         Typically, this is the case after finding real values for
  54         variables passed as arguments to {% ssi_include %}.
  55         """
  56         self._name = None
  57         return self.name
  58
  59     @property
  60     def definition(self):
  61         """Variable is defined by path to template tag and its arguments."""
  62         if self.kwargs:
  63             return self.tagpath, self.args, self.kwargs
  64         elif self.args:
  65             return self.tagpath, self.args
  66         else:
  67             return self.tagpath,
  68
  69     def __repr__(self):
  70         return "SsiVariable(%s: %s)" % (self.name, repr(self.definition))
  71
  72     def get_value(self, request):
  73         """Computes the real value of the variable, using the request."""
  74         taglib, tagname = self.tagpath.rsplit('.', 1)
  75         return template.get_library(taglib).tags[tagname].get_value(
  76             request, *self.args, **self.kwargs)
  77
  78     def __str__(self):
  79         return mark_safe("<!--#echo var='%s' encoding='none'-->" % self.name)
  80
  81     def as_var(self):
  82         """Returns the form that can be used in SSI include's URL."""
  83         return '${%s}' % self.name
  84
  85 # If-else-endif properties for use in templates.
  86 setattr(SsiVariable, 'if',
  87         lambda self: mark_safe("<!--#if expr='${%s}'-->" % self.name))
  88 setattr(SsiVariable, 'else',
  89         staticmethod(lambda: mark_safe("<!--#else-->")))
  90 setattr(SsiVariable, 'endif',
  91         staticmethod(lambda: mark_safe('<!--#endif-->')))
  92
  93
  94 class SsiExpect(object):
  95     """This class says: I want the real value of this variable here."""
  96     def __init__(self, name):
  97         self.name = name
  98     def __repr__(self):
  99         return "SsiExpect(%s)" % (self.name,)
 100
 101
 102 def ssi_expect(var, type_):
 103     """
 104     Helper function for defining get_ssi_vars on ssi_included views.
 105
 106     The view needs a way of calculating all the needed variables from
 107     the view args. But the args are probably the wrong type
 108     (typically, str instead of int) or even are SsiVariables, not
 109     resolved until request time.
 110
 111     This function provides a way to expect a real value of the needed type.
 112
 113     """
 114     if isinstance(var, SsiVariable):
 115         return SsiExpect(var.name)
 116     else:
 117         return type_(var)
 118
 119
 120 class SsiVariableNode(template.Node):
 121     """ Node for the SsiVariable tags. """
 122     def __init__(self, tagpath, args, kwargs, patch_response=None, asvar=None):
 123         self.tagpath = tagpath
 124         self.args = args
 125         self.kwargs = kwargs
 126         self.patch_response = patch_response
 127         self.asvar = asvar
 128
 129     def __repr__(self):
 130         return "<SsiVariableNode>"
 131
 132     def render(self, context):
 133         """Renders the tag as SSI echo or sets the context variable."""
 134         resolved_args = [var.resolve(context) for var in self.args]
 135         resolved_kwargs = dict((k, v.resolve(context))
 136                                for k, v in self.kwargs.items())
 137         var = SsiVariable(self.tagpath, resolved_args, resolved_kwargs)
 138
 139         request = context['request']
 140         if not hasattr(request, 'ssi_vars_needed'):
 141             request.ssi_vars_needed = {}
 142         request.ssi_vars_needed[var.name] = var
 143         if self.patch_response:
 144             if not hasattr(request, 'ssi_patch_response'):
 145                 request.ssi_patch_response = []
 146             request.ssi_patch_response.extend(self.patch_response)
 147
 148         if self.asvar:
 149             context.dicts[0][self.asvar] = var
 150             return ''
 151         else:
 152             return var
 153
 154
 155 def ssi_set_statement(var, value):
 156     """Generates an SSI set statement for a variable."""
 157     if isinstance(value, Promise):
 158         # Yes, this is quite brutal. But we need to know
 159         # the real value now, we don't know the type,
 160         # and we only want to evaluate the lazy function once.
 161         value = value._proxy____cast()
 162     if value is False or value is None:
 163         value = ''
 164     return "<!--#set var='%s' value='%s'-->" % (
 165         var,
 166         force_text(value).replace('\\', '\\\\').replace("'", "\\'"))
 167
 168
 169 def provide_vars(request, ssi_vars):
 170     """
 171     Provides all the SSI set statements for ssi_vars variables.
 172
 173     The main purpose of this function is to by called by SsifyMiddleware.
 174     """
 175     def resolve_expects(var):
 176         if not hasattr(var, 'hash_dirty'):
 177             var.hash_dirty = False
 178
 179         for i, arg in enumerate(var.args):
 180             if isinstance(arg, SsiExpect):
 181                 var.args[i] = resolved[arg.name]
 182                 var.hash_dirty = True
 183         for k, arg in var.kwargs.items():
 184             if isinstance(arg, SsiExpect):
 185                 var.kwargs[k] = resolved[arg.name]
 186                 var.hash_dirty = True
 187
 188         for arg in var.args + list(var.kwargs.values()):
 189             if isinstance(arg, SsiVariable):
 190                 var.hash_dirty = resolve_expects(arg) or var.hash_dirty
 191
 192         hash_dirty = var.hash_dirty
 193         if var.hash_dirty:
 194             # Rehash after calculating the SsiExpects with real
 195             # values, because that's what the included views expect.
 196             var.rehash()
 197             var.hash_dirty = False
 198
 199         return hash_dirty
 200
 201     def resolve_args(var):
 202         kwargs = {}
 203         for k, arg in var.kwargs.items():
 204             kwargs[k] = resolved[arg.name] if isinstance(arg, SsiVariable) else arg
 205         new_var = SsiVariable(var.tagpath,
 206             [resolved[arg.name] if isinstance(arg, SsiVariable) else arg for arg in var.args],
 207             kwargs)
 208         return new_var
 209
 210     resolved = {}
 211     queue = list(ssi_vars.values())
 212
 213     unresolved_streak = 0
 214     while queue:
 215         var = queue.pop(0)
 216         try:
 217             resolve_expects(var)
 218             rv = resolve_args(var)
 219         except KeyError as e:
 220             queue.append(var)
 221             unresolved_streak += 1
 222             if unresolved_streak > len(queue):
 223                 raise SsiVarsDependencyCycleError(request, queue, resolved)
 224             continue
 225
 226         resolved[var.name] = rv.get_value(request)
 227         unresolved_streak = 0
 228
 229     output = "".join(ssi_set_statement(var, value)
 230                       for (var, value) in resolved.items()
 231                       ).encode('utf-8')
 232     return output
 233
 234
 235 from .serializers import json_encode