Audit events table doc section is generated with broken links

Parent issue: gh-93851

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]

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.

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:

cpython/Doc/tools/extensions/pyspecific.py

Lines 189 to 278 in ff095e1

    
           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

[...] I don't know what to grep.

$ grep -r "audit-event::" Doc/
$ grep -r "audit-event::.*sqlite" Doc/

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.

Yay, it was the latter. So we don't need to dig around in the Python Sphinx extensions (phew!) :)

pythongh-93857: Fix broken audit-event targets in sqlite3 docs

FTR, the third argument to the audit-event directive is the target:

cpython/Doc/tools/extensions/pyspecific.py

Lines 236 to 243 in ff095e1

    
           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']),

pythongh-93857: Fix broken audit-event targets in sqlite3 docs (pytho…

gh-93857: Fix broken audit-event targets in sqlite3 docs (#93859)

pythongh-93857: Fix broken audit-event targets in sqlite3 docs (pytho…

Fixed in:

main: gh-93857: Fix broken audit-event targets in sqlite3 docs #93859
3.11: [3.11] gh-93857: Fix broken audit-event targets in sqlite3 docs (GH-93859) #93861
3.10: [3.10] gh-93857: Fix broken audit-event targets in sqlite3 docs (GH-93859) #93862

gh-93857: Fix broken audit-event targets in sqlite3 docs (GH-93859)

Revert 30935 defer bpo45162 to 312 (#94285)

Navigation Menu

Repository navigation

`Audit events table` doc section is generated with broken links #93857

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

	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

Audit events table doc section is generated with broken links #93857

Description

Activity

erlend-aasland commented on Jun 15, 2022

erlend-aasland commented on Jun 15, 2022

erlend-aasland commented on Jun 15, 2022

erlend-aasland commented on Jun 15, 2022

erlend-aasland commented on Jun 15, 2022

erlend-aasland commented on Jun 15, 2022

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

`Audit events table` doc section is generated with broken links #93857