code-annotations 3.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- code_annotations/__init__.py +6 -0
- code_annotations/annotation_errors.py +64 -0
- code_annotations/base.py +647 -0
- code_annotations/cli.py +271 -0
- code_annotations/contrib/README.rst +8 -0
- code_annotations/contrib/config/__init__.py +14 -0
- code_annotations/contrib/config/feature_toggle_annotations.yaml +29 -0
- code_annotations/contrib/config/openedx_events_annotations.yaml +20 -0
- code_annotations/contrib/config/setting_annotations.yaml +13 -0
- code_annotations/contrib/sphinx/extensions/__init__.py +3 -0
- code_annotations/contrib/sphinx/extensions/base.py +53 -0
- code_annotations/contrib/sphinx/extensions/featuretoggles.py +137 -0
- code_annotations/contrib/sphinx/extensions/openedx_events.py +182 -0
- code_annotations/contrib/sphinx/extensions/settings.py +139 -0
- code_annotations/exceptions.py +9 -0
- code_annotations/extensions/__init__.py +3 -0
- code_annotations/extensions/base.py +166 -0
- code_annotations/extensions/javascript.py +20 -0
- code_annotations/extensions/python.py +20 -0
- code_annotations/find_django.py +460 -0
- code_annotations/find_static.py +96 -0
- code_annotations/generate_docs.py +165 -0
- code_annotations/helpers.py +182 -0
- code_annotations/report_templates/html/annotation.tpl +14 -0
- code_annotations/report_templates/html/annotation_data.tpl +8 -0
- code_annotations/report_templates/html/annotation_list.tpl +27 -0
- code_annotations/report_templates/html/base.tpl +92 -0
- code_annotations/report_templates/rst/annotation.tpl +13 -0
- code_annotations/report_templates/rst/annotation_data.tpl +8 -0
- code_annotations/report_templates/rst/annotation_group.tpl +2 -0
- code_annotations/report_templates/rst/annotation_list.tpl +34 -0
- code_annotations/report_templates/rst/base.tpl +41 -0
- code_annotations-3.1.0.dist-info/METADATA +82 -0
- code_annotations-3.1.0.dist-info/RECORD +39 -0
- code_annotations-3.1.0.dist-info/WHEEL +5 -0
- code_annotations-3.1.0.dist-info/entry_points.txt +6 -0
- code_annotations-3.1.0.dist-info/licenses/LICENSE.txt +202 -0
- code_annotations-3.1.0.dist-info/licenses/NOTICE.txt +13 -0
- code_annotations-3.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Sphinx extension for viewing openedx events annotations.
|
|
3
|
+
"""
|
|
4
|
+
import os
|
|
5
|
+
|
|
6
|
+
from docutils import nodes
|
|
7
|
+
from sphinx.util.docutils import SphinxDirective
|
|
8
|
+
|
|
9
|
+
from code_annotations.contrib.config import OPENEDX_EVENTS_ANNOTATIONS_CONFIG_PATH
|
|
10
|
+
|
|
11
|
+
from .base import find_annotations
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def find_events(source_path):
|
|
15
|
+
"""
|
|
16
|
+
Find the events as defined in the configuration file.
|
|
17
|
+
|
|
18
|
+
Return:
|
|
19
|
+
events (dict): found events indexed by event type.
|
|
20
|
+
"""
|
|
21
|
+
return find_annotations(
|
|
22
|
+
source_path, OPENEDX_EVENTS_ANNOTATIONS_CONFIG_PATH, ".. event_type:"
|
|
23
|
+
)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
class OpenedxEvents(SphinxDirective):
|
|
27
|
+
"""
|
|
28
|
+
Sphinx directive to list the events in a single documentation page.
|
|
29
|
+
|
|
30
|
+
Use this directive as follows::
|
|
31
|
+
|
|
32
|
+
.. openedxevents::
|
|
33
|
+
|
|
34
|
+
This directive supports the following configuration parameters:
|
|
35
|
+
|
|
36
|
+
- ``openedxevents_source_path``: absolute path to the repository file tree. E.g:
|
|
37
|
+
|
|
38
|
+
openedxevents_source_path = os.path.join(os.path.dirname(__file__), "..", "..")
|
|
39
|
+
|
|
40
|
+
- ``openedxevents_repo_url``: Github repository where the code is hosted. E.g:
|
|
41
|
+
|
|
42
|
+
openedxevents_repo_url = "https://github.com/openedx/myrepo"
|
|
43
|
+
|
|
44
|
+
- ``openedxevents_repo_version``: current version of the git repository. E.g:
|
|
45
|
+
|
|
46
|
+
import git
|
|
47
|
+
try:
|
|
48
|
+
repo = git.Repo(search_parent_directories=True)
|
|
49
|
+
openedxevents_repo_version = repo.head.object.hexsha
|
|
50
|
+
except git.InvalidGitRepositoryError:
|
|
51
|
+
openedxevents_repo_version = "main"
|
|
52
|
+
"""
|
|
53
|
+
|
|
54
|
+
required_arguments = 0
|
|
55
|
+
optional_arguments = 0
|
|
56
|
+
option_spec = {}
|
|
57
|
+
|
|
58
|
+
def run(self):
|
|
59
|
+
"""
|
|
60
|
+
Public interface of the Directive class.
|
|
61
|
+
|
|
62
|
+
Return:
|
|
63
|
+
nodes (list): nodes to be appended to the resulting document.
|
|
64
|
+
"""
|
|
65
|
+
return list(self.iter_nodes())
|
|
66
|
+
|
|
67
|
+
def iter_nodes(self):
|
|
68
|
+
"""
|
|
69
|
+
Iterate on the docutils nodes generated by this directive.
|
|
70
|
+
"""
|
|
71
|
+
events = find_events(self.env.config.openedxevents_source_path)
|
|
72
|
+
|
|
73
|
+
current_domain = ""
|
|
74
|
+
domain_header = None
|
|
75
|
+
current_subject = ""
|
|
76
|
+
subject_header = None
|
|
77
|
+
|
|
78
|
+
for event_type in sorted(events):
|
|
79
|
+
domain = event_type.split(".")[2]
|
|
80
|
+
subject = event_type.split(".")[3]
|
|
81
|
+
if domain != current_domain:
|
|
82
|
+
if domain_header:
|
|
83
|
+
yield domain_header
|
|
84
|
+
|
|
85
|
+
current_domain = domain
|
|
86
|
+
domain_header = nodes.section("", ids=[f"openedxevent-domain-{domain}"])
|
|
87
|
+
domain_header += nodes.title(text=f"Architectural subdomain: {domain}")
|
|
88
|
+
if subject != current_subject:
|
|
89
|
+
current_subject = subject
|
|
90
|
+
subject_header = nodes.section("", ids=[f"openedxevent-subject"
|
|
91
|
+
f"-{subject}"])
|
|
92
|
+
subject_header += nodes.title(text=f"Subject: {subject}")
|
|
93
|
+
domain_header += subject_header
|
|
94
|
+
|
|
95
|
+
event = events[event_type]
|
|
96
|
+
event_name = event[".. event_name:"]
|
|
97
|
+
event_name_literal = nodes.literal(text=event_name)
|
|
98
|
+
event_data = event[".. event_data:"]
|
|
99
|
+
event_data_literal = nodes.literal(text=event_data)
|
|
100
|
+
event_key_field = event.get(".. event_key_field:", "")
|
|
101
|
+
event_key_literal = nodes.literal(text=event_key_field)
|
|
102
|
+
event_description = event[".. event_description:"]
|
|
103
|
+
event_trigger_repository = event.get(".. event_trigger_repository:")
|
|
104
|
+
|
|
105
|
+
event_section = nodes.section("", ids=[f"openedxevent-{event_type}"])
|
|
106
|
+
event_section += nodes.title(text=event_type, ids=[f"title-{event_type}"])
|
|
107
|
+
event_section += nodes.paragraph(text=f"Description: "
|
|
108
|
+
f"{event_description}")
|
|
109
|
+
event_section += nodes.paragraph("", "Signal name: ", event_name_literal)
|
|
110
|
+
if event_key_field:
|
|
111
|
+
event_section += nodes.paragraph(
|
|
112
|
+
"",
|
|
113
|
+
"Event key field: ",
|
|
114
|
+
event_key_literal
|
|
115
|
+
)
|
|
116
|
+
event_section += nodes.paragraph("", "Event data: ", event_data_literal)
|
|
117
|
+
event_section += nodes.paragraph(
|
|
118
|
+
"",
|
|
119
|
+
"Defined at: ",
|
|
120
|
+
nodes.reference(
|
|
121
|
+
text="{} (line {})".format(
|
|
122
|
+
event["filename"], event["line_number"]
|
|
123
|
+
),
|
|
124
|
+
refuri="{}/blob/{}/{}#L{}".format(
|
|
125
|
+
self.env.config.openedxevents_repo_url,
|
|
126
|
+
self.env.config.openedxevents_repo_version,
|
|
127
|
+
event["filename"],
|
|
128
|
+
event["line_number"],
|
|
129
|
+
),
|
|
130
|
+
),
|
|
131
|
+
ids=[f"definition-{event_name}"],
|
|
132
|
+
)
|
|
133
|
+
|
|
134
|
+
if event_trigger_repository:
|
|
135
|
+
event_trigger_repository = event_trigger_repository.split(" ")
|
|
136
|
+
event_section += nodes.paragraph(text="Triggered by:", ids=[f"triggers-{event_name}"])
|
|
137
|
+
triggers_bullet_list = nodes.bullet_list()
|
|
138
|
+
for repository in event_trigger_repository:
|
|
139
|
+
search_url = f"https://github.com/search?q=repo:{repository}+{event_name}.send_event&type=code"
|
|
140
|
+
triggers_bullet_list += nodes.list_item(
|
|
141
|
+
"",
|
|
142
|
+
nodes.paragraph(
|
|
143
|
+
"",
|
|
144
|
+
"",
|
|
145
|
+
nodes.reference(
|
|
146
|
+
text=repository,
|
|
147
|
+
refuri=search_url,
|
|
148
|
+
),
|
|
149
|
+
),
|
|
150
|
+
)
|
|
151
|
+
|
|
152
|
+
event_section += triggers_bullet_list
|
|
153
|
+
|
|
154
|
+
if event.get(".. event_warning:") not in (None, "None", "n/a", "N/A"):
|
|
155
|
+
event_section += nodes.warning(
|
|
156
|
+
"", nodes.paragraph("", event[".. event_warning:"]), ids=[f"warning-{event_name}"]
|
|
157
|
+
)
|
|
158
|
+
|
|
159
|
+
subject_header += event_section
|
|
160
|
+
|
|
161
|
+
if domain_header:
|
|
162
|
+
yield domain_header
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def setup(app):
|
|
166
|
+
"""
|
|
167
|
+
Declare the Sphinx extension.
|
|
168
|
+
"""
|
|
169
|
+
app.add_config_value(
|
|
170
|
+
"openedxevents_source_path",
|
|
171
|
+
os.path.abspath(".."),
|
|
172
|
+
"env",
|
|
173
|
+
)
|
|
174
|
+
app.add_config_value("openedxevents_repo_url", "", "env")
|
|
175
|
+
app.add_config_value("openedxevents_repo_version", "main", "env")
|
|
176
|
+
app.add_directive("openedxevents", OpenedxEvents)
|
|
177
|
+
|
|
178
|
+
return {
|
|
179
|
+
"version": "0.1",
|
|
180
|
+
"parallel_read_safe": True,
|
|
181
|
+
"parallel_write_safe": True,
|
|
182
|
+
}
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Sphinx extension for viewing (non-toggle) setting annotations.
|
|
3
|
+
"""
|
|
4
|
+
import os
|
|
5
|
+
|
|
6
|
+
from docutils import nodes
|
|
7
|
+
from docutils.parsers.rst import directives
|
|
8
|
+
from sphinx.util.docutils import SphinxDirective
|
|
9
|
+
|
|
10
|
+
from code_annotations.contrib.config import SETTING_ANNOTATIONS_CONFIG_PATH
|
|
11
|
+
|
|
12
|
+
from .base import find_annotations, quote_value
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def find_settings(source_path):
|
|
16
|
+
"""
|
|
17
|
+
Find the Django settings as defined in the configuration file.
|
|
18
|
+
|
|
19
|
+
Return:
|
|
20
|
+
settings (dict): Django settings indexed by name.
|
|
21
|
+
"""
|
|
22
|
+
return find_annotations(
|
|
23
|
+
source_path, SETTING_ANNOTATIONS_CONFIG_PATH, ".. setting_name:"
|
|
24
|
+
)
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
class Settings(SphinxDirective):
|
|
28
|
+
"""
|
|
29
|
+
Sphinx directive to document Django settings in a single documentation page.
|
|
30
|
+
|
|
31
|
+
Use this directive as follows::
|
|
32
|
+
|
|
33
|
+
.. settings::
|
|
34
|
+
:folder_path: lms/envs/common.py
|
|
35
|
+
|
|
36
|
+
This directive supports the following configuration parameters:
|
|
37
|
+
|
|
38
|
+
- ``settings_source_path``: absolute path to the repository file tree. E.g:
|
|
39
|
+
|
|
40
|
+
settings_source_path = os.path.join(os.path.dirname(__file__), "..", "..")
|
|
41
|
+
|
|
42
|
+
- ``settings_repo_url``: Github repository where the code is hosted. E.g:
|
|
43
|
+
|
|
44
|
+
settings_repo_url = "https://github.com/openedx/myrepo"
|
|
45
|
+
|
|
46
|
+
- ``settings_repo_version``: current version of the git repository. E.g:
|
|
47
|
+
|
|
48
|
+
import git
|
|
49
|
+
try:
|
|
50
|
+
repo = git.Repo(search_parent_directories=True)
|
|
51
|
+
settings_repo_version = repo.head.object.hexsha
|
|
52
|
+
except git.InvalidGitRepositoryError:
|
|
53
|
+
settings_repo_version = "master"
|
|
54
|
+
"""
|
|
55
|
+
|
|
56
|
+
required_arguments = 0
|
|
57
|
+
optional_arguments = 1
|
|
58
|
+
option_spec = {"folder_path": directives.unchanged}
|
|
59
|
+
|
|
60
|
+
def run(self):
|
|
61
|
+
"""
|
|
62
|
+
Public interface of the Directive class.
|
|
63
|
+
|
|
64
|
+
Return:
|
|
65
|
+
nodes (list): nodes to be appended to the resulting document.
|
|
66
|
+
"""
|
|
67
|
+
return list(self.iter_nodes())
|
|
68
|
+
|
|
69
|
+
def iter_nodes(self):
|
|
70
|
+
"""
|
|
71
|
+
Iterate on the docutils nodes generated by this directive.
|
|
72
|
+
"""
|
|
73
|
+
folder_path = self.options.get("folder_path", "")
|
|
74
|
+
source_path = os.path.join(self.env.config.settings_source_path, folder_path)
|
|
75
|
+
settings = find_settings(source_path)
|
|
76
|
+
# folder_path can point to a file or directory
|
|
77
|
+
root_folder = (
|
|
78
|
+
folder_path if os.path.isdir(source_path) else os.path.dirname(folder_path)
|
|
79
|
+
)
|
|
80
|
+
for setting_name in sorted(settings):
|
|
81
|
+
setting = settings[setting_name]
|
|
82
|
+
# setting["filename"] is relative to the root_path
|
|
83
|
+
setting_filename = os.path.join(root_folder, setting["filename"])
|
|
84
|
+
setting_default_value = setting.get(".. setting_default:", "Not defined")
|
|
85
|
+
setting_default_node = nodes.literal(
|
|
86
|
+
text=quote_value(setting_default_value)
|
|
87
|
+
)
|
|
88
|
+
setting_section = nodes.section("", ids=[f"setting-{setting_name}"])
|
|
89
|
+
setting_section += nodes.title(text=setting_name, ids=[f"title-{setting_name}"])
|
|
90
|
+
setting_section += nodes.paragraph(
|
|
91
|
+
"", "Default: ", setting_default_node, ids=[f"default-{setting_name}"]
|
|
92
|
+
)
|
|
93
|
+
setting_section += nodes.paragraph(
|
|
94
|
+
"",
|
|
95
|
+
"Source: ",
|
|
96
|
+
nodes.reference(
|
|
97
|
+
text="{} (line {})".format(
|
|
98
|
+
setting["filename"], setting["line_number"]
|
|
99
|
+
),
|
|
100
|
+
refuri="{}/blob/{}/{}#L{}".format(
|
|
101
|
+
self.env.config.settings_repo_url,
|
|
102
|
+
self.env.config.settings_repo_version,
|
|
103
|
+
setting_filename,
|
|
104
|
+
setting["line_number"],
|
|
105
|
+
),
|
|
106
|
+
),
|
|
107
|
+
ids=[f"source-{setting_name}"],
|
|
108
|
+
)
|
|
109
|
+
setting_section += nodes.paragraph(
|
|
110
|
+
text=setting.get(".. setting_description:", ""),
|
|
111
|
+
ids=[f"description-{setting_name}"],
|
|
112
|
+
)
|
|
113
|
+
if setting.get(".. setting_warning:") not in (None, "None", "n/a", "N/A"):
|
|
114
|
+
setting_section += nodes.warning(
|
|
115
|
+
"",
|
|
116
|
+
nodes.paragraph("", setting[".. setting_warning:"]),
|
|
117
|
+
ids=[f"warning-{setting_name}"],
|
|
118
|
+
)
|
|
119
|
+
yield setting_section
|
|
120
|
+
|
|
121
|
+
|
|
122
|
+
def setup(app):
|
|
123
|
+
"""
|
|
124
|
+
Declare the Sphinx extension.
|
|
125
|
+
"""
|
|
126
|
+
app.add_config_value(
|
|
127
|
+
"settings_source_path",
|
|
128
|
+
os.path.abspath(".."),
|
|
129
|
+
"env",
|
|
130
|
+
)
|
|
131
|
+
app.add_config_value("settings_repo_url", "", "env")
|
|
132
|
+
app.add_config_value("settings_repo_version", "master", "env")
|
|
133
|
+
app.add_directive("settings", Settings)
|
|
134
|
+
|
|
135
|
+
return {
|
|
136
|
+
"version": "0.1",
|
|
137
|
+
"parallel_read_safe": True,
|
|
138
|
+
"parallel_write_safe": True,
|
|
139
|
+
}
|
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Abstract and base classes to support plugins.
|
|
3
|
+
"""
|
|
4
|
+
import re
|
|
5
|
+
from abc import ABCMeta, abstractmethod
|
|
6
|
+
|
|
7
|
+
from code_annotations.helpers import clean_abs_path, clean_annotation, get_annotation_regex
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class AnnotationExtension(metaclass=ABCMeta):
|
|
11
|
+
"""
|
|
12
|
+
Abstract base class that annotation extensions will inherit from.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
extension_name = None
|
|
16
|
+
|
|
17
|
+
def __init__(self, config, echo):
|
|
18
|
+
"""
|
|
19
|
+
Initialize this base object, save a handle to configuration.
|
|
20
|
+
|
|
21
|
+
Args:
|
|
22
|
+
config: The configuration object
|
|
23
|
+
echo: VerboseEcho object used for logging
|
|
24
|
+
"""
|
|
25
|
+
self.config = config
|
|
26
|
+
self.ECHO = echo
|
|
27
|
+
|
|
28
|
+
@abstractmethod
|
|
29
|
+
def search(self, file_handle): # pragma: no cover
|
|
30
|
+
"""
|
|
31
|
+
Search for annotations in the given file.
|
|
32
|
+
"""
|
|
33
|
+
raise NotImplementedError('search called on base class!')
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class SimpleRegexAnnotationExtension(AnnotationExtension, metaclass=ABCMeta):
|
|
37
|
+
"""
|
|
38
|
+
Abstract base class for languages that have comments which can be reasonably searched using regular expressions.
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
# These are the language-specific comment definitions that are defined in the child classes. See the
|
|
42
|
+
# Javascript and Python extensions for examples.
|
|
43
|
+
lang_comment_definition = None
|
|
44
|
+
|
|
45
|
+
# This format string/regex finds all comments in the file. The format tokens will be replaced with the
|
|
46
|
+
# language-specific comment definitions defined in the sub-classes.
|
|
47
|
+
#
|
|
48
|
+
# Match groupdict will contain two named subgroups: 'comment' and 'prefixed_comment', of which at most
|
|
49
|
+
# one will be non-None.
|
|
50
|
+
comment_regex_fmt = r"""
|
|
51
|
+
{multi_start} # start of the language-specific multi-line comment (ex. /*)
|
|
52
|
+
(?P<comment> # Look for a multiline comment
|
|
53
|
+
[\d\D]*? # capture all of the characters...
|
|
54
|
+
)
|
|
55
|
+
{multi_end} # until you find the end of the language-specific multi-line comment (ex. */)
|
|
56
|
+
| # If you don't find any of those...
|
|
57
|
+
(?P<prefixed_comment> # Look for a group of single-line comments
|
|
58
|
+
(?: # Non-capture mode
|
|
59
|
+
{single} # start by finding the single-line comment token (ex. //)
|
|
60
|
+
.* # and capture all characters until the end of the line
|
|
61
|
+
\n? # followed by an optional carriage return
|
|
62
|
+
\ * # and some empty space
|
|
63
|
+
)* # multiple times
|
|
64
|
+
)
|
|
65
|
+
"""
|
|
66
|
+
|
|
67
|
+
def __init__(self, config, echo):
|
|
68
|
+
"""
|
|
69
|
+
Set up the extension and create the regexes used to do searches.
|
|
70
|
+
|
|
71
|
+
Args:
|
|
72
|
+
config: The configuration dict
|
|
73
|
+
echo: VerboseEcho object for logging
|
|
74
|
+
"""
|
|
75
|
+
super().__init__(config, echo)
|
|
76
|
+
|
|
77
|
+
if self.lang_comment_definition is None: # pragma: no cover
|
|
78
|
+
raise ValueError('Subclasses of SimpleRegexAnnotationExtension must define lang_comment_definition!')
|
|
79
|
+
|
|
80
|
+
self.comment_regex = re.compile(
|
|
81
|
+
self.comment_regex_fmt.format(**self.lang_comment_definition),
|
|
82
|
+
flags=re.VERBOSE
|
|
83
|
+
)
|
|
84
|
+
self.prefixed_comment_regex = re.compile(
|
|
85
|
+
r"^ *{single}".format(**self.lang_comment_definition),
|
|
86
|
+
flags=re.MULTILINE
|
|
87
|
+
)
|
|
88
|
+
|
|
89
|
+
# Parent class will allow this class to populate self.strings_to_search via
|
|
90
|
+
# calls to _add_annotation_token or _add_annotation_group for each configured
|
|
91
|
+
# annotation.
|
|
92
|
+
self.query = get_annotation_regex(self.config.annotation_regexes)
|
|
93
|
+
|
|
94
|
+
self.ECHO.echo_v(f"{self.extension_name} extension regex query: {self.query.pattern}")
|
|
95
|
+
|
|
96
|
+
def search(self, file_handle):
|
|
97
|
+
"""
|
|
98
|
+
Search for annotations in the given file.
|
|
99
|
+
|
|
100
|
+
Args:
|
|
101
|
+
file_handle: Handle for the file to validate
|
|
102
|
+
|
|
103
|
+
Returns:
|
|
104
|
+
List of dicts describing found annotations, or an empty list
|
|
105
|
+
"""
|
|
106
|
+
txt = file_handle.read()
|
|
107
|
+
|
|
108
|
+
found_annotations = []
|
|
109
|
+
|
|
110
|
+
# Fast out if no annotations exist in the file
|
|
111
|
+
if any(anno in txt for anno in self.config.annotation_tokens):
|
|
112
|
+
fname = clean_abs_path(file_handle.name, self.config.source_path)
|
|
113
|
+
|
|
114
|
+
# Iterate on all comments: both prefixed- and non-prefixed.
|
|
115
|
+
for match in self.comment_regex.finditer(txt):
|
|
116
|
+
# Get the line number by counting newlines + 1 (for the first line).
|
|
117
|
+
# Note that this is the line number of the beginning of the comment, not the
|
|
118
|
+
# annotation token itself.
|
|
119
|
+
line = txt.count('\n', 0, match.start()) + 1
|
|
120
|
+
|
|
121
|
+
comment_content = self._find_comment_content(match)
|
|
122
|
+
for inner_match in self.query.finditer(comment_content):
|
|
123
|
+
try:
|
|
124
|
+
annotation_token = inner_match.group('token')
|
|
125
|
+
annotation_data = inner_match.group('data')
|
|
126
|
+
except IndexError as error:
|
|
127
|
+
# pragma: no cover
|
|
128
|
+
raise ValueError('{}::{}: Could not find "data" or "token" groups. Found: {}'.format(
|
|
129
|
+
fname,
|
|
130
|
+
line,
|
|
131
|
+
inner_match.groupdict()
|
|
132
|
+
)) from error
|
|
133
|
+
annotation_token, annotation_data = clean_annotation(annotation_token, annotation_data)
|
|
134
|
+
found_annotations.append({
|
|
135
|
+
'found_by': self.extension_name,
|
|
136
|
+
'filename': fname,
|
|
137
|
+
'line_number': line,
|
|
138
|
+
'annotation_token': annotation_token,
|
|
139
|
+
'annotation_data': annotation_data,
|
|
140
|
+
})
|
|
141
|
+
|
|
142
|
+
return found_annotations
|
|
143
|
+
|
|
144
|
+
def _find_comment_content(self, match):
|
|
145
|
+
"""
|
|
146
|
+
Return the comment content as text.
|
|
147
|
+
|
|
148
|
+
Args:
|
|
149
|
+
match (sre.SRE_MATCH): one of the matches of the self.comment_regex regular expression.
|
|
150
|
+
"""
|
|
151
|
+
comment_content = match.groupdict()["comment"]
|
|
152
|
+
if comment_content:
|
|
153
|
+
return comment_content
|
|
154
|
+
|
|
155
|
+
# Find single-line comments and strip comment tokens
|
|
156
|
+
comment_content = match.groupdict()["prefixed_comment"]
|
|
157
|
+
return self._strip_single_line_comment_tokens(comment_content)
|
|
158
|
+
|
|
159
|
+
def _strip_single_line_comment_tokens(self, content):
|
|
160
|
+
"""
|
|
161
|
+
Strip the leading single-line comment tokens from a comment text.
|
|
162
|
+
|
|
163
|
+
Args:
|
|
164
|
+
content (str): token-prefixed multi-line comment string.
|
|
165
|
+
"""
|
|
166
|
+
return self.prefixed_comment_regex.sub("", content)
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Stevedore extension for static annotation searching in Javascript files.
|
|
3
|
+
"""
|
|
4
|
+
import re
|
|
5
|
+
|
|
6
|
+
from code_annotations.extensions.base import SimpleRegexAnnotationExtension
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
class JavascriptAnnotationExtension(SimpleRegexAnnotationExtension):
|
|
10
|
+
"""
|
|
11
|
+
Annotation extension for Javascript source files.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
extension_name = 'javascript'
|
|
15
|
+
|
|
16
|
+
lang_comment_definition = {
|
|
17
|
+
'multi_start': re.escape('/*'),
|
|
18
|
+
'multi_end': re.escape('*/'),
|
|
19
|
+
'single': re.escape('//')
|
|
20
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Stevedore extension for static annotation searching in Python files.
|
|
3
|
+
"""
|
|
4
|
+
import re
|
|
5
|
+
|
|
6
|
+
from code_annotations.extensions.base import SimpleRegexAnnotationExtension
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
class PythonAnnotationExtension(SimpleRegexAnnotationExtension):
|
|
10
|
+
"""
|
|
11
|
+
Annotation extension for Python source files.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
extension_name = 'python'
|
|
15
|
+
|
|
16
|
+
lang_comment_definition = {
|
|
17
|
+
'multi_start': re.escape('"""'),
|
|
18
|
+
'multi_end': re.escape('"""'),
|
|
19
|
+
'single': re.escape('#')
|
|
20
|
+
}
|