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.
Files changed (39) hide show
  1. code_annotations/__init__.py +6 -0
  2. code_annotations/annotation_errors.py +64 -0
  3. code_annotations/base.py +647 -0
  4. code_annotations/cli.py +271 -0
  5. code_annotations/contrib/README.rst +8 -0
  6. code_annotations/contrib/config/__init__.py +14 -0
  7. code_annotations/contrib/config/feature_toggle_annotations.yaml +29 -0
  8. code_annotations/contrib/config/openedx_events_annotations.yaml +20 -0
  9. code_annotations/contrib/config/setting_annotations.yaml +13 -0
  10. code_annotations/contrib/sphinx/extensions/__init__.py +3 -0
  11. code_annotations/contrib/sphinx/extensions/base.py +53 -0
  12. code_annotations/contrib/sphinx/extensions/featuretoggles.py +137 -0
  13. code_annotations/contrib/sphinx/extensions/openedx_events.py +182 -0
  14. code_annotations/contrib/sphinx/extensions/settings.py +139 -0
  15. code_annotations/exceptions.py +9 -0
  16. code_annotations/extensions/__init__.py +3 -0
  17. code_annotations/extensions/base.py +166 -0
  18. code_annotations/extensions/javascript.py +20 -0
  19. code_annotations/extensions/python.py +20 -0
  20. code_annotations/find_django.py +460 -0
  21. code_annotations/find_static.py +96 -0
  22. code_annotations/generate_docs.py +165 -0
  23. code_annotations/helpers.py +182 -0
  24. code_annotations/report_templates/html/annotation.tpl +14 -0
  25. code_annotations/report_templates/html/annotation_data.tpl +8 -0
  26. code_annotations/report_templates/html/annotation_list.tpl +27 -0
  27. code_annotations/report_templates/html/base.tpl +92 -0
  28. code_annotations/report_templates/rst/annotation.tpl +13 -0
  29. code_annotations/report_templates/rst/annotation_data.tpl +8 -0
  30. code_annotations/report_templates/rst/annotation_group.tpl +2 -0
  31. code_annotations/report_templates/rst/annotation_list.tpl +34 -0
  32. code_annotations/report_templates/rst/base.tpl +41 -0
  33. code_annotations-3.1.0.dist-info/METADATA +82 -0
  34. code_annotations-3.1.0.dist-info/RECORD +39 -0
  35. code_annotations-3.1.0.dist-info/WHEEL +5 -0
  36. code_annotations-3.1.0.dist-info/entry_points.txt +6 -0
  37. code_annotations-3.1.0.dist-info/licenses/LICENSE.txt +202 -0
  38. code_annotations-3.1.0.dist-info/licenses/NOTICE.txt +13 -0
  39. 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,9 @@
1
+ """
2
+ Custom exceptions for code_annotations.
3
+ """
4
+
5
+
6
+ class ConfigurationException(Exception):
7
+ """
8
+ Exception specific to code annotation configuration problems.
9
+ """
@@ -0,0 +1,3 @@
1
+ """
2
+ Extensions used in static annotation functionality.
3
+ """
@@ -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
+ }