classification
Title: Don't use _ as a function name in logging documentation cookbook
Type: Stage: resolved
Components: Documentation Versions: Python 3.9
process
Status: closed Resolution: not a bug
Dependencies: Superseder:
Assigned To: docs@python Nosy List: AndrewCarterUK, docs@python, vinay.sajip, xtreak
Priority: normal Keywords:

Created on 2019-07-15 17:11 by AndrewCarterUK, last changed 2019-07-16 09:54 by vinay.sajip. This issue is now closed.

Messages (4)
msg347984 - (view) Author: Andrew Carter (AndrewCarterUK) Date: 2019-07-15 17:11
Current docs link: https://docs.python.org/3/howto/logging-cookbook.html#implementing-structured-logging

GitHub commit link: https://github.com/python/cpython/commit/4b88d6c6642450240a9dc22e6efbdc69baf890dd

The suggestion is that for structured logging, a StructuredMessage class should be created with a __str__ method defined and then assigned to an _ variable and used as a logging formatter.

As the _ variable is commonly used as a "skip variable" and it has other meanings inside the Python interactive shell - I recommend that this example is changed to one that maybe just defines a simple wrapper function.

I'm happy to create a PR for this - but only if there's agreement that it's worthwhile and will get merged if suitable.

Thanks,

Andrew
msg347992 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2019-07-15 21:09
The comment at the end of the "_ = ..." line indicates clearly that it's optional to do that, and I assume that any reader will realise that they can use any suitable variable name rather than "_". There's no particular "recommendation" to use "_" and cookbook recipes are generally regarded as starting points for one's own code, rather than being copied verbatim into production scenarios.

I specifically picked "_", despite knowing its other uses, because:

 * One use of "_" is as a function that does some form of translation on a passed string argument - language translation being the most common example - and this recipe is a very loose analogue of that type of usage
* A very brief notation assists readability because once you've looked at the "_" definition, you can use constructions like the one further down in the recipe.

Since "_" wasn't picked at random, I'd rather not change it - if people decide to use this recipe, it would be better for brevity and standardisation if "_" were to be used, IMO.

I don't believe the usage of "_" in interactive interpreter sessions is relevant to this cookbook recipe and shouldn't, in my opinion, cause confusion, any more than where the use of "_" for language translations is being explored in an interactive session.

In summary - please don't waste your time on this, though I appreciate the intent behind your suggestion - thanks.
msg348005 - (view) Author: Karthikeyan Singaravelan (xtreak) * (Python triager) Date: 2019-07-16 07:51
Slightly unrelated to the issue but I noticed the below statement in the docs page couple of times. I think it's related to the order of kwargs when the statement was added in 3d9e972270270e1498712065a17ec3a589ae8986. Since order of kwargs is guaranteed from Python 3.6 can this be removed?

> Note that the order of items might be different according to the version of Python used.
msg348009 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2019-07-16 09:53
> Since order of kwargs is guaranteed from Python 3.6 can this be removed?

Well, the statement about order isn't inaccurate when talking about Python in general and the cookbook is a resource meant to be useful across multiple Python implementations and versions, so I'd be inclined to leave it as is.
History
Date User Action Args
2019-07-16 09:54:22vinay.sajipsetstatus: open -> closed
resolution: not a bug
stage: resolved
2019-07-16 09:53:44vinay.sajipsetmessages: + msg348009
2019-07-16 07:51:35xtreaksetnosy: + xtreak
messages: + msg348005
2019-07-15 21:09:59vinay.sajipsetmessages: + msg347992
2019-07-15 19:22:50xtreaksetnosy: + vinay.sajip
2019-07-15 17:11:21AndrewCarterUKcreate