-
-
Notifications
You must be signed in to change notification settings - Fork 116
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Issue all messages using the logging library #250
Conversation
This commit modifies the _convert_input function to print messages issued by pandoc on stderr that have not triggered a RuntimeError. These messages may be warnings, for instance or verbose output (see jgm/pandoc#6628). This behaviour can be suppressed by passing True to the quite argument of _convert_input. As passthrough argument has also been added to convert, convert_text and convert_file.
At some point the warning issued by the pandoc docx writer for a missing image changes from: [WARNING] Could not fetch resource 'missing.png': PandocResourceNotFound "missing.png" to: [WARNING] Could not fetch resource missing.png: PandocResourceNotFound "missing.png"
amazing work @H0R5E I was wondering, if it would be best behavior to initialize a logger instead of just using print. Or would that be overkill. What do you think? |
Thanks @NicklasTegner! I've been thinking about this PR and your suggestions. Firstly, it struck me that the Also, I don't think using the warnings module is the right approach because pandoc will put log messages with both INFO and WARNING level onto Probably using the Python logging module is the most robust way to handle the
The questions I have with this approach are "should the other functions that print (namely So, in conclusion, I think the Cheers, Mat |
@H0R5E For logging, I would say that your list is a good solution, I would however put all printing (including from _ensure_pandoc_path and others) into the logging as well, at the appropriate levels. |
OK @NicklasTegner, I'll give it a try. |
This commit changes the issuing of messages to use the Python logging library. Logging in the module now follows this process: 1. The module logger is initiated on import (without a handler) 2. The user then has the opportunity to attach a handler to the logger before the pypandoc functions are called. 3. When a function that issues messages is called, check if the logger has a handler and if not add a console handler, formatted in the same manner as pandoc's. 4. When log messages are detected on Pandoc's stderr stream, parse them to determine the level and then reissue the log messages at the appropriate level. Checking and setting up the logging handler is done by the `_check_log_handler` function, while determining the level of the messages issued by Pandoc on stderr is done by the `_classify_pandoc_logging` function.
This commit moves the remaining print statements, associated to the `download_pandoc` function to log messages instead. This change required moving the `_check_log_handler` function to its own submodule, `handler`, to avoid circular import. Also removed all "quiet" flags, as this can now be handled by configuring the logger.
@NicklasTegner, I've made the changes. Everything that printed or wrote to |
@H0R5E can you explain what exactly is a "breaking change" in this? |
Usually any change in the public command line interface (removing a flag that users may have used and now they have to adapt) is a breaking change. But then, people usually embrace change because they want the beneficial parts that should come along with it - maybe just consider when bumping the semantic version. |
mmhmm. What do you guys think. Either just remove the flags outright in this pr, bumping the version to 1.8 when relizing. |
So, to be precise, the breaking change is an API change to the -def ensure_pandoc_installed(url=None, targetfolder=None, version="latest", quiet=False, delete_installer=False):
+def ensure_pandoc_installed(url=None,
+ targetfolder=None,
+ version="latest",
+ delete_installer=False): And an API change to the -def download_pandoc(url=None, targetfolder=None, version="latest", quiet=False, delete_installer=False, download_folder=None):
+def download_pandoc(url=None,
+ targetfolder=None,
+ version="latest",
+ delete_installer=False,
+ download_folder=None): My understanding is that semantic versioning would require that this then be a major version change (i.e. to version 2). Here are the options I see for finishing this:
Happy to finish this off whichever way you want. |
I think option 2 in my list is my preference, BTW. |
I would say go ahead with option 2. Adding a message like:
Just essentially a message, stating that we have removed the functionality in favor of logging with the logging module, and where to find more information e.g the readme. |
@NicklasTegner, I think this is ready now. |
fantastic work. Good job :) @H0R5E |
This commit changes the issuing of messages to use the Python logging library. Logging in the module now follows this process:
Checking and setting up the logging handler is done by the
_check_log_handler
function (in thehandler
submodule), while determining the level of the messages issued by Pandoc on stderr is done by the_classify_pandoc_logging
function.Note, all public "quiet" flags are now deprecated, as this can now be handled by configuring the logger.
Closes #249