1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
|
"""
This module contains all functions which are used to improve the documentation of methods.
"""
import re
RE_GET_FOO_DISPLAY = re.compile(r"\.get_(?P<field>[a-zA-Z0-9_]+)_display$")
RE_GET_NEXT_BY = re.compile(r"\.get_next_by_(?P<field>[a-zA-Z0-9_]+)$")
RE_GET_PREVIOUS_BY = re.compile(r"\.get_previous_by_(?P<field>[a-zA-Z0-9_]+)$")
def improve_method_docstring(name, lines):
"""
Improve the documentation of methods automatically contributed to models by Django:
* :meth:`~django.db.models.Model.get_FOO_display`
* :meth:`~django.db.models.Model.get_next_by_FOO`
* :meth:`~django.db.models.Model.get_previous_by_FOO`
:param name: The full dotted path to the object.
:type name: str
:param lines: The lines of docstring lines
:type lines: list [ str ]
"""
if not lines:
# Not doing obj.__module__ lookups to avoid performance issues.
if name.endswith("_display"):
match = RE_GET_FOO_DISPLAY.search(name)
if match is not None:
# Django get_..._display method
lines.append(
f"Shows the label of the :attr:`{match.group('field')}`. See"
" :meth:`~django.db.models.Model.get_FOO_display` for more"
" information."
)
elif ".get_next_by_" in name:
match = RE_GET_NEXT_BY.search(name)
if match is not None:
lines.append(
f"Finds next instance based on :attr:`{match.group('field')}`. See"
" :meth:`~django.db.models.Model.get_next_by_FOO` for more"
" information."
)
elif ".get_previous_by_" in name:
match = RE_GET_PREVIOUS_BY.search(name)
if match is not None:
lines.append(
f"Finds previous instance based on :attr:`{match.group('field')}`."
" See :meth:`~django.db.models.Model.get_previous_by_FOO` for more"
" information."
)
|
