philo/models/nodes.py

   1 from inspect import getargspec
   2
   3 from django.contrib.contenttypes import generic
   4 from django.contrib.contenttypes.models import ContentType
   5 from django.contrib.sites.models import Site, RequestSite
   6 from django.core.exceptions import ValidationError
   7 from django.core.servers.basehttp import FileWrapper
   8 from django.core.urlresolvers import resolve, clear_url_caches, reverse, NoReverseMatch
   9 from django.db import models
  10 from django.http import HttpResponse, HttpResponseServerError, HttpResponseRedirect, Http404
  11 from django.template import add_to_builtins as register_templatetags
  12 from django.utils.encoding import smart_str
  13
  14 from philo.exceptions import MIDDLEWARE_NOT_CONFIGURED, ViewCanNotProvideSubpath, ViewDoesNotProvideSubpaths
  15 from philo.models.base import TreeEntity, Entity, QuerySetMapper, register_value_model
  16 from philo.models.fields import JSONField
  17 from philo.utils import ContentTypeSubclassLimiter
  18 from philo.validators import RedirectValidator
  19 from philo.signals import view_about_to_render, view_finished_rendering
  20
  21
  22 _view_content_type_limiter = ContentTypeSubclassLimiter(None)
  23
  24
  25 class Node(TreeEntity):
  26         """
  27         :class:`Node`\ s are the basic building blocks of a website using Philo. They define the URL hierarchy and connect each URL to a :class:`View` subclass instance which is used to generate an HttpResponse.
  28
  29         """
  30         view_content_type = models.ForeignKey(ContentType, related_name='node_view_set', limit_choices_to=_view_content_type_limiter)
  31         view_object_id = models.PositiveIntegerField()
  32         #: :class:`GenericForeignKey` to a non-abstract subclass of :class:`View`
  33         view = generic.GenericForeignKey('view_content_type', 'view_object_id')
  34
  35         @property
  36         def accepts_subpath(self):
  37                 """A property shortcut for :attr:`self.view.accepts_subpath <View.accepts_subpath>`"""
  38                 if self.view:
  39                         return self.view.accepts_subpath
  40                 return False
  41
  42         def handles_subpath(self, subpath):
  43                 return self.view.handles_subpath(subpath)
  44
  45         def render_to_response(self, request, extra_context=None):
  46                 """This is a shortcut method for :meth:`View.render_to_response`"""
  47                 return self.view.render_to_response(request, extra_context)
  48
  49         def get_absolute_url(self, request=None, with_domain=False, secure=False):
  50                 """
  51                 This is essentially a shortcut for calling :meth:`construct_url` without a subpath.
  52
  53                 :returns: The absolute url of the node on the current site.
  54
  55                 """
  56                 return self.construct_url(request=request, with_domain=with_domain, secure=secure)
  57
  58         def construct_url(self, subpath="/", request=None, with_domain=False, secure=False):
  59                 """
  60                 This method will do its best to construct a URL based on the Node's location. If with_domain is True, that URL will include a domain and a protocol; if secure is True as well, the protocol will be https. The request will be used to construct a domain in cases where a call to :meth:`Site.objects.get_current` fails.
  61
  62                 Node urls will not contain a trailing slash unless a subpath is provided which ends with a trailing slash. Subpaths are expected to begin with a slash, as if returned by :func:`django.core.urlresolvers.reverse`.
  63
  64                 :meth:`construct_url` may raise the following exceptions:
  65
  66                 - :class:`NoReverseMatch` if "philo-root" is not reversable -- for example, if :mod:`philo.urls` is not included anywhere in your urlpatterns.
  67                 - :class:`Site.DoesNotExist <ObjectDoesNotExist>` if with_domain is True but no :class:`Site` or :class:`RequestSite` can be built.
  68                 - :class:`~philo.exceptions.AncestorDoesNotExist` if the root node of the site isn't an ancestor of the node constructing the URL.
  69
  70                 :param string subpath: The subpath to be constructed beyond beyond the node's URL.
  71                 :param request: :class:`HttpRequest` instance. Will be used to construct a :class:`RequestSite` if :meth:`Site.objects.get_current` fails.
  72                 :param with_domain: Whether the constructed URL should include a domain name and protocol.
  73                 :param secure: Whether the protocol, if included, should be http:// or https://.
  74                 :returns: A constructed url for accessing the given subpath of the current node instance.
  75
  76                 """
  77                 # Try reversing philo-root first, since we can't do anything if that fails.
  78                 root_url = reverse('philo-root')
  79
  80                 try:
  81                         current_site = Site.objects.get_current()
  82                 except Site.DoesNotExist:
  83                         if request is not None:
  84                                 current_site = RequestSite(request)
  85                         elif with_domain:
  86                                 # If they want a domain and we can't figure one out,
  87                                 # best to reraise the error to let them know.
  88                                 raise
  89                         else:
  90                                 current_site = None
  91
  92                 root = getattr(current_site, 'root_node', None)
  93                 path = self.get_path(root=root)
  94
  95                 if current_site and with_domain:
  96                         domain = "http%s://%s" % (secure and "s" or "", current_site.domain)
  97                 else:
  98                         domain = ""
  99
 100                 if not path or subpath == "/":
 101                         subpath = subpath[1:]
 102
 103                 return '%s%s%s%s' % (domain, root_url, path, subpath)
 104
 105         class Meta:
 106                 app_label = 'philo'
 107
 108
 109 # the following line enables the selection of a node as the root for a given django.contrib.sites Site object
 110 models.ForeignKey(Node, related_name='sites', null=True, blank=True).contribute_to_class(Site, 'root_node')
 111
 112
 113 class View(Entity):
 114         """
 115         :class:`View` is an abstract model that represents an item which can be "rendered", generally in response to an :class:`HttpRequest`.
 116
 117         """
 118         #: A generic relation back to nodes.
 119         nodes = generic.GenericRelation(Node, content_type_field='view_content_type', object_id_field='view_object_id')
 120
 121         #: Property or attribute which defines whether this :class:`View` can handle subpaths. Default: ``False``
 122         accepts_subpath = False
 123
 124         def handles_subpath(self, subpath):
 125                 """Returns True if the :class:`View` handles the given subpath, and False otherwise."""
 126                 if not self.accepts_subpath and subpath != "/":
 127                         return False
 128                 return True
 129
 130         def reverse(self, view_name=None, args=None, kwargs=None, node=None, obj=None):
 131                 """
 132                 If :attr:`accepts_subpath` is True, try to reverse a URL using the given parameters using ``self`` as the urlconf.
 133
 134                 If ``obj`` is provided, :meth:`get_reverse_params` will be called and the results will be combined with any ``view_name``, ``args``, and ``kwargs`` that may have been passed in.
 135
 136                 This method will raise the following exceptions:
 137
 138                 - :class:`~philo.exceptions.ViewDoesNotProvideSubpaths` if :attr:`accepts_subpath` is False.
 139                 - :class:`~philo.exceptions.ViewCanNotProvideSubpath` if a reversal is not possible.
 140
 141                 :param view_name: The name of the view to be reversed.
 142                 :param args: Extra args for reversing the view.
 143                 :param kwargs: A dictionary of arguments for reversing the view.
 144                 :param node: The node whose subpath this is.
 145                 :param obj: An object to be passed to :meth:`get_reverse_params` to generate a view_name, args, and kwargs for reversal.
 146                 :returns: A subpath beyond the node that reverses the view, or an absolute url that reverses the view if a node was passed in.
 147
 148                 """
 149                 if not self.accepts_subpath:
 150                         raise ViewDoesNotProvideSubpaths
 151
 152                 if obj is not None:
 153                         # Perhaps just override instead of combining?
 154                         obj_view_name, obj_args, obj_kwargs = self.get_reverse_params(obj)
 155                         if view_name is None:
 156                                 view_name = obj_view_name
 157                         args = list(obj_args) + list(args or [])
 158                         obj_kwargs.update(kwargs or {})
 159                         kwargs = obj_kwargs
 160
 161                 try:
 162                         subpath = reverse(view_name, urlconf=self, args=args or [], kwargs=kwargs or {})
 163                 except NoReverseMatch, e:
 164                         raise ViewCanNotProvideSubpath(e.message)
 165
 166                 if node is not None:
 167                         return node.construct_url(subpath)
 168                 return subpath
 169
 170         def get_reverse_params(self, obj):
 171                 """
 172                 This method is not implemented on the base class. It should return a (``view_name``, ``args``, ``kwargs``) tuple suitable for reversing a url for the given ``obj`` using ``self`` as the urlconf. If a reversal will not be possible, this method should raise :class:`~philo.exceptions.ViewCanNotProvideSubpath`.
 173
 174                 """
 175                 raise NotImplementedError("View subclasses must implement get_reverse_params to support subpaths.")
 176
 177         def attributes_with_node(self, node):
 178                 """
 179                 Returns a :class:`~philo.models.base.QuerySetMapper` using the :class:`Node`'s attributes as a passthrough.
 180
 181                 """
 182                 return QuerySetMapper(self.attribute_set, passthrough=node.attributes)
 183
 184         def render_to_response(self, request, extra_context=None):
 185                 """
 186                 Renders the :class:`View` as an :class:`HttpResponse`. This will raise :const:`~philo.exceptions.MIDDLEWARE_NOT_CONFIGURED` if the `request` doesn't have an attached :class:`Node`. This can happen if the :class:`~philo.middleware.RequestNodeMiddleware` is not in :setting:`settings.MIDDLEWARE_CLASSES` or if it is not functioning correctly.
 187
 188                 :meth:`render_to_response` will send the :data:`~philo.signals.view_about_to_render` signal, then call :meth:`actually_render_to_response`, and finally send the :data:`~philo.signals.view_finished_rendering` signal before returning the ``response``.
 189
 190                 """
 191                 if not hasattr(request, 'node'):
 192                         raise MIDDLEWARE_NOT_CONFIGURED
 193
 194                 extra_context = extra_context or {}
 195                 view_about_to_render.send(sender=self, request=request, extra_context=extra_context)
 196                 response = self.actually_render_to_response(request, extra_context)
 197                 view_finished_rendering.send(sender=self, response=response)
 198                 return response
 199
 200         def actually_render_to_response(self, request, extra_context=None):
 201                 """Concrete subclasses must override this method to provide the business logic for turning a ``request`` and ``extra_context`` into an :class:`HttpResponse`."""
 202                 raise NotImplementedError('View subclasses must implement actually_render_to_response.')
 203
 204         class Meta:
 205                 abstract = True
 206
 207
 208 _view_content_type_limiter.cls = View
 209
 210
 211 class MultiView(View):
 212         """
 213         :class:`MultiView` is an abstract model which represents a section of related pages - for example, a :class:`~philo.contrib.penfield.BlogView` might have a foreign key to :class:`Page`\ s for an index, an entry detail, an entry archive by day, and so on. :class:`!MultiView` subclasses :class:`View`, and defines the following additional methods and attributes:
 214
 215         """
 216         #: Same as :attr:`View.accepts_subpath`. Default: ``True``
 217         accepts_subpath = True
 218
 219         @property
 220         def urlpatterns(self):
 221                 """Returns urlpatterns that point to views (generally methods on the class). :class:`MultiView`\ s can be thought of as "managing" these subpaths."""
 222                 raise NotImplementedError("MultiView subclasses must implement urlpatterns.")
 223
 224         def handles_subpath(self, subpath):
 225                 if not super(MultiView, self).handles_subpath(subpath):
 226                         return False
 227                 try:
 228                         resolve(subpath, urlconf=self)
 229                 except Http404:
 230                         return False
 231                 return True
 232
 233         def actually_render_to_response(self, request, extra_context=None):
 234                 """
 235                 Resolves the remaining subpath left after finding this :class:`View`'s node using :attr:`self.urlpatterns <urlpatterns>` and renders the view function (or method) found with the appropriate args and kwargs.
 236
 237                 """
 238                 clear_url_caches()
 239                 subpath = request.node.subpath
 240                 view, args, kwargs = resolve(subpath, urlconf=self)
 241                 view_args = getargspec(view)
 242                 if extra_context is not None and ('extra_context' in view_args[0] or view_args[2] is not None):
 243                         if 'extra_context' in kwargs:
 244                                 extra_context.update(kwargs['extra_context'])
 245                         kwargs['extra_context'] = extra_context
 246                 return view(request, *args, **kwargs)
 247
 248         def get_context(self):
 249                 """Hook for providing instance-specific context - such as the value of a Field - to any view methods on the instance."""
 250                 return {}
 251
 252         def basic_view(self, field_name):
 253                 """
 254                 Given the name of a field on the class, accesses the value of
 255                 that field and treats it as a ``View`` instance. Creates a
 256                 basic context based on self.get_context() and any extra_context
 257                 that was passed in, then calls the ``View`` instance's
 258                 render_to_response() method. This method is meant to be called
 259                 to return a view function appropriate for urlpatterns.
 260
 261                 :param field_name: The name of a field on the instance which contains a :class:`View` subclass instance.
 262                 :returns: A simple view function.
 263
 264                 Example::
 265
 266                         class Foo(Multiview):
 267                                 page = models.ForeignKey(Page)
 268
 269                                 @property
 270                                 def urlpatterns(self):
 271                                         urlpatterns = patterns('',
 272                                                 url(r'^$', self.basic_view('page'))
 273                                         )
 274                                         return urlpatterns
 275
 276                 """
 277                 field = self._meta.get_field(field_name)
 278                 view = getattr(self, field.name, None)
 279
 280                 def inner(request, extra_context=None, **kwargs):
 281                         if not view:
 282                                 raise Http404
 283                         context = self.get_context()
 284                         context.update(extra_context or {})
 285                         return view.render_to_response(request, extra_context=context)
 286
 287                 return inner
 288
 289         class Meta:
 290                 abstract = True
 291
 292
 293 class TargetURLModel(models.Model):
 294         """An abstract parent class for models which deal in targeting a url."""
 295         #: An optional :class:`ForeignKey` to a :class:`Node`. If provided, that node will be used as the basis for the redirect.
 296         target_node = models.ForeignKey(Node, blank=True, null=True, related_name="%(app_label)s_%(class)s_related")
 297         #: A :class:`CharField` which may contain an absolute or relative URL. This will be validated with :class:`philo.validators.RedirectValidator`.
 298         url_or_subpath = models.CharField(max_length=200, validators=[RedirectValidator()], blank=True, help_text="Point to this url or, if a node is defined and accepts subpaths, this subpath of the node.")
 299         #: A :class:`~philo.models.fields.JSONField` instance. If the value of :attr:`reversing_parameters` is not None, the :attr:`url_or_subpath` will be treated as the name of a view to be reversed. The value of :attr:`reversing_parameters` will be passed into the reversal as args if it is a list or as kwargs if it is a dictionary. Otherwise it will be ignored.
 300         reversing_parameters = JSONField(blank=True, help_text="If reversing parameters are defined, url_or_subpath will instead be interpreted as the view name to be reversed.")
 301
 302         def clean(self):
 303                 if not self.target_node and not self.url_or_subpath:
 304                         raise ValidationError("Either a target node or a url must be defined.")
 305
 306                 if self.reversing_parameters and not (self.url_or_subpath or self.target_node):
 307                         raise ValidationError("Reversing parameters require either a view name or a target node.")
 308
 309                 try:
 310                         self.get_target_url()
 311                 except (NoReverseMatch, ViewCanNotProvideSubpath), e:
 312                         raise ValidationError(e.message)
 313
 314                 super(TargetURLModel, self).clean()
 315
 316         def get_reverse_params(self):
 317                 params = self.reversing_parameters
 318                 args = kwargs = None
 319                 if isinstance(params, list):
 320                         args = params
 321                 elif isinstance(params, dict):
 322                         # Convert unicode keys to strings for Python < 2.6.5. Compare
 323                         # http://stackoverflow.com/questions/4598604/how-to-pass-unicode-keywords-to-kwargs
 324                         kwargs = dict([(smart_str(k, 'ascii'), v) for k, v in params.items()])
 325                 return self.url_or_subpath, args, kwargs
 326
 327         def get_target_url(self):
 328                 """Calculates and returns the target url based on the :attr:`target_node`, :attr:`url_or_subpath`, and :attr:`reversing_parameters`."""
 329                 node = self.target_node
 330                 if node is not None and node.accepts_subpath and self.url_or_subpath:
 331                         if self.reversing_parameters is not None:
 332                                 view_name, args, kwargs = self.get_reverse_params()
 333                                 subpath = node.view.reverse(view_name, args=args, kwargs=kwargs)
 334                         else:
 335                                 subpath = self.url_or_subpath
 336                                 if subpath[0] != '/':
 337                                         subpath = '/' + subpath
 338                         return node.construct_url(subpath)
 339                 elif node is not None:
 340                         return node.get_absolute_url()
 341                 else:
 342                         if self.reversing_parameters is not None:
 343                                 view_name, args, kwargs = self.get_reverse_params()
 344                                 return reverse(view_name, args=args, kwargs=kwargs)
 345                         return self.url_or_subpath
 346         target_url = property(get_target_url)
 347
 348         class Meta:
 349                 abstract = True
 350
 351
 352 class Redirect(TargetURLModel, View):
 353         """Represents a 301 or 302 redirect to a different url on an absolute or relative path."""
 354         #: A choices tuple of redirect status codes (temporary or permanent).
 355         STATUS_CODES = (
 356                 (302, 'Temporary'),
 357                 (301, 'Permanent'),
 358         )
 359         #: An :class:`IntegerField` which uses :attr:`STATUS_CODES` as its choices. Determines whether the redirect is considered temporary or permanent.
 360         status_code = models.IntegerField(choices=STATUS_CODES, default=302, verbose_name='redirect type')
 361
 362         def actually_render_to_response(self, request, extra_context=None):
 363                 """Returns an :class:`HttpResponseRedirect` to :attr:`self.target_url`."""
 364                 response = HttpResponseRedirect(self.target_url)
 365                 response.status_code = self.status_code
 366                 return response
 367
 368         class Meta:
 369                 app_label = 'philo'
 370
 371
 372 class File(View):
 373         """Stores an arbitrary file."""
 374         #: Defines the mimetype of the uploaded file. This will not be validated.
 375         mimetype = models.CharField(max_length=255)
 376         #: Contains the uploaded file. Files are uploaded to ``philo/files/%Y/%m/%d``.
 377         file = models.FileField(upload_to='philo/files/%Y/%m/%d')
 378
 379         def actually_render_to_response(self, request, extra_context=None):
 380                 wrapper = FileWrapper(self.file)
 381                 response = HttpResponse(wrapper, content_type=self.mimetype)
 382                 response['Content-Length'] = self.file.size
 383                 return response
 384
 385         class Meta:
 386                 app_label = 'philo'
 387
 388         def __unicode__(self):
 389                 """Returns the path of the uploaded file."""
 390                 return self.file.name
 391
 392
 393 register_templatetags('philo.templatetags.nodes')
 394 register_value_model(Node)