hynek / structlog

Simple, powerful, and fast logging for Python.
https://www.structlog.org/
Other
3.48k stars 220 forks source link

Fix reference to undefined var `logger` in "Getting Started" example #614

Closed mosbasik closed 5 months ago

mosbasik commented 6 months ago

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 of structlog.get_logger() to a variable named log).

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 by structlog.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 of logger 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:

  1. maybe you're trying to avoid assigning to a variable the result of evaluating an expression containing that variable
  2. maybe one of log/logger is for the result of structlog.get_logger() and the other is for the result of a .bind()

Pull Request Check List

hynek commented 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. 🤔