def build_query_parameters(self):
parameter_type = 'query'
params = self.get_method_parameter_data(parameter_type)
if params:
return params
params = []
docstring = self.retrieve_docstring() or ''
docstring += "\n" + get_view_description(self.callback)
docstring = trim_docstring(docstring)
if not docstring:
return params
split_lines = docstring.split('\n')
# TODO: use filter_class instead of docstring if available
for line in split_lines:
param = line.split(' -- ')
if len(param) == 2:
params.append({'paramType': parameter_type,
'name': param[0].strip(),
'description': param[1].strip(),
'dataType': ''})
return params
def get_notes(self):
"""
Returns the body of the docstring trimmed before any parameters are
listed. First, get the class docstring and then get the method's. The
methods will always inherit the class comments.
"""
sw_notes = self._get_swdocs('notes')
if sw_notes is not None:
return sw_notes
docstring = ""
class_docs = trim_docstring(get_view_description(self.callback))
method_docs = self.get_docs()
if class_docs is not None:
docstring += class_docs
if method_docs is not None:
docstring += '\n' + method_docs
docstring = IntrospectorHelper.strip_params_from_docstring(docstring)
docstring = re.sub(r'\n\s+\n', "<br/>", docstring)
docstring = docstring.replace("\n", " ")
return docstring
def get_description(self, path, method, view):
"""
Based on original SchemaGenerator.
This method take the class docstring directly,
and put break lines in sections correctly.
"""
method_docstring = self._get_method_docstring(view, method)
if method_docstring:
return method_docstring
description = get_view_description(view.__class__)
lines = [line.strip() for line in description.splitlines()]
current_section = ''
sections = {'': ''}
for line in lines:
if header_regex.match(line):
current_section, _, lead = line.partition(':')
sections[current_section] = lead.strip()
else:
sections[current_section] += '\n' + line
header = getattr(view, 'action', method.lower())
if header in sections:
return sections[header].strip()
if header in self.coerce_method_names:
if self.coerce_method_names[header] in sections:
return sections[self.coerce_method_names[header]].strip()
return sections[''].strip()
def build_query_params_from_docstring(self):
params = []
docstring = self.retrieve_docstring() or ''
docstring += "\n" + get_view_description(self.callback)
split_lines = docstring.split('\n')
for line in split_lines:
param = line.split(' -- ')
if len(param) == 2:
name, description = param
type = 'form'
if '[q]' in description:
type = 'query'
description = description.replace('[q]', '')
if '[b]' in description:
type = 'body'
description = description.replace('[b]', '')
params.append({
'paramType': type,
'name': name.strip(),
'description': description.strip(),
'dataType': ''
})
return params
def build_query_params_from_docstring(self, callback, method=None):
params = []
# Combine class & method level comments. If parameters are specified
if method is not None:
docstring = self.eval_method_docstring(callback, method)
params += self.build_query_params_from_docstring(callback)
else: # Get the class docstring
docstring = get_view_description(callback)
if docstring is None:
return params
split_lines = docstring.split('\n')
for line in split_lines:
param = line.split(' -- ')
if len(param) == 2:
params.append({
'paramType': 'query',
'name': param[0].strip(),
'description': param[1].strip(),
'dataType': ''
})
return params
def __build_query_params_from_docstring__(self, callback, method=None):
params = []
# Combine class & method level comments. If parameters are specified
if method is not None:
docstring = self.__eval_method_docstring_(callback, method)
params += self.__build_query_params_from_docstring__(callback)
else: # Otherwise, get the class level docstring
docstring = get_view_description(callback)
if docstring is None:
return params
split_lines = docstring.split('\n')
for line in split_lines:
param = line.split(' -- ')
if len(param) == 2:
params.append({
'paramType': 'query',
'name': param[0].strip(),
'description': param[1].strip(),
'dataType': '',
})
return params
def get_notes(self):
"""
Returns the body of the docstring trimmed before any parameters are
listed. First, get the class docstring and then get the method's. The
methods will always inherit the class comments.
"""
sw_notes = self._get_swdocs('notes')
if sw_notes is not None:
return sw_notes
docstring = ""
class_docs = trim_docstring(get_view_description(self.callback))
method_docs = self.get_docs()
if class_docs is not None:
docstring += class_docs
if method_docs is not None:
docstring += '\n' + method_docs
docstring = IntrospectorHelper.strip_params_from_docstring(docstring)
docstring = re.sub(r'\n\s+\n', "<br/>", docstring)
docstring = docstring.replace("\n", " ")
return docstring
def __get_notes__(self, callback, method=None):
"""
Returns the body of the docstring trimmed before any parameters are
listed. First, get the class docstring and then get the method's. The
methods will always inherit the class comments.
"""
docstring = ""
if method is not None:
docs = []
class_docs = self.__get_notes__(callback)
method_docs = self.__eval_method_docstring_(callback, method)
if class_docs is not None:
docs.append(class_docs)
if method_docs is not None:
docs.append(method_docs)
docstring += "\n".join(docs)
else:
docstring = trim_docstring(get_view_description(callback))
docstring = self.__strip_params_from_docstring__(docstring)
docstring = docstring.replace("\n", "<br/>")
return docstring
def parse_params_from_docstring(self):
params = []
docstring = self.retrieve_docstring()
if docstring is None:
docstring = ''
docstring += "\n" + get_view_description(self.callback)
if docstring is None:
return params
split_lines = docstring.split('\n')
for line in split_lines:
param = line.split(' -- ')
if len(param) == 2:
paramtype = 'query'
match = re.match(r"\((P|B|F|Q)\).*", param[0].strip())
if match:
annotated = match.group(1)
param[0] = re.sub(r"\((P|B|F|Q)\)", "", param[0].strip())
if annotated == "P":
paramtype = "path"
elif annotated == "B":
paramtype = "body"
elif annotated == "F":
paramtype = "form"
params.append({'paramType': paramtype,
'name': param[0].strip(),
'description': param[1].strip(),
'dataType': ''})
return params
def build_query_params_from_docstring(self):
params = []
docstring = self.retrieve_docstring() if None else ''
docstring += "\n" + get_view_description(self.callback)
if docstring is None:
return params
split_lines = docstring.split('\n')
for line in split_lines:
param = line.split(' -- ')
if len(param) == 2:
params.append({'paramType': 'query',
'name': param[0].strip(),
'description': param[1].strip(),
'dataType': ''})
if len(param) == 3:
paramtype = param[1].strip()
allowed_paramtypes = ['query', 'form', 'body', 'path']
if any(paramtype in s for s in allowed_paramtypes):
params.append({'paramType': paramtype,
'name': param[0].strip(),
'description': param[1].strip(),
'dataType': ''})
else:
params.append({'paramType': 'query',
'name': param[0].strip(),
'description': param[1].strip(),
'dataType': 'string'})
return params
def get_description(self, path, method, view):
"""
Based on original SchemaGenerator.
This method take the class docstring directly,
and put break lines in sections correctly.
"""
method_docstring = self._get_method_docstring(view, method)
if method_docstring:
return method_docstring
description = get_view_description(view.__class__)
lines = [line.strip() for line in description.splitlines()]
current_section = ''
sections = {'': ''}
for line in lines:
if header_regex.match(line):
current_section, _, lead = line.partition(':')
sections[current_section] = lead.strip()
else:
sections[current_section] += '\n' + line
header = getattr(view, 'action', method.lower())
if header in sections:
return sections[header].strip()
if header in self.coerce_method_names:
if self.coerce_method_names[header] in sections:
return sections[self.coerce_method_names[header]].strip()
return sections[''].strip()
def build_query_params_from_docstring(self):
params = []
docstring = self.retrieve_docstring() or ''
docstring += "\n" + get_view_description(self.callback)
if docstring is None:
return params
split_lines = docstring.split('\n')
for line in split_lines:
param = line.split(' -- ')
if len(param) == 2:
params.append({'paramType': 'query',
'name': param[0].strip(),
'description': param[1].strip(),
'dataType': ''})
elif len(param) == 3:
params.append({'paramType': param[2].strip(),
'name': param[0].strip(),
'description': param[1].strip(),
'dataType': ''})
elif len(param) == 4:
params.append({'paramType': param[2].strip(),
'name': param[0].strip(),
'description': param[1].strip(),
'dataType': param[3].strip()})
return params
def build_query_params_from_docstring(self):
params = []
docstring = self.retrieve_docstring() or ''
docstring += "\n" + get_view_description(self.callback)
split_lines = docstring.split('\n')
for line in split_lines:
param = line.split(' -- ')
if len(param) == 2:
name, description = param
type = 'form'
if '[q]' in description:
type = 'query'
description = description.replace('[q]', '')
if '[b]' in description:
type = 'body'
description = description.replace('[b]', '')
params.append({'paramType': type,
'name': name.strip(),
'description': description.strip(),
'dataType': ''})
return params
def __eval_method_docstring_(self, callback, method):
"""
Attempts to fetch the docs for a class method. Returns None
if the method does not exist
"""
try:
return get_view_description(eval("callback.%s" % (str(method).lower())))
except AttributeError:
return None
def get_view_description(view, html=False):
"""Wrapper around REST framework get_view_description() to continue
to support our historical div.
"""
desc = views.get_view_description(view, html=html)
if html:
desc = '<div class="description">%s</div>' % desc
return mark_safe(desc)
def get_view_description(callback):
"""
Returns the first sentence of the first line of the class docstring
"""
from .compat import strip_tags
description = get_view_description(callback).split("\n")[0].split(".")[0]
if apply_markdown:
description = strip_tags(do_markdown(description))
return description
def get_view_description(callback):
"""
Returns the first sentence of the first line of the class docstring
"""
from .compat import strip_tags
description = get_view_description(callback).split("\n")[0].split(
".")[0]
if apply_markdown:
description = strip_tags(do_markdown(description))
return description
def get_view_description(view_cls, html=False):
''' Replace example.com in Django REST framework's default API description
with the domain name of the current site '''
domain = Site.objects.get_current().domain
description = rest_framework_views.get_view_description(view_cls, html)
# description might not be a plain string: e.g. it could be a SafeText
# to prevent further HTML escaping
original_type = type(description)
description = original_type(
re.sub('(https*)://example.com', '\\1://{}'.format(domain),
description))
return description
def get_view_description(view_cls, html=False):
''' Replace example.com in Django REST framework's default API description
with the domain name of the current site '''
domain = Site.objects.get_current().domain
description = rest_framework_views.get_view_description(view_cls,
html)
# description might not be a plain string: e.g. it could be a SafeText
# to prevent further HTML escaping
original_type = type(description)
description = original_type(re.sub(
'(https*)://example.com',
'\\1://{}'.format(domain),
description
))
return description
def get_view_description(cls, html=False):
'''
Wrapper around REST framework get_view_description() to support
get_description() method and view_description property on a view class.
'''
if hasattr(cls, 'get_description') and callable(cls.get_description):
desc = cls().get_description(html=html)
cls = type(cls.__name__, (object,), {'__doc__': desc})
elif hasattr(cls, 'view_description'):
if callable(cls.view_description):
view_desc = cls.view_description()
else:
view_desc = cls.view_description
cls = type(cls.__name__, (object,), {'__doc__': view_desc})
desc = views.get_view_description(cls, html=html)
if html:
desc = '<div class="description">%s</div>' % desc
return mark_safe(desc)
def parse_params_from_docstring(self):
params = []
docstring = self.retrieve_docstring()
if docstring is None:
docstring = ''
docstring += "\n" + get_view_description(self.callback)
if docstring is None:
return params
split_lines = docstring.split('\n')
for line in split_lines:
param = line.split(' -- ')
if len(param) == 2:
param_name = param[0].strip()
param_description = param[1].strip()
param_type = 'query'
param_types = {
'GET': 'query',
'POST': 'form',
'HEADER': 'header',
}
data_type = 'string'
match = re.search(r'^(GET|POST|HEADER):(.*)', param_name)
if match:
param_type = param_types.get(match.group(1))
param_name = match.group(2).strip()
match = re.search(r'(.*)\((.*)\)', param_description)
if match:
param_description = match.group(1).strip()
data_type = match.group(2)
params.append({'paramType': escape(param_type),
'name': escape(param_name),
'description': escape(param_description),
'dataType': escape(data_type)})
return params
def metadata(self, request):
"""
Return a dictionary of metadata about the view.
Used to return responses for OPTIONS requests.
"""
# This is used by ViewSets to disambiguate instance vs list views
view_name_suffix = getattr(self, 'suffix', None)
# By default we can't provide any form-like information, however the
# generic views override this implementation and add additional
# information for POST and PUT methods, based on the serializer.
ret = SortedDict()
ret['name'] = get_view_name(self.__class__, view_name_suffix)
ret['description'] = get_view_description(self.__class__)
ret['renders'] = [renderer.media_type for renderer in self.renderer_classes]
ret['parses'] = [parser.media_type for parser in self.parser_classes]
ret['filters'] = OrderHistoryFilter.Meta.fields
return ret
def get_notes(self):
"""
Returns the body of the docstring trimmed before any parameters are
listed. First, get the class docstring and then get the method's. The
methods will always inherit the class comments.
"""
docstring = ""
class_docs = trim_docstring(get_view_description(self.callback))
method_docs = trim_docstring(self.get_docs())
if class_docs is not None:
docstring += class_docs
if method_docs is not None:
docstring += '\n\n' + method_docs
docstring = IntrospectorHelper.strip_params_from_docstring(docstring)
docstring = markdown.markdown(escape(docstring))
return docstring
def metadata(self, request):
"""
Return a dictionary of metadata about the view.
Used to return responses for OPTIONS requests.
"""
# This is used by ViewSets to disambiguate instance vs list views
view_name_suffix = getattr(self, 'suffix', None)
# By default we can't provide any form-like information, however the
# generic views override this implementation and add additional
# information for POST and PUT methods, based on the serializer.
ret = SortedDict()
ret['name'] = get_view_name(self.__class__, view_name_suffix)
ret['description'] = get_view_description(self.__class__)
ret['renders'] = [
renderer.media_type for renderer in self.renderer_classes
]
ret['parses'] = [parser.media_type for parser in self.parser_classes]
ret['filters'] = OrderHistoryFilter.Meta.fields
return ret
def get_view_description(self, html):
"""
Return extended / dynamic view description for
detail view.
"""
doc = super(UserAccountViewSet, self).get_view_description(html=False)
if self.action == 'retrieve':
pk = self.kwargs.get('pk', 1)
detail_urls = ['deposit', 'purchase']
doc += "\n\n**Available detail routes:**\n\n"
for detail in detail_urls:
url = "/api/users/{pk}/{detail}/".format(pk=pk, detail=detail)
doc += "* [{url}]({url})\n".format(url=url)
doc += "\n\n"
cls = type('CLS', (), {"__doc__": doc})
return views.get_view_description(cls, html)
def build_query_params_from_docstring(self):
params = []
docstring = self.retrieve_docstring() or ''
docstring += "\n" + get_view_description(self.callback)
if docstring is None:
return params
split_lines = docstring.split('\n')
for line in split_lines:
param = line.split(' -- ')
if len(param) == 2:
params.append({
'paramType': 'query',
'name': param[0].strip(),
'description': param[1].strip(),
'dataType': ''
})
return params
def __get_notes__(self, callback, method=None):
"""
Returns the body of the docstring trimmed before any parameters are
listed. First, get the class docstring and then get the method's. The
methods will always inherit the class comments.
"""
docstring = ""
if method is not None:
class_docs = self.__get_notes__(callback)
method_docs = self.__eval_method_docstring_(callback, method)
if class_docs is not None:
docstring += class_docs
if method_docs is not None:
docstring += method_docs
else:
docstring = trim_docstring(get_view_description(callback, html=True))
docstring = self.__strip_params_from_docstring__(docstring)
return docstring
def build_query_params_from_docstring(self, callback, method=None):
params = []
# Combine class & method level comments. If parameters are specified
if method is not None:
docstring = self.eval_method_docstring(callback, method)
params += self.build_query_params_from_docstring(callback)
else: # Get the class docstring
docstring = get_view_description(callback)
if docstring is None:
return params
split_lines = docstring.split("\n")
for line in split_lines:
param = line.split(" -- ")
if len(param) == 2:
params.append(
{"paramType": "query", "name": param[0].strip(), "description": param[1].strip(), "dataType": ""}
)
return params
def get_notes(self, callback, method=None, path=None):
"""
Returns the body of the docstring trimmed before any parameters are
listed. First, get the class docstring and then get the method's. The
methods will always inherit the class comments.
"""
docstring = ""
if method is not None:
class_docs = self.get_notes(callback)
method_docs = self.get_method_docs(callback, method, path)
if class_docs is not None:
docstring += class_docs
if method_docs is not None:
docstring = '%s \n %s' % (class_docs, method_docs)
else:
docstring = trim_docstring(get_view_description(callback))
docstring = self.strip_params_from_docstring(docstring)
docstring = docstring.replace("\n\n", "<br/>")
return docstring
def get_notes(self, callback, method=None, path=None):
"""
Returns the body of the docstring trimmed before any parameters are
listed. First, get the class docstring and then get the method's. The
methods will always inherit the class comments.
"""
docstring = ""
if method is not None:
class_docs = self.get_notes(callback)
method_docs = self.get_method_docs(callback, method, path)
if class_docs is not None:
docstring += class_docs
if method_docs is not None:
docstring += '\n' + method_docs
else:
docstring = trim_docstring(get_view_description(callback))
docstring = self.strip_params_from_docstring(docstring)
docstring = docstring.replace("\n\n", "<br/>")
return docstring
def __get_notes__(self, callback, method=None):
"""
Returns the body of the docstring trimmed before any parameters are
listed. First, get the class docstring and then get the method's. The
methods will always inherit the class comments.
"""
docstring = ""
if method is not None:
class_docs = self.__get_notes__(callback)
method_docs = self.__eval_method_docstring_(callback, method)
if class_docs is not None:
docstring += class_docs
if method_docs is not None:
docstring += method_docs
else:
docstring = trim_docstring(get_view_description(callback))
docstring = self.__strip_params_from_docstring__(docstring)
docstring = docstring.replace("\n", "<br/>")
return docstring
def build_query_params_from_docstring(self):
params = []
docstring = self.retrieve_docstring() if None else ''
docstring += "\n" + get_view_description(self.callback)
method_docs = self.get_docs()
if method_docs is not None:
docstring += '\n' + method_docs
if docstring is None:
return params
split_lines = docstring.split('\n')
for line in split_lines:
param = line.split(' -- ')
if len(param) == 3:
params.append({'paramType': 'query',
'name': param[0].strip(),
'description': param[1].strip(),
'dataType': param[2].strip()})
return params
def get_view_description(callback):
"""
Returns the first sentence of the first line of the class docstring
"""
return get_view_description(callback).split("\n")[0].split(".")[0]
def __get_description__(self, callback):
"""
Returns the first sentence of the first line of the class docstring
"""
return get_view_description(callback, html=True).split("\n")[0].split(".")[0]
def get_view_description(callback):
"""
Returns the first sentence of the first line of the class docstring
"""
return get_view_description(callback).split("\n")[0].split(".")[0]
def __get_description__(self, callback):
"""
Returns the first sentence of the first line of the class docstring
"""
return get_view_description(callback,
html=True).split("\n")[0].split(".")[0]
def to_html(docstring):
class A:
pass # manage to use REST framework code.
A.__doc__ = docstring
return get_view_description(A, html=True)
def get_view_description(cls, callback):
"""
Returns the docstring for the given callback
"""
return get_view_description(callback)
def to_html(docstring):
class A: pass # manage to use REST framework code.
A.__doc__ = docstring
return get_view_description(A, html=True)
