bpo-41192: Clarify the sys module's description of the auditing feature #22768
Conversation
akuchling
added
needs backport to 3.8
needs backport to 3.9
Doc/library/sys.rst
Outdated
| In general, any exceptions raised by this function should not be | ||
| handled and should terminate the process as quickly as | ||
| possible. This allows hook implementations to decide how to respond | ||
| to any particular event. The typical responses will be to log the |
There was a problem hiding this comment.
This sort of duplicates what is said earlier, but probably OK.
There was a problem hiding this comment.
There's no other section or module to link to, so the body of these two functions is basically going to be it for documentation of this auditing feature, so I'm trying to cover everything, but your point about duplication is good!
I've reduced the discussion of sys.audit() a bit, leaving the hook order unspecified and taking out the PEP link. The bulk of the documentation is now on sys.addaudithook(), which seems like the more complicated function and embodies more of the feature's API.
Doc/library/sys.rst
Outdated
| these errors should not be handled and should terminate the process as | ||
| quickly as possible. | ||
| Raise an auditing event and trigger any active auditing hooks. | ||
| `event` is a string identifying the event, and `args` may contain |
There was a problem hiding this comment.
Travis does not like the backticks here and on 97. "default role"
Co-authored-by: Éric Araujo <[email protected]>
|
Thanks @akuchling for the PR 🌮🎉.. I'm working now to backport this PR to: 3.8, 3.9. |
|
Sorry @akuchling, I had trouble checking out the |
|
GH-22820 is a backport of this pull request to the 3.8 branch. |
…re (pythonGH-22768) Co-authored-by: Éric Araujo <[email protected]> (cherry picked from commit 0c37269) Co-authored-by: Andrew Kuchling <[email protected]>
… feature (pythonGH-22768) Co-authored-by: Éric Araujo <[email protected]> (cherry picked from commit 0c37269) Co-authored-by: Andrew Kuchling <[email protected]>
|
GH-22821 is a backport of this pull request to the 3.9 branch. |
…re (pythonGH-22768) Co-authored-by: Éric Araujo <[email protected]>
While looking at another PR for this ticket, I learned about 3.8's new auditing feature but found the sys module docs to be rather cryptic. This PR adds some text from the original PEP, adds a link to the PEP, and does some rewriting for clarity. I think the two functions now sufficiently explain what the auditing feature is for & how to use it.
https://bugs.python.org/issue41192