app/django/contrib/admindocs/views.py

   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