1 from django import template, templatetags

     2 from django.template import RequestContext

     3 from django.conf import settings

     4 from django.contrib.admin.views.decorators import staff_member_required

     5 from django.db import models

     6 from django.shortcuts import render_to_response

     7 from django.core.exceptions import ImproperlyConfigured, ViewDoesNotExist

     8 from django.http import Http404

     9 from django.core import urlresolvers

    10 from django.contrib.admindocs import utils

    11 from django.contrib.sites.models import Site

    12 from django.utils.translation import ugettext as _

    13 from django.utils.safestring import mark_safe

    14 import inspect, os, re

    15 

    16 # Exclude methods starting with these strings from documentation

    17 MODEL_METHODS_EXCLUDE = ('_', 'add_', 'delete', 'save', 'set_')

    18 

    19 class GenericSite(object):

    20     domain = 'example.com'

    21     name = 'my site'

    22 

    23 def get_root_path():

    24     from django.contrib import admin

    25     try:

    26         return urlresolvers.reverse(admin.site.root, args=[''])

    27     except urlresolvers.NoReverseMatch:

    28         return getattr(settings, "ADMIN_SITE_ROOT_URL", "/admin/")

    29 

    30 def doc_index(request):

    31     if not utils.docutils_is_available:

    32         return missing_docutils_page(request)

    33     return render_to_response('admin_doc/index.html', {

    34         'root_path': get_root_path(),

    35     }, context_instance=RequestContext(request))

    36 doc_index = staff_member_required(doc_index)

    37 

    38 def bookmarklets(request):

    39     admin_root = get_root_path()

    40     return render_to_response('admin_doc/bookmarklets.html', {

    41         'root_path': admin_root,

    42         'admin_url': mark_safe("%s://%s%s" % (request.is_secure() and 'https' or 'http', request.get_host(), admin_root)),

    43     }, context_instance=RequestContext(request))

    44 bookmarklets = staff_member_required(bookmarklets)

    45 

    46 def template_tag_index(request):

    47     if not utils.docutils_is_available:

    48         return missing_docutils_page(request)

    49 

    50     load_all_installed_template_libraries()

    51 

    52     tags = []

    53     for module_name, library in template.libraries.items():

    54         for tag_name, tag_func in library.tags.items():

    55             title, body, metadata = utils.parse_docstring(tag_func.__doc__)

    56             if title:

    57                 title = utils.parse_rst(title, 'tag', _('tag:') + tag_name)

    58             if body:

    59                 body = utils.parse_rst(body, 'tag', _('tag:') + tag_name)

    60             for key in metadata:

    61                 metadata[key] = utils.parse_rst(metadata[key], 'tag', _('tag:') + tag_name)

    62             if library in template.builtins:

    63                 tag_library = None

    64             else:

    65                 tag_library = module_name.split('.')[-1]

    66             tags.append({

    67                 'name': tag_name,

    68                 'title': title,

    69                 'body': body,

    70                 'meta': metadata,

    71                 'library': tag_library,

    72             })

    73     return render_to_response('admin_doc/template_tag_index.html', {

    74         'root_path': get_root_path(),

    75         'tags': tags

    76     }, context_instance=RequestContext(request))

    77 template_tag_index = staff_member_required(template_tag_index)

    78 

    79 def template_filter_index(request):

    80     if not utils.docutils_is_available:

    81         return missing_docutils_page(request)

    82 

    83     load_all_installed_template_libraries()

    84 

    85     filters = []

    86     for module_name, library in template.libraries.items():

    87         for filter_name, filter_func in library.filters.items():

    88             title, body, metadata = utils.parse_docstring(filter_func.__doc__)

    89             if title:

    90                 title = utils.parse_rst(title, 'filter', _('filter:') + filter_name)

    91             if body:

    92                 body = utils.parse_rst(body, 'filter', _('filter:') + filter_name)

    93             for key in metadata:

    94                 metadata[key] = utils.parse_rst(metadata[key], 'filter', _('filter:') + filter_name)

    95             if library in template.builtins:

    96                 tag_library = None

    97             else:

    98                 tag_library = module_name.split('.')[-1]

    99             filters.append({

   100                 'name': filter_name,

   101                 'title': title,

   102                 'body': body,

   103                 'meta': metadata,

   104                 'library': tag_library,

   105             })

   106     return render_to_response('admin_doc/template_filter_index.html', {

   107         'root_path': get_root_path(),

   108         'filters': filters

   109     }, context_instance=RequestContext(request))

   110 template_filter_index = staff_member_required(template_filter_index)

   111 

   112 def view_index(request):

   113     if not utils.docutils_is_available:

   114         return missing_docutils_page(request)

   115 

   116     if settings.ADMIN_FOR:

   117         settings_modules = [__import__(m, {}, {}, ['']) for m in settings.ADMIN_FOR]

   118     else:

   119         settings_modules = [settings]

   120 

   121     views = []

   122     for settings_mod in settings_modules:

   123         urlconf = __import__(settings_mod.ROOT_URLCONF, {}, {}, [''])

   124         view_functions = extract_views_from_urlpatterns(urlconf.urlpatterns)

   125         if Site._meta.installed:

   126             site_obj = Site.objects.get(pk=settings_mod.SITE_ID)

   127         else:

   128             site_obj = GenericSite()

   129         for (func, regex) in view_functions:

   130             views.append({

   131                 'name': func.__name__,

   132                 'module': func.__module__,

   133                 'site_id': settings_mod.SITE_ID,

   134                 'site': site_obj,

   135                 'url': simplify_regex(regex),

   136             })

   137     return render_to_response('admin_doc/view_index.html', {

   138         'root_path': get_root_path(),

   139         'views': views

   140     }, context_instance=RequestContext(request))

   141 view_index = staff_member_required(view_index)

   142 

   143 def view_detail(request, view):

   144     if not utils.docutils_is_available:

   145         return missing_docutils_page(request)

   146 

   147     mod, func = urlresolvers.get_mod_func(view)

   148     try:

   149         view_func = getattr(__import__(mod, {}, {}, ['']), func)

   150     except (ImportError, AttributeError):

   151         raise Http404

   152     title, body, metadata = utils.parse_docstring(view_func.__doc__)

   153     if title:

   154         title = utils.parse_rst(title, 'view', _('view:') + view)

   155     if body:

   156         body = utils.parse_rst(body, 'view', _('view:') + view)

   157     for key in metadata:

   158         metadata[key] = utils.parse_rst(metadata[key], 'model', _('view:') + view)

   159     return render_to_response('admin_doc/view_detail.html', {

   160         'root_path': get_root_path(),

   161         'name': view,

   162         'summary': title,

   163         'body': body,

   164         'meta': metadata,

   165     }, context_instance=RequestContext(request))

   166 view_detail = staff_member_required(view_detail)

   167 

   168 def model_index(request):

   169     if not utils.docutils_is_available:

   170         return missing_docutils_page(request)

   171     m_list = [m._meta for m in models.get_models()]

   172     return render_to_response('admin_doc/model_index.html', {

   173         'root_path': get_root_path(),

   174         'models': m_list

   175     }, context_instance=RequestContext(request))

   176 model_index = staff_member_required(model_index)

   177 

   178 def model_detail(request, app_label, model_name):

   179     if not utils.docutils_is_available:

   180         return missing_docutils_page(request)

   181         

   182     # Get the model class.

   183     try:

   184         app_mod = models.get_app(app_label)

   185     except ImproperlyConfigured:

   186         raise Http404, _("App %r not found") % app_label

   187     model = None

   188     for m in models.get_models(app_mod):

   189         if m._meta.object_name.lower() == model_name:

   190             model = m

   191             break

   192     if model is None:

   193         raise Http404, _("Model %(model_name)r not found in app %(app_label)r") % {'model_name': model_name, 'app_label': app_label}

   194 

   195     opts = model._meta

   196 

   197     # Gather fields/field descriptions.

   198     fields = []

   199     for field in opts.fields:

   200         # ForeignKey is a special case since the field will actually be a

   201         # descriptor that returns the other object

   202         if isinstance(field, models.ForeignKey):

   203             data_type = related_object_name = field.rel.to.__name__

   204             app_label = field.rel.to._meta.app_label

   205             verbose = utils.parse_rst((_("the related `%(app_label)s.%(data_type)s` object")  % {'app_label': app_label, 'data_type': data_type}), 'model', _('model:') + data_type)

   206         else:

   207             data_type = get_readable_field_data_type(field)

   208             verbose = field.verbose_name

   209         fields.append({

   210             'name': field.name,

   211             'data_type': data_type,

   212             'verbose': verbose,

   213             'help_text': field.help_text,

   214         })

   215 

   216     # Gather model methods.

   217     for func_name, func in model.__dict__.items():

   218         if (inspect.isfunction(func) and len(inspect.getargspec(func)[0]) == 1):

   219             try:

   220                 for exclude in MODEL_METHODS_EXCLUDE:

   221                     if func_name.startswith(exclude):

   222                         raise StopIteration

   223             except StopIteration:

   224                 continue

   225             verbose = func.__doc__

   226             if verbose:

   227                 verbose = utils.parse_rst(utils.trim_docstring(verbose), 'model', _('model:') + opts.module_name)

   228             fields.append({

   229                 'name': func_name,

   230                 'data_type': get_return_data_type(func_name),

   231                 'verbose': verbose,

   232             })

   233 

   234     # Gather related objects

   235     for rel in opts.get_all_related_objects():

   236         verbose = _("related `%(app_label)s.%(object_name)s` objects") % {'app_label': rel.opts.app_label, 'object_name': rel.opts.object_name}

   237         accessor = rel.get_accessor_name()

   238         fields.append({

   239             'name'      : "%s.all" % accessor,

   240             'data_type' : 'List',

   241             'verbose'   : utils.parse_rst(_("all %s") % verbose , 'model', _('model:') + opts.module_name),

   242         })

   243         fields.append({

   244             'name'      : "%s.count" % accessor,

   245             'data_type' : 'Integer',

   246             'verbose'   : utils.parse_rst(_("number of %s") % verbose , 'model', _('model:') + opts.module_name),

   247         })

   248     return render_to_response('admin_doc/model_detail.html', {

   249         'root_path': get_root_path(),

   250         'name': '%s.%s' % (opts.app_label, opts.object_name),

   251         'summary': _("Fields on %s objects") % opts.object_name,

   252         'description': model.__doc__,

   253         'fields': fields,

   254     }, context_instance=RequestContext(request))

   255 model_detail = staff_member_required(model_detail)

   256 

   257 def template_detail(request, template):

   258     templates = []

   259     for site_settings_module in settings.ADMIN_FOR:

   260         settings_mod = __import__(site_settings_module, {}, {}, [''])

   261         if Site._meta.installed:

   262             site_obj = Site.objects.get(pk=settings_mod.SITE_ID)

   263         else:

   264             site_obj = GenericSite()

   265         for dir in settings_mod.TEMPLATE_DIRS:

   266             template_file = os.path.join(dir, "%s.html" % template)

   267             templates.append({

   268                 'file': template_file,

   269                 'exists': os.path.exists(template_file),

   270                 'contents': lambda: os.path.exists(template_file) and open(template_file).read() or '',

   271                 'site_id': settings_mod.SITE_ID,

   272                 'site': site_obj,

   273                 'order': list(settings_mod.TEMPLATE_DIRS).index(dir),

   274             })

   275     return render_to_response('admin_doc/template_detail.html', {

   276         'root_path': get_root_path(),

   277         'name': template,

   278         'templates': templates,

   279     }, context_instance=RequestContext(request))

   280 template_detail = staff_member_required(template_detail)

   281 

   282 ####################

   283 # Helper functions #

   284 ####################

   285 

   286 def missing_docutils_page(request):

   287     """Display an error message for people without docutils"""

   288     return render_to_response('admin_doc/missing_docutils.html')

   289 

   290 def load_all_installed_template_libraries():

   291     # Load/register all template tag libraries from installed apps.

   292     for e in templatetags.__path__:

   293         libraries = [os.path.splitext(p)[0] for p in os.listdir(e) if p.endswith('.py') and p[0].isalpha()]

   294         for library_name in libraries:

   295             try:

   296                 lib = template.get_library("django.templatetags.%s" % library_name.split('.')[-1])

   297             except template.InvalidTemplateLibrary:

   298                 pass

   299 

   300 def get_return_data_type(func_name):

   301     """Return a somewhat-helpful data type given a function name"""

   302     if func_name.startswith('get_'):

   303         if func_name.endswith('_list'):

   304             return 'List'

   305         elif func_name.endswith('_count'):

   306             return 'Integer'

   307     return ''

   308 

   309 # Maps Field objects to their human-readable data types, as strings.

   310 # Column-type strings can contain format strings; they'll be interpolated

   311 # against the values of Field.__dict__ before being output.

   312 # If a column type is set to None, it won't be included in the output.

   313 DATA_TYPE_MAPPING = {

   314     'AutoField'                 : _('Integer'),

   315     'BooleanField'              : _('Boolean (Either True or False)'),

   316     'CharField'                 : _('String (up to %(max_length)s)'),

   317     'CommaSeparatedIntegerField': _('Comma-separated integers'),

   318     'DateField'                 : _('Date (without time)'),

   319     'DateTimeField'             : _('Date (with time)'),

   320     'DecimalField'              : _('Decimal number'),

   321     'EmailField'                : _('E-mail address'),

   322     'FileField'                 : _('File path'),

   323     'FilePathField'             : _('File path'),

   324     'FloatField'                : _('Floating point number'),

   325     'ForeignKey'                : _('Integer'),

   326     'ImageField'                : _('File path'),

   327     'IntegerField'              : _('Integer'),

   328     'IPAddressField'            : _('IP address'),

   329     'ManyToManyField'           : '',

   330     'NullBooleanField'          : _('Boolean (Either True, False or None)'),

   331     'OneToOneField'             : _('Relation to parent model'),

   332     'PhoneNumberField'          : _('Phone number'),

   333     'PositiveIntegerField'      : _('Integer'),

   334     'PositiveSmallIntegerField' : _('Integer'),

   335     'SlugField'                 : _('String (up to %(max_length)s)'),

   336     'SmallIntegerField'         : _('Integer'),

   337     'TextField'                 : _('Text'),

   338     'TimeField'                 : _('Time'),

   339     'URLField'                  : _('URL'),

   340     'USStateField'              : _('U.S. state (two uppercase letters)'),

   341     'XMLField'                  : _('XML text'),

   342 }

   343 

   344 def get_readable_field_data_type(field):

   345     return DATA_TYPE_MAPPING[field.get_internal_type()] % field.__dict__

   346 

   347 def extract_views_from_urlpatterns(urlpatterns, base=''):

   348     """

   349     Return a list of views from a list of urlpatterns.

   350 

   351     Each object in the returned list is a two-tuple: (view_func, regex)

   352     """

   353     views = []

   354     for p in urlpatterns:

   355         if hasattr(p, '_get_callback'):

   356             try:

   357                 views.append((p._get_callback(), base + p.regex.pattern))

   358             except ViewDoesNotExist:

   359                 continue

   360         elif hasattr(p, '_get_url_patterns'):

   361             try:

   362                 patterns = p.url_patterns

   363             except ImportError:

   364                 continue

   365             views.extend(extract_views_from_urlpatterns(patterns, base + p.regex.pattern))

   366         else:

   367             raise TypeError, _("%s does not appear to be a urlpattern object") % p

   368     return views

   369 

   370 named_group_matcher = re.compile(r'\(\?P(<\w+>).+?\)')

   371 non_named_group_matcher = re.compile(r'\(.*?\)')

   372 

   373 def simplify_regex(pattern):

   374     """

   375     Clean up urlpattern regexes into something somewhat readable by Mere Humans:

   376     turns something like "^(?P<sport_slug>\w+)/athletes/(?P<athlete_slug>\w+)/$"

   377     into "<sport_slug>/athletes/<athlete_slug>/"

   378     """

   379     # handle named groups first

   380     pattern = named_group_matcher.sub(lambda m: m.group(1), pattern)

   381 

   382     # handle non-named groups

   383     pattern = non_named_group_matcher.sub("<var>", pattern)

   384 

   385     # clean up any outstanding regex-y characters.

   386     pattern = pattern.replace('^', '').replace('$', '').replace('?', '').replace('//', '/').replace('\\', '')

   387     if not pattern.startswith('/'):

   388         pattern = '/' + pattern

   389     return pattern