Skip to content

bpo-38892: Improve docs for audit event #17361

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zooba merged 3 commits into from
Nov 26, 2019
Merged

bpo-38892: Improve docs for audit event #17361

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
83dfb6a
bpo-38892: Improve docs for audit events.
terryjreedy Nov 23, 2019
cbc3e2f
blurb
terryjreedy Nov 23, 2019
afc721a
'Raise'.
terryjreedy Nov 23, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 12 additions & 11 deletions Doc/c-api/sys.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -309,7 +309,7 @@ accessible to C code. They all work with the current interpreter thread's

.. c:function:: int PySys_Audit(const char *event, const char *format, ...)

Raises an auditing event with any active hooks. Returns zero for success
Raise an auditing event with any active hooks. Return zero for success
and non-zero with an exception set on failure.

If any hooks have been added, *format* and other arguments will be used
Expand All @@ -327,11 +327,16 @@ accessible to C code. They all work with the current interpreter thread's

.. c:function:: int PySys_AddAuditHook(Py_AuditHookFunction hook, void *userData)

Adds to the collection of active auditing hooks. Returns zero for success
and non-zero on failure. If the runtime has been initialized, also sets an
Append the callable *hook* to the list of active auditing hooks.
Return zero for success
and non-zero on failure. If the runtime has been initialized, also set an
error on failure. Hooks added through this API are called for all
interpreters created by the runtime.

The *userData* pointer is passed into the hook function. Since hook
functions may be called from different runtimes, this pointer should not
refer directly to Python state.

This function is safe to call before :c:func:`Py_Initialize`. When called
after runtime initialization, existing audit hooks are notified and may
silently abort the operation by raising an error subclassed from
Expand All @@ -342,14 +347,10 @@ accessible to C code. They all work with the current interpreter thread's
:c:type:`PyTupleObject`. The hook function is always called with the GIL
held by the Python interpreter that raised the event.

The *userData* pointer is passed into the hook function. Since hook
functions may be called from different runtimes, this pointer should not
refer directly to Python state.

See :pep:`578` for a detailed description of auditing. Functions in the
runtime and standard library that raise events include the details in each
function's documentation and listed in the :ref:`audit events table
<audit-events>`.
See :pep:`578` for a detailed description of auditing. Functions in the
runtime and standard library that raise events are listed in the
:ref:`audit events table <audit-events>`.
Details are in each function's documentation.

.. audit-event:: sys.addaudithook "" c.PySys_AddAuditHook

Expand Down
2 changes: 1 addition & 1 deletion Doc/library/audit_events.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Audit events table

This table contains all events raised by :func:`sys.audit` or
:c:func:`PySys_Audit` calls throughout the CPython runtime and the
standard library.
standard library. These calls were added in 3.8.0 or later.
Copy link
Copy Markdown
Member Author

@terryjreedy terryjreedy Nov 23, 2019

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A minimal addition.


See :func:`sys.addaudithook` and :c:func:`PySys_AddAuditHook` for
information on handling these events.
Expand Down
6 changes: 3 additions & 3 deletions Doc/library/sys.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ always available.

.. function:: addaudithook(hook)

Adds the callable *hook* to the collection of active auditing hooks for the
Append the callable *hook* to the list of active auditing hooks for the
current interpreter.

When an auditing event is raised through the :func:`sys.audit` function, each
Expand All @@ -35,7 +35,7 @@ always available.

.. audit-event:: sys.addaudithook "" sys.addaudithook

Raises a auditing event ``sys.addaudithook`` with no arguments. If any
Raise an auditing event ``sys.addaudithook`` with no arguments. If any
existing hooks raise an exception derived from :class:`Exception`, the
new hook will not be added and the exception suppressed. As a result,
callers cannot assume that their hook has been added unless they control
Expand Down Expand Up @@ -74,7 +74,7 @@ always available.

.. index:: single: auditing

Raises an auditing event with any active hooks. The event name is a string
Raise an auditing event with any active hooks. The event name is a string
identifying the event and its associated schema, which is the number and
types of arguments. The schema for a given event is considered public and
stable API and should not be modified between releases.
Expand Down
1 change: 1 addition & 0 deletions Misc/NEWS.d/next/Core and Builtins/2019-11-22-22-18-50.bpo-38892.LS586s.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Improve documentation for audit events table and functions.