fc14addb6c87366d8d556148ae6939b0f8949335
[wolnelektury.git] / apps / piston / doc.py
1 import inspect, handler
2
3 from piston.handler import typemapper
4 from piston.handler import handler_tracker
5
6 from django.core.urlresolvers import get_resolver, get_callable, get_script_prefix
7 from django.shortcuts import render_to_response
8 from django.template import RequestContext
9
10 def generate_doc(handler_cls):
11     """
12     Returns a `HandlerDocumentation` object
13     for the given handler. Use this to generate
14     documentation for your API.
15     """
16     if not type(handler_cls) is handler.HandlerMetaClass:
17         raise ValueError("Give me handler, not %s" % type(handler_cls))
18
19     return HandlerDocumentation(handler_cls)
20
21 class HandlerMethod(object):
22     def __init__(self, method, stale=False):
23         self.method = method
24         self.stale = stale
25
26     def iter_args(self):
27         args, _, _, defaults = inspect.getargspec(self.method)
28
29         for idx, arg in enumerate(args):
30             if arg in ('self', 'request', 'form'):
31                 continue
32
33             didx = len(args)-idx
34
35             if defaults and len(defaults) >= didx:
36                 yield (arg, str(defaults[-didx]))
37             else:
38                 yield (arg, None)
39
40     @property
41     def signature(self, parse_optional=True):
42         spec = ""
43
44         for argn, argdef in self.iter_args():
45             spec += argn
46
47             if argdef:
48                 spec += '=%s' % argdef
49
50             spec += ', '
51
52         spec = spec.rstrip(", ")
53
54         if parse_optional:
55             return spec.replace("=None", "=<optional>")
56
57         return spec
58
59     @property
60     def doc(self):
61         return inspect.getdoc(self.method)
62
63     @property
64     def name(self):
65         return self.method.__name__
66
67     @property
68     def http_name(self):
69         if self.name == 'read':
70             return 'GET'
71         elif self.name == 'create':
72             return 'POST'
73         elif self.name == 'delete':
74             return 'DELETE'
75         elif self.name == 'update':
76             return 'PUT'
77
78     def __repr__(self):
79         return "<Method: %s>" % self.name
80
81 class HandlerDocumentation(object):
82     def __init__(self, handler):
83         self.handler = handler
84
85     def get_methods(self, include_default=False):
86         for method in "read create update delete".split():
87             met = getattr(self.handler, method, None)
88
89             if not met:
90                 continue
91
92             stale = inspect.getmodule(met) is handler
93
94             if not self.handler.is_anonymous:
95                 if met and (not stale or include_default):
96                     yield HandlerMethod(met, stale)
97             else:
98                 if not stale or met.__name__ == "read" \
99                     and 'GET' in self.allowed_methods:
100
101                     yield HandlerMethod(met, stale)
102
103     def get_all_methods(self):
104         return self.get_methods(include_default=True)
105
106     @property
107     def is_anonymous(self):
108         return handler.is_anonymous
109
110     def get_model(self):
111         return getattr(self, 'model', None)
112
113     @property
114     def has_anonymous(self):
115         return self.handler.anonymous
116
117     @property
118     def anonymous(self):
119         if self.has_anonymous:
120             return HandlerDocumentation(self.handler.anonymous)
121
122     @property
123     def doc(self):
124         return self.handler.__doc__
125
126     @property
127     def name(self):
128         return self.handler.__name__
129
130     @property
131     def allowed_methods(self):
132         return self.handler.allowed_methods
133
134     def get_resource_uri_template(self):
135         """
136         URI template processor.
137
138         See http://bitworking.org/projects/URI-Templates/
139         """
140         def _convert(template, params=[]):
141             """URI template converter"""
142             paths = template % dict([p, "{%s}" % p] for p in params)
143             return u'%s%s' % (get_script_prefix(), paths)
144
145         try:
146             resource_uri = self.handler.resource_uri()
147
148             components = [None, [], {}]
149
150             for i, value in enumerate(resource_uri):
151                 components[i] = value
152
153             lookup_view, args, kwargs = components
154             lookup_view = get_callable(lookup_view, True)
155
156             possibilities = get_resolver(None).reverse_dict.getlist(lookup_view)
157
158             for possibility, pattern in possibilities:
159                 for result, params in possibility:
160                     if args:
161                         if len(args) != len(params):
162                             continue
163                         return _convert(result, params)
164                     else:
165                         if set(kwargs.keys()) != set(params):
166                             continue
167                         return _convert(result, params)
168         except:
169             return None
170
171     resource_uri_template = property(get_resource_uri_template)
172
173     def __repr__(self):
174         return u'<Documentation for "%s">' % self.name
175
176 def documentation_view(request):
177     """
178     Generic documentation view. Generates documentation
179     from the handlers you've defined.
180     """
181     docs = [ ]
182
183     for handler in handler_tracker:
184         docs.append(generate_doc(handler))
185
186     def _compare(doc1, doc2):
187        #handlers and their anonymous counterparts are put next to each other.
188        name1 = doc1.name.replace("Anonymous", "")
189        name2 = doc2.name.replace("Anonymous", "")
190        return cmp(name1, name2)
191
192     docs.sort(_compare)
193
194     return render_to_response('documentation.html',
195         { 'docs': docs }, RequestContext(request))