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