#!/usr/bin/python2.5
#
# Copyright 2008 the Melange authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#   http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Page properties, used to generate sidebar menus, urlpatterns, etc.
"""

__authors__ = [
  '"Todd Larsen" <tlarsen@google.com>',
  ]


import copy
import re

from django.conf.urls import defaults

from python25src import urllib

from soc.logic import menu
from soc.logic.no_overwrite_sorted_dict import NoOverwriteSortedDict


class Url:
  """The components of a Django URL pattern.
  """
   
  def __init__(self, regex, view, kwargs=None, name=None, prefix=''):
    """Collects Django urlpatterns info into a simple object.
    
    The arguments to this constructor correspond directly to the items in
    the urlpatterns tuple, which also correspond to the parameters of
    django.conf.urls.defaults.url().
    
    Args:
      regex: a Django URL regex pattern, which, for obvious reason, must
        be unique
      view: a Django view, either a string or a callable; if a callable,
        a unique 'name' string must be supplied
      kwargs: optional dict of extra arguments passed to the view
        function as keyword arguments, which is copy.deepcopy()'d;
        default is None, which supplies an empty dict {}
      name: optional name of the view; used instead of 'view' if supplied;
        the 'name' or 'view' string, whichever is used, must be unique
        amongst *all* Url objects supplied to a Page object
      prefix: optional view prefix
    """
    self.regex = regex
    self.view = view
    
    if kwargs:
      self.kwargs = copy.deepcopy(kwargs)
    else:
      self.kwargs = {}

    self.name = name
    self.prefix = prefix

  def makeDjangoUrl(self, **extra_kwargs):
    """Returns a Django url() used by urlpatterns, or None if not a view.
    """
    if not self.view:
      return None

    kwargs = copy.deepcopy(self.kwargs)
    kwargs.update(extra_kwargs)
    return defaults.url(self.regex, self.view, kwargs=kwargs,
                        name=self.name, prefix=self.prefix)

  _STR_FMT = '''%(indent)sregex: %(regex)s
%(indent)sview: %(view)s
%(indent)skwargs: %(kwargs)s
%(indent)sname: %(name)s
%(indent)sprefix: %(prefix)s
'''

  def asIndentedStr(self, indent=''):
    """Returns an indented string representation useful for logging.
    
    Args:
      indent: an indentation string that is prepended to each line present
        in the multi-line string returned by this method.
    """
    return self._STR_FMT % {'indent': indent, 'regex': self.regex,
                            'view': self.view, 'kwargs': self.kwargs,
                            'name': self.name, 'prefix': self.prefix}

  def __str__(self):
    """Returns a string representation useful for logging.
    """
    return self.asIndentedStr()


class Page:
  """An abstraction that combines a Django view with sidebar menu info.
  """
  
  def __init__(self, url, long_name, short_name=None, selected=False,
               annotation=None, parent=None, link_url=None,
               in_breadcrumb=True, force_in_menu=False):
    """Initializes the menu item attributes from supplied arguments.
    
    Args:
      url: a Url object
      long_name: title of the Page
      short_name: optional menu item and breadcrumb name; default is
        None, in which case long_name is used
      selected: Boolean indicating if this menu item is selected;
        default is False
      annotation: optional annotation associated with the menu item;
        default is None
      parent: optional Page that is the logical "parent" of this page;
        used to construct hierarchical menus and breadcrumb trails
      link_url: optional alternate URL link; if supplied, it is returned
        by makeLinkUrl(); default is None, and makeLinkUrl() attempts to
        create a URL link from url.regex 
      in_breadcrumb: if True, the Page appears in breadcrumb trails;
        default is True
      force_in_menu: if True, the Page appears in menus even if it does
        not have a usable link_url; default is False, which excludes
        the Page if makeLinkUrl() returns None
    """
    self.url = url
    self.long_name = long_name
    self.annotation = annotation
    self.in_breadcrumb = in_breadcrumb
    self.force_in_menu = force_in_menu
    self.link_url = link_url
    self.selected = selected
    self.parent = parent

    # create ordered, unique mappings of URLs and view names to Pages
    self.child_by_urls = NoOverwriteSortedDict()
    self.child_by_views = NoOverwriteSortedDict()
    
    if not short_name:
      short_name = long_name
      
    self.short_name = short_name
    
    if parent:
      # tell parent Page about parent <- child relationship
      parent.addChild(self)
      
    # TODO(tlarsen): build some sort of global Page dictionary to detect
    #   collisions sooner and to make global queries from URLs to pages
    #   and views to Pages possible (without requiring a recursive search)

  def getChildren(self):
    """Returns an iterator over any child Pages 
    """
    for page in self.child_by_views.itervalues():
      yield page

  children = property(getChildren)

  def getChild(self, url=None, regex=None, view=None,
               name=None, prefix=None, request_path=None):
    """Returns a child Page if one can be identified; or None otherwise.
    
    All of the parameters to this method are optional, but at least one
    must be supplied to return anything other than None.  The parameters
    are tried in the order they are listed in the "Args:" section, and
    this method exits on the first "match".
    
    Args:
      url: a Url object, used to overwrite the regex, view, name, and
        prefix parameters if present; default is None
      regex: a regex pattern string, used to return the associated
        child Page
      view: a view string, used to return the associated child Page
      name: a name string, used to return the associated child Page
      prefix: (currently unused, see TODO below in code)
      request_path: optional HTTP request path string (request.path)
        with no query arguments
    """
    # this code is yucky; there is probably a better way...
    if url:
      regex = url.regex
      view = url.view
      name = url.name
      prefix = url.prefix

    if regex in self.child_by_urls:
      # regex supplied and Page found, so return that Page
      return self.child_by_urls[regex][0]
  
    # TODO(tlarsen): make this work correctly with prefixes

    if view in self.child_views:
      # view supplied and Page found, so return that Page
      return self.child_by_views[view]
  
    if name in self.child_views:
      # name supplied and Page found, so return that Page
      return self.child_by_views[name]

    if request_path.startswith('/'):
      request_path = request_path[1:]

    # attempt to match the HTTP request path with a Django URL pattern
    for pattern, (page, regex) in self.child_by_urls:
      if regex.match(request_path):
        return page

    return None

  def addChild(self, page):
    """Adds a unique Page as a child Page of this parent.
    
    Raises:
      ValueError if page.url.regex is not a string.
      ValueError if page.url.view is not a string.
      ValueError if page.url.name is supplied but is not a string.
      KeyError if page.url.regex is already associated with another Page.
      KeyError if page.url.view/name is already associated with another Page.
    """
    # TODO(tlarsen): see also TODO in __init__() about global Page dictionary

    url = page.url
    
    if url.regex:
      if not isinstance(url.regex, basestring):
        raise ValueError('"regex" must be a string, not a compiled regex')

      # TODO(tlarsen): see if Django has some way exposed in its API to get
      #   the view name from the request path matched against urlpatterns;
      #   if so, there would be no need for child_by_urls, because the
      #   request path could be converted for us by Django into a view/name,
      #   and we could just use child_by_views with that string instead
      self.child_by_urls[url.regex] = (page, re.compile(url.regex))
    # else: NonUrl does not get indexed by regex, because it has none

    # TODO(tlarsen): make this work correctly if url has a prefix
    #   (not sure how to make this work with include() views...)
    if url.name:
      if not isinstance(url.name, basestring):
        raise ValueError('"name" must be a string if it is supplied')

      view = url.name
    elif isinstance(url.view, basestring):
      view = url.view
    else:
      raise ValueError('"view" must be a string if "name" is not supplied')

    self.child_by_views[view] = page

  def delChild(self, url=None, regex=None, view=None, name=None,
               prefix=None):
    """Removes a child Page if one can be identified.
    
    All of the parameters to this method are optional, but at least one
    must be supplied in order to remove a child Page.  The parameters
    are tried in the order they are listed in the "Args:" section, and
    this method uses the first "match".
    
    Args:
      url: a Url object, used to overwrite the regex, view, name, and
        prefix parameters if present; default is None
      regex: a regex pattern string, used to remove the associated
        child Page
      view: a view string, used to remove the associated child Page
      name: a name string, used to remove the associated child Page
      prefix: (currently unused, see TODO below in code)
      
    Raises:
      KeyError if the child Page could not be definitively identified in
      order to delete it.
    """
    # this code is yucky; there is probably a better way...
    if url:
      regex = url.regex
      view = url.view
      name = url.name
      prefix = url.prefix

    # try to find page by regex, view, or name, in turn
    if regex in self.child_by_urls:
      url = self.child_by_urls[regex][0].url
      view = url.view
      name = url.name
      prefix = url.prefix
    elif view in self.child_views:
      # TODO(tlarsen): make this work correctly with prefixes
      regex = self.child_by_views[view].url.regex
    elif name in self.child_views:
      regex = self.child_by_views[name].url.regex

    if regex:
      # regex must refer to an existing Page at this point
      del self.child_urls[regex]

    if not isinstance(view, basestring):
      # use name if view is callable() or None, etc.
      view = name

    # TODO(tlarsen): make this work correctly with prefixes
    del self.child_by_views[view]
    

  def makeLinkUrl(self):
    """Makes a URL link suitable for <A HREF> use.
    
    Returns:
      self.link_url if link_url was supplied to the __init__() constructor
        and it is a non-False value
       -OR-
      a suitable URL extracted from the url.regex, if possible
       -OR-
      None if url.regex contains quotable characters that have not already
        been quoted (that is, % is left untouched, so quote suspect
        characters in url.regex that would otherwise be quoted)
    """
    if self.link_url:
      return self.link_url

    link = self.url.regex
    
    if not link:
      return None

    if link.startswith('^'):
      link = link[1:]
    
    if link.endswith('$'):
      link = link[:-1]

    if not link.startswith('/'):
      link = '/' + link
    
    # path separators and already-quoted characters are OK
    if link != urllib.quote(link, safe='/%'):
      return None

    return link

  def makeMenuItem(self):
    """Returns a menu.MenuItem for the Page (and any child Pages).
    """
    child_items = []
    
    for child in self.children:
      child_item = child.makeMenuItem()
      if child_item:
        child_items.append(child_item)
    
    if child_items:
      sub_menu = menu.Menu(items=child_items)
    else:
      sub_menu = None
    
    link_url = self.makeLinkUrl()
    
    if (not sub_menu) and (not link_url) and (not self.force_in_menu):
      # no sub-menu, no valid link URL, and not forced to be in menu
      return None
    
    return menu.MenuItem(
      self.short_name, value=link_url, sub_menu=sub_menu)

  def makeDjangoUrl(self):
    """Returns the Django url() for the underlying self.url.
    """
    return self.url.makeDjangoUrl(page=self)

  def makeDjangoUrls(self):
    """Returns an ordered mapping of unique Django url() objects.
    
    Raises:
      KeyError if more than one Page has the same urlpattern.
      
    TODO(tlarsen): this really needs to be detected earlier via a
      global Page dictionary
    """
    return self._makeDjangoUrlsDict().values()

  def _makeDjangoUrlsDict(self):
    """Returns an ordered mapping of unique Django url() objects.
    
    Used to implement makeDjangoUrls().  See that method for details.
    """
    urlpatterns = NoOverwriteSortedDict()

    django_url = self.makeDjangoUrl()
    
    if django_url:
      urlpatterns[self.url.regex] = django_url
    
    for child in self.children:
      urlpatterns.update(child._makeDjangoUrlsDict())
    
    return urlpatterns

  _STR_FMT = '''%(indent)slong_name: %(long_name)s
%(indent)sshort_name: %(short_name)s
%(indent)sselected: %(selected)s
%(indent)sannotation: %(annotation)s
%(indent)surl: %(url)s
'''

  def asIndentedStr(self, indent=''):
    """Returns an indented string representation useful for logging.
    
    Args:
      indent: an indentation string that is prepended to each line present
        in the multi-line string returned by this method.
    """
    strings = [ 
        self._STR_FMT % {'indent': indent, 'long_name': self.long_name,
                         'short_name': self.short_name,
                         'selected': self.selected,
                         'annotation': self.annotation,
                         'url': self.url.asIndentedStr(indent + ' ')}]

    for child in self.children:
      strings.extend(child.asIndentedStr(indent + '  '))

    return ''.join(strings)

  def __str__(self):
    """Returns a string representation useful for logging.
    """
    return self.asIndentedStr()


class NonUrl(Url):
  """Placeholder for when a site-map entry is not a linkable URL.
  """
   
  def __init__(self, name):
    """Creates a non-linkable Url placeholder.
    
    Args:
      name: name of the non-view placeholder; see Url.__init__()
    """
    Url.__init__(self, None, None, name=name)

  def makeDjangoUrl(self, **extra_kwargs):
    """Always returns None, since NonUrl is never a Django view.
    """
    return None


class NonPage(Page):
  """Placeholder for when a site-map entry is not a displayable page.
  """

  def __init__(self, non_url_name, long_name, **page_kwargs):
    """Constructs a NonUrl and passes it to base Page class __init__().
    
    Args:
      non_url_name:  unique (it *must* be) string that does not match
        the 'name' or 'view' of any other Url or NonUrl object;
        see Url.__init__() for details
      long_name:  see Page.__init__()
      **page_kwargs:  keyword arguments passed directly to the base
        Page class __init__()
    """
    non_url = NonUrl(non_url_name)
    Page.__init__(self, non_url, long_name, **page_kwargs)