terom@39: """
terom@39:     Tree-based URL mapping
terom@39: """
terom@39: 
terom@39: import re
terom@39: import os.path
terom@39: 
terom@39: # for Mapper
terom@39: from lib import map
terom@39: 
terom@39: class URLError (Exception) :
terom@39:     """
terom@39:         Error with an URL definition
terom@39:     """
terom@39: 
terom@39:     pass
terom@39: 
terom@39: class LabelValue (object) :
terom@39:     """
terom@39:         Represents the value of a ValueLabel... love these names
terom@39:     """
terom@39: 
terom@39:     def __init__ (self, label, value) :
terom@39:         """
terom@39:             Just store
terom@39:         """
terom@39: 
terom@39:         self.label = label
terom@39:         self.value = value
terom@39:     
terom@39:     def __str__ (self) :
terom@39:         return "%s=%r" % (self.label.key, self.value)
terom@39: 
terom@39:     def __repr__ (self) :
terom@39:         return "<%s>" % self
terom@39: 
terom@39: class Label (object) :
terom@39:     """
terom@39:         Base class for URL labels (i.e. the segments of the URL between /s)
terom@39:     """
terom@39: 
terom@39:     @staticmethod
terom@39:     def parse (mask, defaults) :
terom@39:         """
terom@39:             Parse the given label-segment, and return a *Label instance
terom@39:         """
terom@39: 
terom@39:         # empty?
terom@39:         if not mask :
terom@39:             return EmptyLabel()
terom@39: 
terom@39:         # simple value?
terom@39:         match = SimpleValueLabel.EXPR.match(mask)
terom@39: 
terom@39:         if match :
terom@39:             # key
terom@39:             key = match.group('key')
terom@39: 
terom@39:             # type
terom@39:             type = match.group("type")
terom@39:             
terom@39:             if type :
terom@39:                 # XXX: resolve using eval() for now, should be a module or something
terom@39:                 type = eval(type)
terom@39: 
terom@39:             else :
terom@39:                 type = str
terom@39: 
terom@39:             # defaults?
terom@39:             default = defaults.get(key)
terom@39: 
terom@39:             if not default :
terom@39:                 default = match.group('default')
terom@39: 
terom@39:                 if default :
terom@39:                     # apply type to default
terom@39:                     default = type(default)
terom@39: 
terom@39:             # build
terom@39:             return SimpleValueLabel(key, type, default)
terom@39:         
terom@39:         # static?
terom@39:         match = StaticLabel.EXPR.match(mask)
terom@39: 
terom@39:         if match :
terom@39:             return StaticLabel(match.group('name'))
terom@39: 
terom@39:         # invalid
terom@39:         raise URLError("Invalid label: %r" % (mask, ))
terom@39:     
terom@39:     def match (self, value=None) :
terom@39:         """
terom@39:             Match this label against the given value, returning either True to match without a value, a LabelValue
terom@39:             object, or boolean false to not match.
terom@39: 
terom@39:             If value is None, this means that only a default value should be returned.
terom@39:         """
terom@39: 
terom@39:         abstract
terom@39: 
terom@39: class EmptyLabel (Label) :
terom@39:     """
terom@39:         An empty label, i.e. just a slash in the URL
terom@39:     """
terom@39:     
terom@39:     def __eq__ (self, other) :
terom@39:         """
terom@39:             Just compares type
terom@39:         """
terom@39: 
terom@39:         return isinstance(other, EmptyLabel)
terom@39:     
terom@39:     def match (self, value=None) :
terom@39:         """
terom@39:             Match empty string -> True
terom@39:         """
terom@39:         
terom@39:         # no default
terom@39:         if value is None :
terom@39:             return False
terom@39:         
terom@39:         # only empty segments
terom@39:         if value == '' :
terom@39:             return True
terom@39: 
terom@39:     def __str__ (self) :
terom@39:         return ''
terom@39: 
terom@39: class StaticLabel (Label) :
terom@39:     """
terom@39:         A simple literal Label, used for fixed terms in the URL
terom@39:     """
terom@39: 
terom@39:     EXPR = re.compile(r'^(?P<name>[a-zA-Z_.-]+)$')
terom@39: 
terom@39:     def __init__ (self, name) :
terom@39:         """
terom@39:             The given name is the literal name of this label
terom@39:         """
terom@39: 
terom@39:         self.name = name
terom@39: 
terom@39:     def __eq__ (self, other) :
terom@39:         """
terom@39:             Compares names
terom@39:         """
terom@39: 
terom@39:         return isinstance(other, StaticLabel) and self.name == other.name
terom@39:     
terom@39:     def match (self, value=None) :
terom@39:         """
terom@39:             Match exactly -> True
terom@39:         """
terom@39: 
terom@39:         # no defaults
terom@39:         if value is None :
terom@39:             return False
terom@39:         
terom@39:         # match name
terom@39:         if value == self.name :
terom@39:             return True
terom@39: 
terom@39:     def __str__ (self) :
terom@39:         return self.name
terom@39: 
terom@39: class ValueLabel (Label) :
terom@39:     """
terom@39:         A label with a key and a value
terom@39: 
terom@39:         XXX: do we even need this?
terom@39:     """
terom@39: 
terom@39:     def __init__ (self, key, default) :
terom@39:         """
terom@39:             Set the key and default value. Default value may be None if there is no default value defined
terom@39:         """
terom@39: 
terom@39:         self.key = key
terom@39:         self.default = default
terom@39: 
terom@39:     def __eq__ (self, other) :
terom@39:         """
terom@39:             Compares keys
terom@39:         """
terom@39: 
terom@39:         return isinstance(other, ValueLabel) and self.key == other.key
terom@39: 
terom@39: class SimpleValueLabel (ValueLabel) :
terom@39:     """
terom@39:         A label that has a name and a simple string value
terom@39:     """
terom@39: 
terom@39:     EXPR = re.compile(r'^\{(?P<key>[a-zA-Z_][a-zA-Z0-9_]*)(:(?P<type>[a-zA-Z_][a-zA-Z0-9_]*))?(=(?P<default>[^}]+))?\}$')
terom@39: 
terom@39:     def __init__ (self, key, type=str, default=None) :
terom@39:         """
terom@39:             The given key is the name of this label's value
terom@39:         """
terom@39: 
terom@39:         # type
terom@39:         self.type = type
terom@39: 
terom@39:         # store
terom@39:         self.key = key
terom@39:         self.default = default
terom@39:         
terom@39:     def match (self, value=None) :
terom@39:         """
terom@39:             Match -> LabelValue
terom@39:         """
terom@39:         
terom@39:         # default?
terom@39:         if value is None and self.default :
terom@39:             return LabelValue(self, self.default)
terom@39:         
terom@39:         # only non-empty values!
terom@39:         elif value :
terom@39:             # convert with type
terom@39:             try :
terom@39:                 value = self.type(value)
terom@39: 
terom@39:             except Exception, e :
terom@39:                 raise URLError("Bad value %r for type %s: %s" % (value, self.type.__name__, e))
terom@39: 
terom@39:             return LabelValue(self, value)
terom@39: 
terom@39:     def __str__ (self) :
terom@39:         return '{%s%s%s}' % (
terom@39:             self.key, 
terom@39:             ':%s' % (self.type.__name__ ) if self.type != str else '',
terom@39:             '=%s' % (self.default, ) if self.default else '',
terom@39:         )
terom@39:             
terom@39: class URL (object) :
terom@39:     """
terom@39:         Represents a specific URL
terom@39:     """
terom@39: 
terom@39:     def __init__ (self, url_mask, handler, **defaults) :
terom@39:         """
terom@39:             Create an URL with the given url mask, handler, and default values
terom@39:         """
terom@39: 
terom@39:         # store
terom@39:         self.url_mask = url_mask
terom@39:         self.handler = handler
terom@39:         self.defaults = defaults
terom@39: 
terom@39:         # build our labels
terom@39:         self.label_path = [Label.parse(mask, defaults) for mask in url_mask.split('/')]
terom@39:         
terom@39:     def get_label_path (self) :
terom@39:         """
terom@39:             Returns a list containing the labels in this url
terom@39:         """
terom@39:         
terom@39:         # copy self.label_path
terom@39:         return list(self.label_path)
terom@39: 
terom@39:     def execute (self, request, label_values) :
terom@39:         """
terom@39:             Invoke the handler, using the given label values
terom@39:         """
terom@39:         
terom@39:         # start with the defaults
terom@40:         kwargs = self.defaults.copy()
terom@39: 
terom@39:         # then add all the values
terom@39:         for label_value in label_values :
terom@39:             kwargs[label_value.label.key] = label_value.value
terom@39:             
terom@39:         # execute the handler
terom@39:         return self.handler(request, **kwargs)
terom@39: 
terom@39:     def __str__ (self) :
terom@39:         return '/'.join(str(label) for label in self.label_path)
terom@39:     
terom@39:     def __repr__ (self) :
terom@39:         return "URL(%r, %r)" % (str(self), self.handler)
terom@39: 
terom@39: class URLNode (object) :
terom@39:     """
terom@39:         Represents a node in the URLTree
terom@39:     """
terom@39: 
terom@39:     def __init__ (self, parent, label) :
terom@39:         """
terom@39:             Initialize with the given parent and label, empty children dict
terom@39:         """
terom@39:         
terom@39:         # the parent URLNode
terom@39:         self.parent = parent
terom@39: 
terom@39:         # this node's Label
terom@39:         self.label = label
terom@39: 
terom@39:         # list of child URLNodes
terom@39:         self.children = []
terom@39: 
terom@39:         # this node's URL, set by add_url for an empty label_path
terom@39:         self.url = None
terom@39: 
terom@39:     def _build_child (self, label) :
terom@39:         """
terom@39:             Build, insert and return a new child Node
terom@39:         """
terom@39:         
terom@39:         # build new child
terom@39:         child = URLNode(self, label)
terom@39:         
terom@39:         # add to children
terom@39:         self.children.append(child)
terom@39: 
terom@39:         # return
terom@39:         return child
terom@39: 
terom@39:     def add_url (self, url, label_path) :
terom@39:         """
terom@39:             Add a URL object to this node under the given path. Uses recursion to process the path.
terom@39: 
terom@39:             The label_path argument is a (partial) label path as returned by URL.get_label_path.
terom@39: 
terom@39:             If label_path is empty (len zero, or begins with EmptyLabel), then the given url is assigned to this node, if no
terom@39:             url was assigned before.
terom@39:         """
terom@39:         
terom@39:         # matches this node?
terom@39:         if not label_path or isinstance(label_path[0], EmptyLabel) :
terom@39:             if self.url :
terom@39:                 raise URLError(url, "node already defined")
terom@39: 
terom@39:             else :
terom@39:                 # set
terom@39:                 self.url = url
terom@39: 
terom@39:         else :
terom@39:             # pop child label from label_path
terom@39:             child_label = label_path.pop(0)
terom@39: 
terom@39:             # look for the child to recurse into
terom@39:             child = None
terom@39: 
terom@39:             # look for an existing child with that label
terom@39:             for child in self.children :
terom@39:                 if child.label == child_label :
terom@39:                     # found, use this
terom@39:                     break
terom@39: 
terom@39:             else :
terom@39:                 # build a new child
terom@39:                 child = self._build_child(child_label)
terom@39: 
terom@39:             # recurse to handle the rest of the label_path
terom@39:             child.add_url(url, label_path)
terom@39:     
terom@39:     def match (self, label_path) :
terom@39:         """
terom@39:             Locate the URL object corresponding to the given label_path value under this node.
terom@39: 
terom@39:             Returns a (url, label_values) tuple
terom@39:         """
terom@39: 
terom@39:         # determine value to use
terom@39:         value = None
terom@39: 
terom@39:         # empty label_path?
terom@39:         if not label_path or label_path[0] == '' :
terom@39:             # the search ends at this node
terom@39:             if self.url :
terom@39:                 # this URL is the best match
terom@39:                 return (self.url, [])
terom@39:             
terom@39:             elif not self.children :
terom@39:                 # incomplete URL
terom@39:                 raise URLError("no URL handler defined for this Node")
terom@39:             
terom@39:             else :
terom@39:                 # use default value, i.e. Label.match(None)
terom@39:                 label = None
terom@39: 
terom@39:         else :
terom@39:             # pop the next label from the label path
terom@39:             label = label_path.pop(0)
terom@39: 
terom@39:         # return one match...
terom@39:         match = value = None
terom@39: 
terom@39:         # recurse through our children, DFS
terom@39:         for child in self.children :
terom@39:             # match value
terom@39:             value = child.label.match(label)
terom@39: 
terom@39:             # skip those that don't match at all
terom@39:             if not value :
terom@39:                 continue;
terom@39:             
terom@39:             # already found a match? :/
terom@39:             if match :
terom@39:                 raise URLError("Ambiguous URL")
terom@39: 
terom@39:             # ok, but continue looking to make sure there's no ambiguous URLs
terom@39:             match = child
terom@39:         
terom@39:         # found something?
terom@39:         if not match :
terom@40:             raise URLError("No child found for label: %s + %s + %s" % (self.get_url(), label, '/'.join(str(l) for l in label_path)))
terom@39: 
terom@39:         # ok, recurse into the match
terom@39:         url, label_value = match.match(label_path)
terom@39: 
terom@39:         # add our value?
terom@39:         if isinstance(value, LabelValue) :
terom@39:             label_value.append(value)
terom@39: 
terom@39:         # return the match
terom@39:         return url, label_value
terom@40: 
terom@40:     def get_url (self) :
terom@40:         """
terom@40:             Returns the URL for this node, by iterating over our parents
terom@40:         """
terom@40:         
terom@40:         # URL segments in reverse order
terom@40:         segments = ['']
terom@40:         
terom@40:         # start with ourself
terom@40:         node = self
terom@40:         
terom@40:         # iterate up to root
terom@40:         while node :
terom@40:             segments.append(str(node.label))
terom@40: 
terom@40:             node = node.parent
terom@40: 
terom@40:         # reverse
terom@40:         segments.reverse()
terom@40: 
terom@40:         # return
terom@40:         return '/'.join(segments)
terom@40: 
terom@39:     def dump (self, indent=0) :
terom@39:         """
terom@39:             Returns a multi-line string representation of this Node
terom@39:         """
terom@39: 
terom@39:         return '\n'.join([
terom@39:             "%-45s%s" % (
terom@39:                 ' '*indent + str(self.label) + ('/' if self.children else ''), 
terom@39:                 (' -> %r' % self.url) if self.url else ''
terom@39:             )
terom@39:         ] + [
terom@39:             child.dump(indent + 4) for child in self.children
terom@39:         ])
terom@39: 
terom@39:     def __str__ (self) :
terom@39:         return "%s/[%s]" % (self.label, ','.join(str(child) for child in self.children))
terom@39: 
terom@39: class URLTree (map.Mapper) :
terom@39:     """
terom@39:         Map requests to handlers, using a defined tree of URLs
terom@39:     """
terom@39: 
terom@39:     def __init__ (self, url_list) :
terom@39:         """
terom@39:             Initialize the tree using the given list of URLs
terom@39:         """
terom@39: 
terom@39:         # root node
terom@39:         self.root = URLNode(None, EmptyLabel())
terom@39:         
terom@39:         # just add each URL
terom@39:         for url in url_list :
terom@39:             self.add_url(url)
terom@39: 
terom@39:     def add_url (self, url) :
terom@39:         """
terom@39:             Adds the given URL to the tree. The URL must begin with a root slash.
terom@39:         """
terom@39:         # get url's label path
terom@39:         path = url.get_label_path()
terom@39: 
terom@39:         # should begin with root
terom@39:         root_label = path.pop(0)
terom@39:         assert root_label == self.root.label, "URL must begin with root"
terom@39: 
terom@39:         # add to root
terom@39:         self.root.add_url(url, path)
terom@39:         
terom@39:     def match (self, url) :
terom@39:         """
terom@39:             Find the URL object best corresponding to the given url, matching any ValueLabels.
terom@39: 
terom@39:             Returns an (URL, [LabelValue]) tuple.
terom@39:         """
terom@39: 
terom@39:         # split it into labels
terom@39:         path = url.split('/')
terom@40:         
terom@40:         # empty URL is empty
terom@40:         if url :
terom@40:             # ensure that it doesn't start with a /
terom@40:             assert not self.root.label.match(path[0]), "URL must not begin with root"
terom@39: 
terom@39:         # just match starting at root
terom@39:         return self.root.match(path)
terom@39: 
terom@39:     def handle_request (self, request) :
terom@39:         """
terom@39:             Looks up the request's URL, and invokes its handler
terom@39:         """
terom@39:         
terom@40:         # get the requested URL
terom@40:         request_url = request.get_page_name()
terom@40: 
terom@40:         # find the URL+values to use
terom@40:         url, label_values = self.match(request_url)
terom@39: 
terom@39:         # let the URL handle it
terom@40:         return url.execute(request, label_values)
terom@39: 
terom@39: