/django/contrib/admindocs/views.py

https://code.google.com/p/mango-py/ · Python · 387 lines · 338 code · 31 blank · 18 comment · 77 complexity · 206bcc7509b0258dc1bf733b2d2a0859 MD5 · raw file

  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.importlib import import_module
  13. from django.utils.translation import ugettext as _
  14. from django.utils.safestring import mark_safe
  15. import inspect, os, re
  16. # Exclude methods starting with these strings from documentation
  17. MODEL_METHODS_EXCLUDE = ('_', 'add_', 'delete', 'save', 'set_')
  18. class GenericSite(object):
  19. domain = 'example.com'
  20. name = 'my site'
  21. def get_root_path():
  22. try:
  23. return urlresolvers.reverse('admin:index')
  24. except urlresolvers.NoReverseMatch:
  25. from django.contrib import admin
  26. try:
  27. return urlresolvers.reverse(admin.site.root, args=[''])
  28. except urlresolvers.NoReverseMatch:
  29. return getattr(settings, "ADMIN_SITE_ROOT_URL", "/admin/")
  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. def bookmarklets(request):
  38. admin_root = get_root_path()
  39. return render_to_response('admin_doc/bookmarklets.html', {
  40. 'root_path': admin_root,
  41. 'admin_url': mark_safe("%s://%s%s" % (request.is_secure() and 'https' or 'http', request.get_host(), admin_root)),
  42. }, context_instance=RequestContext(request))
  43. bookmarklets = staff_member_required(bookmarklets)
  44. def template_tag_index(request):
  45. if not utils.docutils_is_available:
  46. return missing_docutils_page(request)
  47. load_all_installed_template_libraries()
  48. tags = []
  49. app_libs = template.libraries.items()
  50. builtin_libs = [(None, lib) for lib in template.builtins]
  51. for module_name, library in builtin_libs + app_libs:
  52. for tag_name, tag_func in library.tags.items():
  53. title, body, metadata = utils.parse_docstring(tag_func.__doc__)
  54. if title:
  55. title = utils.parse_rst(title, 'tag', _('tag:') + tag_name)
  56. if body:
  57. body = utils.parse_rst(body, 'tag', _('tag:') + tag_name)
  58. for key in metadata:
  59. metadata[key] = utils.parse_rst(metadata[key], 'tag', _('tag:') + tag_name)
  60. if library in template.builtins:
  61. tag_library = None
  62. else:
  63. tag_library = module_name.split('.')[-1]
  64. tags.append({
  65. 'name': tag_name,
  66. 'title': title,
  67. 'body': body,
  68. 'meta': metadata,
  69. 'library': tag_library,
  70. })
  71. return render_to_response('admin_doc/template_tag_index.html', {
  72. 'root_path': get_root_path(),
  73. 'tags': tags
  74. }, context_instance=RequestContext(request))
  75. template_tag_index = staff_member_required(template_tag_index)
  76. def template_filter_index(request):
  77. if not utils.docutils_is_available:
  78. return missing_docutils_page(request)
  79. load_all_installed_template_libraries()
  80. filters = []
  81. app_libs = template.libraries.items()
  82. builtin_libs = [(None, lib) for lib in template.builtins]
  83. for module_name, library in builtin_libs + app_libs:
  84. for filter_name, filter_func in library.filters.items():
  85. title, body, metadata = utils.parse_docstring(filter_func.__doc__)
  86. if title:
  87. title = utils.parse_rst(title, 'filter', _('filter:') + filter_name)
  88. if body:
  89. body = utils.parse_rst(body, 'filter', _('filter:') + filter_name)
  90. for key in metadata:
  91. metadata[key] = utils.parse_rst(metadata[key], 'filter', _('filter:') + filter_name)
  92. if library in template.builtins:
  93. tag_library = None
  94. else:
  95. tag_library = module_name.split('.')[-1]
  96. filters.append({
  97. 'name': filter_name,
  98. 'title': title,
  99. 'body': body,
  100. 'meta': metadata,
  101. 'library': tag_library,
  102. })
  103. return render_to_response('admin_doc/template_filter_index.html', {
  104. 'root_path': get_root_path(),
  105. 'filters': filters
  106. }, context_instance=RequestContext(request))
  107. template_filter_index = staff_member_required(template_filter_index)
  108. def view_index(request):
  109. if not utils.docutils_is_available:
  110. return missing_docutils_page(request)
  111. if settings.ADMIN_FOR:
  112. settings_modules = [import_module(m) for m in settings.ADMIN_FOR]
  113. else:
  114. settings_modules = [settings]
  115. views = []
  116. for settings_mod in settings_modules:
  117. urlconf = import_module(settings_mod.ROOT_URLCONF)
  118. view_functions = extract_views_from_urlpatterns(urlconf.urlpatterns)
  119. if Site._meta.installed:
  120. site_obj = Site.objects.get(pk=settings_mod.SITE_ID)
  121. else:
  122. site_obj = GenericSite()
  123. for (func, regex) in view_functions:
  124. views.append({
  125. 'name': getattr(func, '__name__', func.__class__.__name__),
  126. 'module': func.__module__,
  127. 'site_id': settings_mod.SITE_ID,
  128. 'site': site_obj,
  129. 'url': simplify_regex(regex),
  130. })
  131. return render_to_response('admin_doc/view_index.html', {
  132. 'root_path': get_root_path(),
  133. 'views': views
  134. }, context_instance=RequestContext(request))
  135. view_index = staff_member_required(view_index)
  136. def view_detail(request, view):
  137. if not utils.docutils_is_available:
  138. return missing_docutils_page(request)
  139. mod, func = urlresolvers.get_mod_func(view)
  140. try:
  141. view_func = getattr(import_module(mod), func)
  142. except (ImportError, AttributeError):
  143. raise Http404
  144. title, body, metadata = utils.parse_docstring(view_func.__doc__)
  145. if title:
  146. title = utils.parse_rst(title, 'view', _('view:') + view)
  147. if body:
  148. body = utils.parse_rst(body, 'view', _('view:') + view)
  149. for key in metadata:
  150. metadata[key] = utils.parse_rst(metadata[key], 'model', _('view:') + view)
  151. return render_to_response('admin_doc/view_detail.html', {
  152. 'root_path': get_root_path(),
  153. 'name': view,
  154. 'summary': title,
  155. 'body': body,
  156. 'meta': metadata,
  157. }, context_instance=RequestContext(request))
  158. view_detail = staff_member_required(view_detail)
  159. def model_index(request):
  160. if not utils.docutils_is_available:
  161. return missing_docutils_page(request)
  162. m_list = [m._meta for m in models.get_models()]
  163. return render_to_response('admin_doc/model_index.html', {
  164. 'root_path': get_root_path(),
  165. 'models': m_list
  166. }, context_instance=RequestContext(request))
  167. model_index = staff_member_required(model_index)
  168. def model_detail(request, app_label, model_name):
  169. if not utils.docutils_is_available:
  170. return missing_docutils_page(request)
  171. # Get the model class.
  172. try:
  173. app_mod = models.get_app(app_label)
  174. except ImproperlyConfigured:
  175. raise Http404(_("App %r not found") % app_label)
  176. model = None
  177. for m in models.get_models(app_mod):
  178. if m._meta.object_name.lower() == model_name:
  179. model = m
  180. break
  181. if model is None:
  182. raise Http404(_("Model %(model_name)r not found in app %(app_label)r") % {'model_name': model_name, 'app_label': app_label})
  183. opts = model._meta
  184. # Gather fields/field descriptions.
  185. fields = []
  186. for field in opts.fields:
  187. # ForeignKey is a special case since the field will actually be a
  188. # descriptor that returns the other object
  189. if isinstance(field, models.ForeignKey):
  190. data_type = related_object_name = field.rel.to.__name__
  191. app_label = field.rel.to._meta.app_label
  192. 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)
  193. else:
  194. data_type = get_readable_field_data_type(field)
  195. verbose = field.verbose_name
  196. fields.append({
  197. 'name': field.name,
  198. 'data_type': data_type,
  199. 'verbose': verbose,
  200. 'help_text': field.help_text,
  201. })
  202. # Gather many-to-many fields.
  203. for field in opts.many_to_many:
  204. data_type = related_object_name = field.rel.to.__name__
  205. app_label = field.rel.to._meta.app_label
  206. verbose = _("related `%(app_label)s.%(object_name)s` objects") % {'app_label': app_label, 'object_name': data_type}
  207. fields.append({
  208. 'name': "%s.all" % field.name,
  209. "data_type": 'List',
  210. 'verbose': utils.parse_rst(_("all %s") % verbose , 'model', _('model:') + opts.module_name),
  211. })
  212. fields.append({
  213. 'name' : "%s.count" % field.name,
  214. 'data_type' : 'Integer',
  215. 'verbose' : utils.parse_rst(_("number of %s") % verbose , 'model', _('model:') + opts.module_name),
  216. })
  217. # Gather model methods.
  218. for func_name, func in model.__dict__.items():
  219. if (inspect.isfunction(func) and len(inspect.getargspec(func)[0]) == 1):
  220. try:
  221. for exclude in MODEL_METHODS_EXCLUDE:
  222. if func_name.startswith(exclude):
  223. raise StopIteration
  224. except StopIteration:
  225. continue
  226. verbose = func.__doc__
  227. if verbose:
  228. verbose = utils.parse_rst(utils.trim_docstring(verbose), 'model', _('model:') + opts.module_name)
  229. fields.append({
  230. 'name': func_name,
  231. 'data_type': get_return_data_type(func_name),
  232. 'verbose': verbose,
  233. })
  234. # Gather related objects
  235. for rel in opts.get_all_related_objects() + opts.get_all_related_many_to_many_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. def template_detail(request, template):
  257. templates = []
  258. for site_settings_module in settings.ADMIN_FOR:
  259. settings_mod = import_module(site_settings_module)
  260. if Site._meta.installed:
  261. site_obj = Site.objects.get(pk=settings_mod.SITE_ID)
  262. else:
  263. site_obj = GenericSite()
  264. for dir in settings_mod.TEMPLATE_DIRS:
  265. template_file = os.path.join(dir, template)
  266. templates.append({
  267. 'file': template_file,
  268. 'exists': os.path.exists(template_file),
  269. 'contents': lambda: os.path.exists(template_file) and open(template_file).read() or '',
  270. 'site_id': settings_mod.SITE_ID,
  271. 'site': site_obj,
  272. 'order': list(settings_mod.TEMPLATE_DIRS).index(dir),
  273. })
  274. return render_to_response('admin_doc/template_detail.html', {
  275. 'root_path': get_root_path(),
  276. 'name': template,
  277. 'templates': templates,
  278. }, context_instance=RequestContext(request))
  279. template_detail = staff_member_required(template_detail)
  280. ####################
  281. # Helper functions #
  282. ####################
  283. def missing_docutils_page(request):
  284. """Display an error message for people without docutils"""
  285. return render_to_response('admin_doc/missing_docutils.html')
  286. def load_all_installed_template_libraries():
  287. # Load/register all template tag libraries from installed apps.
  288. for module_name in template.get_templatetags_modules():
  289. mod = import_module(module_name)
  290. libraries = [
  291. os.path.splitext(p)[0]
  292. for p in os.listdir(os.path.dirname(mod.__file__))
  293. if p.endswith('.py') and p[0].isalpha()
  294. ]
  295. for library_name in libraries:
  296. try:
  297. lib = template.get_library(library_name)
  298. except template.InvalidTemplateLibrary, e:
  299. pass
  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. def get_readable_field_data_type(field):
  309. """Returns the description for a given field type, if it exists,
  310. Fields' descriptions can contain format strings, which will be interpolated
  311. against the values of field.__dict__ before being output."""
  312. return field.description % field.__dict__
  313. def extract_views_from_urlpatterns(urlpatterns, base=''):
  314. """
  315. Return a list of views from a list of urlpatterns.
  316. Each object in the returned list is a two-tuple: (view_func, regex)
  317. """
  318. views = []
  319. for p in urlpatterns:
  320. if hasattr(p, '_get_callback'):
  321. try:
  322. views.append((p._get_callback(), base + p.regex.pattern))
  323. except ViewDoesNotExist:
  324. continue
  325. elif hasattr(p, '_get_url_patterns'):
  326. try:
  327. patterns = p.url_patterns
  328. except ImportError:
  329. continue
  330. views.extend(extract_views_from_urlpatterns(patterns, base + p.regex.pattern))
  331. else:
  332. raise TypeError(_("%s does not appear to be a urlpattern object") % p)
  333. return views
  334. named_group_matcher = re.compile(r'\(\?P(<\w+>).+?\)')
  335. non_named_group_matcher = re.compile(r'\(.*?\)')
  336. def simplify_regex(pattern):
  337. """
  338. Clean up urlpattern regexes into something somewhat readable by Mere Humans:
  339. turns something like "^(?P<sport_slug>\w+)/athletes/(?P<athlete_slug>\w+)/$"
  340. into "<sport_slug>/athletes/<athlete_slug>/"
  341. """
  342. # handle named groups first
  343. pattern = named_group_matcher.sub(lambda m: m.group(1), pattern)
  344. # handle non-named groups
  345. pattern = non_named_group_matcher.sub("<var>", pattern)
  346. # clean up any outstanding regex-y characters.
  347. pattern = pattern.replace('^', '').replace('$', '').replace('?', '').replace('//', '/').replace('\\', '')
  348. if not pattern.startswith('/'):
  349. pattern = '/' + pattern
  350. return pattern