Loguru: Suggestion/request: Documentation/tutorial for beginners

[ManavalanG]

I came across loguru today, but even as a moderately experienced python developer, I find it hard to pick up loguru using the documentation. Current documentation appears to be targeted towards people with experience in logging module. It lists all features that are provided by loguru, but it doesn't show what is needed to get going for beginners. I looked up for tutorial, but haven't found one yet.

If there is a tutorial elsewhere, please let me know. With the assumption that not one is available yet, I would like to suggest following improvements in Readme:

• Example script showing minimal loguru setup and may be few more examples showcasing other basic but major features
• Levels available (info, warning, etc) and their uses. Unless one has experience with logging, it would be hard to know about their availability and understand their usage.
• Minimal python version needed

[Delgan]

Hello @ManavalanG, thanks for your interest on Loguru and your suggestions!

It is true that the documentation lacks explanations for beginners. I did not realize that. Now that I think about it, it would be good for sure to add a few words about the utility of logging, but I do not know if it is very relevant to dedicate a whole documentation page to this.
The thing is that there is already many ressources online explaining the basics of logging and its advantages. I don't think I can do much better by writing another guide. However, I can definitely add a reference linking to a good introduction to logging. For example, I could add somewhere a link to Python documentation: Logging HOWTO. Hopefully this should help beginners with standard logging practices.

Example script showing minimal loguru setup and may be few more examples showcasing other basic but major features

This is the whole point of the Take the tour section in the Readme! 😄
The minimal setup is from loguru import logger. All others features are listed below with a short description, a small example, and a link to the documentation for extended explanations.
This is intended to give a quick preview at first glance, keeping the Readme "short" but still exhaustive.

Levels available (info, warning, etc) and their uses. Unless one has experience with logging, it would be hard to know about their availability and understand their usage.

The "Logging HOWTO" page I previously linked would serves this usage quite well, I think. Also, available levels are listed in the documentation but the numerical severity values corresponding are actually missing, so I will add them shortly.

Minimal python version needed

The required Python version is referenced in the left bar on PyPI, at the "Meta" section. Actually, it is also displayed at the top of the Readme among the others Github badges. I will move the Python version badge to the left, so it will be harder to miss. 😉

[ManavalanG]

Thanks for responding to my suggestion. Let me try to clarify how I ended up making the suggestions, as it would better paint the picture. I came across loguru in reddit, where if I recall correctly, you (or OP) had commented that this library was written from scratch and not a wrapper to logging library. This comment led me to think that loguru is quite different from logging, and therefore despite both having similar functionalities, they could be potentially quite different in how to use them. I could not easily evaluate the latter statement after looking up Readme doc and searching for any other write-up elsewhere online.

I have used logging >3 years ago, and hence I remembered to look for availability of different levels, but as docstrings were missing for these functions, I couldn't figure if they were similar only in name or also in their functionalities to those in logging.

I guess, as you suggested, linking to logging documentation and perhaps drawing parallels between loguru and logging would help guide the users (not just the beginners, I would think). Obviously, the level/type of documentation needed depends on the type of users/developers you would like to attract, but I think those without logging library experience would struggle picking it up easily.

My bad, I missed the badge about python version requirement. I tend to forget use of the badges once in a while.

[Delgan]

Thanks for your elaborated feedback!

I don't know if you saw it (it's not yet on the stable branch), but there is also this page on the Loguru documentation: Switching from standard logging to loguru
I guess I could clarify what are the fundamental difference between standard logging and loguru, and how they relate to each other. Either by adding a new section or by extanding existing ones.
In addition to other explanations in the logger docstrings and a link to a logging guide, I hope this should ease first steps with Loguru.

[Delgan]

So, I tried to improve the documentation as you suggested:

• Add a link to the "Logging HOWTO" Python documentation in the resources page
• Add a section explaining difference between logging and loguru in the migration guide
• Add a new documentation page containing various code snippets (will be extended)
• Add a section about logging levels in the logger API documentation

Thanks for yours suggestions @ManavalanG! I hope this may answer some beginners questions about Loguru and logging in general.

[anentropic]

The part I am missing is:

I can install loguru in my project and it works for any logs I send via the loguru logger. Great!

But what about logging from 3rd party packages that I am using in my app - how do I make their logs go through the loguru logger too? At the moment they go nowhere.

The InterceptHandler example given in the docs doesn't seem to achieve this. Maybe I am missing something.

[Delgan]

Hi @anentropic.

I updated the InterceptHandler a few weeks ago. Can you please confirm me that the following code does not catch messages from third libraries?

class InterceptHandler(logging.Handler):
    def emit(self, record):
        logger_opt = logger.opt(depth=6, exception=record.exc_info)
        logger_opt.log(record.levelno, record.getMessage())

logging.basicConfig(handlers=[InterceptHandler()], level=0)
logger.add(sys.stderr, level="DEBUG")

# Use your 3rd library then
requests.get("http://www.google.com")

This snippet seems to work fine on my computer. Do you have some code sample not working as expected, so I can reproduce the error please?

[anentropic]

@Delgan that works perfect, thanks!

FYI the docs at https://loguru.readthedocs.io/en/stable/overview.html#entirely-compatible-with-standard-logging don't show the updated snippet yet

[anentropic]

the only problem is that the log level comes out as:

2019-04-19 10:21:41.385 | Level 20 | blah blah...

instead of the bold/colored INFO I get when I using the loguru logger directly

[anentropic]

how do I restrict the log level?

I changed this line to logger.add(sys.stderr, level="INFO") but I still see DEBUG level logs

also, all of the logging appears twice
eg

2019-04-19 10:21:41.385 | Level 20 | blah blah...
2019-04-19 10:21:41.385 | Level 20 | blah blah...

[Delgan]

FYI the docs at https://loguru.readthedocs.io/en/stable/overview.html#entirely-compatible-with-standard-logging don't show the updated snippet yet

@anentropic Yep, this is the stable version of the documentation which corresponds to the v0.2.5 release. Updated snippet is visible on the latest branch.

the only problem is that the log level comes out as:

2019-04-19 10:21:41.385 | Level 20 | blah blah...

instead of the bold/colored INFO I get when I using the loguru logger directly

As a workaround, you can use record.levelname instead of record.levelno, this should be ok for most common levels (debug, info, warning, etc.) but this would prevent logs relying on custom levels to work. Indeed, loguru is not aware of any custom level defined by libraries using custom logging levels. So, logging a message with levelname == "DEBUG" should work without much problem, but you gonna be in trouble as soon as someone use levelname == "MY_CUSTOM_LEVEL", because Loguru will be unable to match the custom level name to its numerical severity value. Hence the default to levelno which ensures that all logs are properly intercepted.

how do I restrict the log level?

I changed this line to logger.add(sys.stderr, level="INFO") but I still see DEBUG level logs

also, all of the logging appears twice

I guess this is because loguru comes with a pre-configured sink, which is automatically added to the logger with a "DEBUG" level. Call logger.remove() before adding the sys.stderr sink, this should remove the pre-configured sink and thus fix your issues.

[Delgan]

As 0.3.0 just has been released, the new improvements are now available in the stable branch of the documentation. :)

Thanks again for all the suggestions. :+1: