8000 bpo-37390: Add audit event table to documentations (GH-14406) · lisroach/cpython@e8fed1c · GitHub
[go: up one dir, main page]
Skip to content

Commit e8fed1c

Browse files
zoobalisroach
zooba
authored and
lisroach
committed
bpo-37390: Add audit event table to documentations (pythonGH-14406)
Also updates some (unreleased) event names to be consistent with the others.
1 parent 81a2984 commit e8fed1c

34 files changed

+266
-113
lines changed

‎Doc/c-api/code.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ bound into a function.
4545
The first parameter (*argcount*) now represents the total number of positional arguments,
4646
including positional-only.
4747
48-
.. audit-event:: code.__new__ "code filename name argcount posonlyargcount kwonlyargcount nlocals stacksize flags"
48+
.. audit-event:: code.__new__ code,filename,name,argcount,posonlyargcount,kwonlyargcount,nlocals,stacksize,flags c.PyCode_New
4949
5050
.. c:function:: PyCodeObject* PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)
5151

‎Doc/c-api/sys.rst

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -291,8 +291,6 @@ accessible to C code. They all work with the current interpreter thread's
291291
292292
.. c:function:: int PySys_Audit(const char *event, const char *format, ...)
293293
294-
.. index:: single: audit events
295-
296294
Raises an auditing event with any active hooks. Returns zero for success
297295
and non-zero with an exception set on failure.
298296
@@ -311,8 +309,6 @@ accessible to C code. They all work with the current interpreter thread's
311309
312310
.. c:function:: int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)
313311
314-
.. index:: single: audit events
315-
316312
Adds to the collection of active auditing hooks. Returns zero for success
317313
and non-zero on failure. If the runtime has been initialized, also sets an
318314
error on failure. Hooks added through this API are called for all

‎Doc/library/array.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,7 @@ The module defines the following type:
8383
to add initial items to the array. Otherwise, the iterable initializer is
8484
passed to the :meth:`extend` method.
8585

86-
.. audit-event:: array.__new__ "typecode initializer"
86+
.. audit-event:: array.__new__ typecode,initializer array.array
8787

8888
.. data:: typecodes
8989

‎Doc/library/audit_events.rst

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
.. _audit-events:
2+
3+
.. index:: single: audit events
4+
5+
Audit events table
6+
==================
7+
8+
This table contains all events raised by :func:`sys.audit` or
9+
:c:func:`PySys_Audit` calls throughout the CPython runtime and the
10+
standard library.
11+
12+
See :func:`sys.addaudithook` and :c:func:`PySys_AddAuditHook` for
13+
information on handling these events.
14+
15+
.. impl-detail::
16+
17+
This table is generated from the CPython documentation, and may not
18+
represent events raised by other implementations. See your runtime
19+
specific documentation for actual events raised.
20+
21+
.. audit-event-table::

‎Doc/library/ctypes.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1509,13 +1509,13 @@ object is available:
15091509
:c:type:`int`, which is of course not always the truth, so you have to assign
15101510
the correct :attr:`restype` attribute to use these functions.
15111511

1512-
.. audit-event:: ctypes.dlopen name
1512+
.. audit-event:: ctypes.dlopen name ctypes.LibraryLoader
15131513

15141514
Loading a library through any of these objects raises an
15151515
:ref:`auditing event <auditing>` ``ctypes.dlopen`` with string argument
15161516
``name``, the name used to load the library.
15171517

1518-
.. audit-event:: ctypes.dlsym "library name"
1518+
.. audit-event:: ctypes.dlsym library,name ctypes.LibraryLoader
15191519

15201520
Accessing a function on a loaded library raises an auditing event
15211521
``ctypes.dlsym`` with arguments ``library`` (the library object) and ``name``
@@ -2043,7 +2043,7 @@ Data types
20432043
This method returns a ctypes type instance using the memory specified by
20442044
*address* which must be an integer.
20452045

2046-
.. audit-event:: ctypes.cdata address
2046+
.. audit-event:: ctypes.cdata address ctypes._CData.from_address
20472047

20482048
This method, and others that indirectly call this method, raises an
20492049
:ref:`auditing event <auditing>` ``ctypes.cdata`` with argument

‎Doc/library/debug.rst

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,13 @@ Debugging and Profiling
55
These libraries help you with Python development: the debugger enables you to
66
step through code, analyze stack frames and set breakpoints etc., and the
77
profilers run code and give you a detailed breakdown of execution times,
8-
allowing you to identify bottlenecks in your programs.
8+
allowing you to identify bottlenecks in your programs. Auditing events
9+
provide visibility into runtime behaviors that would otherwise require
10+
intrusive debugging or patching.
911

1012
.. toctree::
1113

14+
audit_events.rst
1215
bdb.rst
1316
faulthandler.rst
1417
pdb.rst

‎Doc/library/ensurepip.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -119,7 +119,7 @@ Module API
119119
*verbosity* controls the level of output to :data:`sys.stdout` from the
120120
bootstrapping operation.
121121

122-
.. audit-event:: ensurepip.bootstrap root
122+
.. audit-event:: ensurepip.bootstrap root ensurepip.bootstrap
123123

