GeezerVison is showing github.com — `Audit events table` doc section is generated with broken links · Issue #93857 · python/cpython
Audit events table doc section is generated with broken links #93857
Activityerlend-aasland commented on Jun 15, 2022
https://docs.python.org/3/library/audit_events.html has two links to non-existent sections of sqlite3.html:
sqlite3.enable_load_extension | connection, enabled | [1]sqlite3.load_extension | connection, path | [1]
They are not non-existent, they just live under the sqlite3.Connection namespace. The audit names, however, are sqlite3.enable_load_extension and sqlite3.load_extension.
I couldn't find where these lines come from. A source file https://github.com/python/cpython/blob/ff095e13dfdea64de5c1ad21021ae9b5ca2631f8/Doc/library/audit_events.rst is much shorter, and I don't know what to grep.
That file is partly autogenerated, as noted on line 17.
This table is generated from the CPython documentation [...]
I suspect we need to alter the audit-event Sphinx extension to fix these things:
|
class AuditEvent(Directive): |
|
|
|
has_content = True |
|
required_arguments = 1 |
|
optional_arguments = 2 |
|
final_argument_whitespace = True |
|
|
|
_label = [ |
|
"Raises an :ref:`auditing event <auditing>` {name} with no arguments.", |
|
"Raises an :ref:`auditing event <auditing>` {name} with argument {args}.", |
|
"Raises an :ref:`auditing event <auditing>` {name} with arguments {args}.", |
|
] |
|
|
|
@property |
|
def logger(self): |
|
cls = type(self) |
|
return logging.getLogger(cls.__module__ + "." + cls.__name__) |
|
|
|
def run(self): |
|
name = self.arguments[0] |
|
if len(self.arguments) >= 2 and self.arguments[1]: |
|
args = (a.strip() for a in self.arguments[1].strip("'\"").split(",")) |
|
args = [a for a in args if a] |
|
else: |
|
args = [] |
|
|
|
label = translators['sphinx'].gettext(self._label[min(2, len(args))]) |
|
text = label.format(name="``{}``".format(name), |
|
args=", ".join("``{}``".format(a) for a in args if a)) |
|
|
|
env = self.state.document.settings.env |
|
if not hasattr(env, 'all_audit_events'): |
|
env.all_audit_events = {} |
|
|
|
new_info = { |
|
'source': [], |
|
'args': args |
|
} |
|
info = env.all_audit_events.setdefault(name, new_info) |
|
if info is not new_info: |
|
if not self._do_args_match(info['args'], new_info['args']): |
|
self.logger.warn( |
|
"Mismatched arguments for audit-event {}: {!r} != {!r}" |
|
.format(name, info['args'], new_info['args']) |
|
) |
|
|
|
ids = [] |
|
try: |
|
target = self.arguments[2].strip("\"'") |
|
except (IndexError, TypeError): |
|
target = None |
|
if not target: |
|
target = "audit_event_{}_{}".format( |
|
re.sub(r'\W', '_', name), |
|
len(info['source']), |
|
) |
|
ids.append(target) |
|
|
|
info['source'].append((env.docname, target)) |
|
|
|
pnode = nodes.paragraph(text, classes=["audit-hook"], ids=ids) |
|
pnode.line = self.lineno |
|
if self.content: |
|
self.state.nested_parse(self.content, self.content_offset, pnode) |
|
else: |
|
n, m = self.state.inline_text(text, self.lineno) |
|
pnode.extend(n + m) |
|
|
|
return [pnode] |
|
|
|
# This list of sets are allowable synonyms for event argument names. |
|
# If two names are in the same set, they are treated as equal for the |
|
# purposes of warning. This won't help if number of arguments is |
|
# different! |
|
_SYNONYMS = [ |
|
{"file", "path", "fd"}, |
|
] |
|
|
|
def _do_args_match(self, args1, args2): |
|
if args1 == args2: |
|
return True |
|
if len(args1) != len(args2): |
|
return False |
|
for a1, a2 in zip(args1, args2): |
|
if a1 == a2: |
|
continue |
|
if any(a1 in s and a2 in s for s in self._SYNONYMS): |
|
continue |
|
return False |
|
return True |
erlend-aasland commented on Jun 15, 2022
[...] I don't know what to grep.
$ grep -r "audit-event::" Doc/
$ grep -r "audit-event::.*sqlite" Doc/ erlend-aasland commented on Jun 15, 2022
I suspect we need to alter the audit-event Sphinx extension to fix these things [...]
Or maybe we're using the audit-event directive wrongly in Doc/library/sqlite3.rst. erlend-aasland commented on Jun 15, 2022 Yay, it was the latter. So we don't need to dig around in the Python Sphinx extensions (phew!) :) erlend-aasland commented on Jun 15, 2022 FTR, the third argument to the audit-event directive is the target:
|
try: |
|
target = self.arguments[2].strip("\"'") |
|
except (IndexError, TypeError): |
|
target = None |
|
if not target: |
|
target = "audit_event_{}_{}".format( |
|
re.sub(r'\W', '_', name), |
|
len(info['source']), |
erlend-aasland commented on Jun 15, 2022
MetadataMetadataStatusShow more project fields
DevelopmentNo branches or pull requestsIssue actions
|