classification
Title: Audit Hook doc typos and confusion
Type: behavior Stage: resolved
Components: Documentation, Interpreter Core Versions: Python 3.9, Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: christian.heimes, docs@python, miss-islington, steve.dower, terry.reedy
Priority: normal Keywords: patch

Created on 2019-11-22 02:32 by terry.reedy, last changed 2019-11-26 17:14 by miss-islington. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 17361 merged terry.reedy, 2019-11-23 03:35
PR 17391 merged miss-islington, 2019-11-26 17:08
Messages (6)
msg357240 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-11-22 02:32
Some suggestions for
https://docs.python.org/3.9/c-api/sys.html#c.PySys_AddAuditHook
https://docs.python.org/3.9/library/sys.html#sys.addaudithook

"Adds to the collection of active auditing hooks"
"Adds the callable hook to the collection of active auditing hooks"

Change 'Adds' to 'Add' or maybe 'Append' (see near below).
Insert 'the callable hook' in PySys version.
Change 'collection' to 'sequence' or 'list' (and change verb to 'append') since order is important.

PySys version:

I think the 'userData' explanation should be closer to the top.  

Grammar: "Functions in the runtime and standard library that raise events include the details in each function’s documentation and listed in the audit events table." is not a proper sentence.  Its 'skeleton' is "Functions ... include the details ... and listed ... .  

Either change 'include the details' to 'are detailed' and 'listed' to 'are listed' or split into two sentences:

"Functions in the runtime and standard library that raise events are  listed in the audit events table.  Details are in each function’s documentation.

Both, again:

"raises a auditing event".  'a' should be  'an'.  To me, this is slightly confusing because Python raises exceptions, but auditing events are not exceptions and do not normally abort execution.  Perhaps "This call is a 'sys.addaudithook' event with no arguments that triggers an audit call."


https://docs.python.org/3.9/c-api/sys.html#c.PySys_Audit
https://docs.python.org/3.9/library/sys.html#sys.audit

Change 'Raises' to 'Raise'.


https://docs.python.org/3.8/library/audit_events.html

On pydev, Steve said "(though some won't be raised until 3.8.1... we should probably mark those, or at least update that page to warn that events may have been added over time)."
msg357341 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2019-11-22 23:37
Thanks Terry, this is great!

Agree with everything apart from not liking "raise" - I think "raise an event" is totally fine usage, and certainly better than "triggers an audit call" (since it may not, if nobody's listening). Plus PEP 578 is full of "raise", and we're not going to go edit all of that :)
msg357357 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-11-23 02:44
I agree on consistency.  I will make a PR for you to review.

Do you think a minimal code example might help?  Running ...

import sys

def hook(name, args):
    if name.startswith('compile'):
        print(name, args)

sys.addaudithook(hook)
compile('a = 1', '<dummy>', 'exec')

# prints

compile (b'a = 1', '<dummy>')

My own interest is learning about the socket connecting an IDLE GUI process and the user code run process.  The following in the two startup files:

def hook(name, args):
    if name.startswith('socket'):
        print('I', name, args)  # I/R in the IDLE/run processes.
sys.addaudithook(hook)

results in:

I socket.gethostname ()
R socket.gethostname ()
I socket.bind (<socket.socket fd=796, family=AddressFamily.AF_INET, type=SocketKind.SOCK_STREAM, proto=0>, ('127.0.0.1', 0))
R socket.bind (<socket.socket fd=796, family=AddressFamily.AF_INET, type=SocketKind.SOCK_STREAM, proto=0>, ('127.0.0.1', 0))
R socket.connect (<socket.socket fd=816, family=AddressFamily.AF_INET, type=SocketKind.SOCK_STREAM, proto=0>, ('127.0.0.1', 62119))
I socket.__new__ (<socket.socket fd=-1, family=AddressFamily.AF_UNSPEC, type=0, proto=0>, 2, 1, 0)
R socket.__new__ (<socket.socket fd=-1, family=AddressFamily.AF_UNSPEC, type=0, proto=0>, 2, 1, 0)

To go further, I might wrap socket.socket.send/recv with functions that call sys.audit.
msg357513 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2019-11-26 17:07
New changeset e563a155be60fc0757914f87c8138f10de00bb16 by Steve Dower (Terry Jan Reedy) in branch 'master':
bpo-38892: Improve docs for audit event (GH-17361)
https://github.com/python/cpython/commit/e563a155be60fc0757914f87c8138f10de00bb16
msg357515 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2019-11-26 17:12
Thanks Terry!
msg357516 - (view) Author: miss-islington (miss-islington) Date: 2019-11-26 17:14
New changeset 86d9933cc627c4232f9702ca0766713714ebbc53 by Miss Islington (bot) in branch '3.8':
bpo-38892: Improve docs for audit event (GH-17361)
https://github.com/python/cpython/commit/86d9933cc627c4232f9702ca0766713714ebbc53
History
Date User Action Args
2019-11-26 17:14:54miss-islingtonsetnosy: + miss-islington
messages: + msg357516
2019-11-26 17:12:35steve.dowersetstatus: open -> closed
resolution: fixed
messages: + msg357515

stage: patch review -> resolved
2019-11-26 17:08:12miss-islingtonsetpull_requests: + pull_request16873
2019-11-26 17:07:59steve.dowersetmessages: + msg357513
2019-11-23 03:35:57terry.reedysetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request16846
2019-11-23 02:44:25terry.reedysetmessages: + msg357357
2019-11-22 23:37:41steve.dowersetmessages: + msg357341
2019-11-22 02:32:59terry.reedycreate