124124
.. note::
125125

‎Doc/library/ftplib.rst

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,7 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
190190
*source_address* is a 2-tuple ``(host, port)`` for the socket to bind to as
191191
its source address before connecting.
192192

193-
.. audit-event:: ftplib.FTP.connect "self host port"
193+
.. audit-event:: ftplib.connect self,host,port ftplib.FTP.connect
194194

195195
.. versionchanged:: 3.3
196196
*source_address* parameter was added.
@@ -225,7 +225,7 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
225225

226226
Send a simple command string to the server and return the response string.
227227

228-
.. audit-event:: ftplib.FTP.sendcmd "self cmd"
228+
.. audit-event:: ftplib.sendcmd self,cmd ftplib.FTP.sendcmd
229229

230230

231231
.. method:: FTP.voidcmd(cmd)
@@ -234,7 +234,7 @@ followed by ``lines`` for the text version or ``binary`` for the binary version.
234234
nothing if a response code corresponding to success (codes in the range
235235
200--299) is received. Raise :exc:`error_reply` otherwise.
236236

237-
.. audit-event:: ftplib.FTP.sendcmd "self cmd"
237+
.. audit-event:: ftplib.sendcmd self,cmd ftplib.FTP.voidcmd
238238

239239

240240
.. method:: FTP.retrbinary(cmd, callback, blocksize=8192, rest=None)

‎Doc/library/functions.rst

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -128,7 +128,7 @@ are always available. They are listed here in alphabetical order.
128128
:func:`breakpoint` will automatically call that, allowing you to drop into
129129
the debugger of choice.
130130

131-
.. audit-event:: builtins.breakpoint "sys.breakpointhook"
131+
.. audit-event:: builtins.breakpoint breakpointhook breakpoint
132132

133133
.. versionadded:: 3.7
134134

@@ -277,7 +277,7 @@ are always available. They are listed here in alphabetical order.
277277
If you want to parse Python code into its AST representation, see
278278
:func:`ast.parse`.
279279

280-
.. audit-event:: compile "source filename"
280+
.. audit-event:: compile source,filename compile
281281

282282
Raises an :ref:`auditing event <auditing>` ``compile`` with arguments
283283
``source`` and ``filename``. This event may also be raised by implicit
@@ -490,7 +490,7 @@ are always available. They are listed here in alphabetical order.
490490
See :func:`ast.literal_eval` for a function that can safely evaluate strings
491491
with expressions containing only literals.
492492

493-
.. audit-event:: exec code_object
493+
.. audit-event:: exec code_object eval
494494

495495
Raises an :ref:`auditing event <auditing>` ``exec`` with the code object
496496
as the argument. Code compilation events may also be raised.
@@ -525,7 +525,7 @@ are always available. They are listed here in alphabetical order.
525525
builtins are available to the executed code by inserting your own
526526
``__builtins__`` dictionary into *globals* before passing it to :func:`exec`.
527527

528-
.. audit-event:: exec code_object
528+
.. audit-event:: exec code_object exec
529529

530530
Raises an :ref:`auditing event <auditing>` ``exec`` with the code object
531531
as the argument. Code compilation events may also be raised.
@@ -779,12 +779,12 @@ are always available. They are listed here in alphabetical order.
779779
If the :mod:`readline` module was loaded, then :func:`input` will use it
780780
to provide elaborate line editing and history features.
781781

782-
.. audit-event:: builtins.input prompt
782+
.. audit-event:: builtins.input prompt input
783783

784784
Raises an :ref:`auditing event <auditing>` ``builtins.input`` with
785785
argument ``prompt`` before reading input
786786

787-
.. audit-event:: builtins.input/result result
787+
.. audit-event:: builtins.input/result result input
788788

789789
Raises an auditing event ``builtins.input/result`` with the result after
790790
successfully reading input.
@@ -1222,7 +1222,7 @@ are always available. They are listed here in alphabetical order.
12221222
(where :func:`open` is declared), :mod:`os`, :mod:`os.path`, :mod:`tempfile`,
12231223
and :mod:`shutil`.
12241224

1225-
.. audit-event:: open "file mode flags"
1225+
.. audit-event:: open file,mode,flags open
12261226

12271227
The ``mode`` and ``flags`` arguments may have been modified or inferred from
12281228
the original call.

‎Doc/library/glob.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ For example, ``'[?]'`` matches the character ``'?'``.
5252
more directories and subdirectories. If the pattern is followed by an
5353
``os.sep``, only directories and subdirectories match.
5454

55-
.. audit-event:: glob.glob "pathname recursive"
55+
.. audit-event:: glob.glob pathname,recursive glob.glob
5656

5757
.. note::
5858
Using the "``**``" pattern in large directory trees may consume
@@ -67,7 +67,7 @@ For example, ``'[?]'`` matches the character ``'?'``.
6767
Return an :term:`iterator` which yields the same values as :func:`glob`
6868
without actually storing them all simultaneously.
6969

70-
.. audit-event:: glob.glob "pathname recursive"
70+
.. audit-event:: glob.glob pathname,recursive glob.iglob
7171

7272

7373
.. function:: escape(pathname)

0 commit comments

Comments
 (0)
0