Closed mosbasik closed 5 months ago
Yes, you're right I tend to use logger
for global return values from get_logger()
(that are usually lazy proxies) and log
for local loggers that are usually created using bind()
.
Since structlog is original work, best practices like this only emerged over the years and the usage kinda dates the documentation (despite a huge recent rewrite).
Generally speaking, I think the docs should conform to it, it's just the getting started part that I'm not 100% sure about. On the one hand, example code should be exemplar… OTOH I feel like having two differently named loggers in the first contact with the user could be confusing. 🤔
Summary
Just changing the name of one variable in one docs example.
Motivation
While following along with the "Getting Started" guide for the first time, I got sidetracked for several minutes by this
logger
.None of the example snippets earlier in the file assigned to a variable named
logger
(but they frequently assigned the result ofstructlog.get_logger()
to a variable namedlog
).I spent a bit poking around in the API reference to try and figure out which types define a
.bind()
method and whether they completely overlap with the types returned bystructlog.get_logger()
.Eventually I decided the specific variable name probably wasn't a super considered choice and I was overthinking things.
Maybe this change could save someone time in the future.
Further Discussion
It'd be nice (maybe not super valuable, but nice) if a single naming convention were used throughout the docs. I was considering making this a "unify all the names" PR, but figured that might be a waste of time without getting style input from @hynek first.
I found ~71 uses of
log
and ~41 uses oflogger
in markdown files (approximately; used a rough regex to try and find relevant cases). Is there a considered reason to use one or the other, or has it been pretty arbitrary?Some theories I had, but found counterexamples for:
log
/logger
is for the result ofstructlog.get_logger()
and the other is for the result of a.bind()
Pull Request Check List
main
branch – use a separate branch!api.py
.docs/api.rst
by hand.versionadded
,versionchanged
, ordeprecated
directives..rst
and.md
files is written using semantic newlines.