Replace warnings.warn with cbook._warn_external or logging.warning #12006
Conversation
|
Wow, looks great! You are going to have to rebase However, is there no way for us to automate this? Does it have to be set manually for every warnings call? I admit that a quick google search didn't turn up anything hopeful, but thought I'd ask... |
|
We also don't allow lines >79 characters, so you'll have to sort out all the overspilling lines (see the flake8 errors in travis-ci/py3.6 build) |
217e695 to
3c71722
Compare
|
In general, this is an improvement. But an even better improvement would be to just use _warn_external everywhere -- see #11298 (and adapt the (nice) explanation for it). (See for example (not in this PR) backend_pdf's writeInfoDict which currently warns with stacklevel=2 on invalid keywords, but that'll point to some other internal method of backend_pdf which only makes things more (not less) confusing for the end user.) However, it would be even better not to apply either stacklevel=2, or _warn_external, indiscriminately. For example, the change in backend_bases.py in this PR is in key_press_handler, which is invoked asynchronously by the GUI event loop (well, I don't know if there's a good value for stacklevel in that case, so perhaps we can just live with it...). |
|
Oh, that's a nice idea in _warn_external. Sorry, I didn't follow your key_press_handler example. Why would _warn_external not work well in that case? And a git question - is there a way to continue working on this branch without polluting the history (for example changing warnings.warn(___, stacklevel=2) to _warn_external)? Or is it better to just create a new branch from master? |
|
Perhaps key_press_handler is not the best example but I remember looking into doing a global replace and thinking that some of the warn calls would become more confusing if using _warn_external. I don't have a case right now, someone just needs to do a careful review of the changes. |
|
Ok, thanks. I'm away from a computer until the middle of next week. When I return, I can do a global replace, as I don't know the code well enough to identify when _warn_external isn't appropriate. A more knowledgeable reviewer can then hopefully identify the completed cases. Will that be helpful, or should I pick a different issue to work on? Thanks for the git tip. I'll play around with it. |
|
Sounds good. |
lib/matplotlib/font_manager.py
Outdated
| @@ -874,7 +874,7 @@ def json_dump(data, filename): | |||
| try: | |||
| json.dump(data, fh, cls=JSONEncoder, indent=2) | |||
| except OSError as e: | |||
| warnings.warn('Could not save font_manager cache {}'.format(e)) | |||
| warnings.warn('Could not save font_manager cache {}'.format(e), stacklevel=2) | |||
There was a problem hiding this comment.
For example, I don't think that this warning would get clearer if using _warn_external (or even stacklevel=2).
There was a problem hiding this comment.
OK, I see what you mean.
Is it safe to assume that this warning will be "triggered" when importing pyplot? If so, then does it make sense to print the user line of code that imports pyplot i.e. import matplotlib.pyplot as plt?
I tried to manipulate _warn_external to do this without success. If this solution is acceptable, any ideas how to achieve that?
There was a problem hiding this comment.
Is it safe to assume that this warning will be "triggered" when importing pyplot?
Yes
If so, then does it make sense to print the user line of code that imports pyplot i.e. import matplotlib.pyplot as plt?
I wouldn't overthink it (there isn't anything really smart to do in this case IMO) and would just trigger a warning at this line; or perhaps is actually makes sense to use logging.warning instead of warnings.warn here in fact, now that I think of it...
There was a problem hiding this comment.
After further thought, I convinced myself that that should exactly be the criterion for warnings vs logging: by showing the line of offending code, does that point the user to something they should modify?
There was a problem hiding this comment.
Sounds good, thanks.
|
@hershen still interested to work on this? |
|
I am. Sorry it got set aside for so long. I'll try to finish it this weekend. |
|
No hurry. Just wanted to make sure this is not orphaned. |
aa8420c to
b00921b
Compare
|
I (finally) switched the
|
| @@ -221,7 +221,7 @@ def do_constrained_layout(fig, renderer, h_pad, w_pad, | |||
| # so this does the same w/o zeroing layout. | |||
| ax._set_position(newpos, which='original') | |||
| else: | |||
| warnings.warn('constrained_layout not applied. At least ' | |||
| cbook._warn_ext('constrained_layout not applied. At least ' | |||
There was a problem hiding this comment.
Good catch, thanks!
lib/matplotlib/artist.py
Outdated
| @@ -850,7 +852,7 @@ def set_rasterized(self, rasterized): | |||
| rasterized : bool or None | |||
| """ | |||
| if rasterized and not hasattr(self.draw, "_supports_rasterization"): | |||
| warnings.warn("Rasterization of '%s' will be ignored" % self) | |||
| logging.warning("Rasterization of '%s' will be ignored" % self) | |||
There was a problem hiding this comment.
looks like cbook._warn_external
| @@ -241,8 +240,8 @@ def handle_event(self, event): | |||
| return handler(event) | |||
|
|
|||
| def handle_unknown_event(self, event): | |||
| warnings.warn('Unhandled message type {0}. {1}'.format( | |||
| event['type'], event), stacklevel=2) | |||
| cbook._warn_external('Unhandled message type {0}. {1}'.format( | |||
There was a problem hiding this comment.
I think this should use logging (it's basically an event handler and thus likely to be called asynchronously anyways).
| @@ -1573,10 +1572,10 @@ def save_figure(self, *args): | |||
| if ext in ('svg', 'pdf', 'ps', 'eps', 'png') and format != ext: | |||
| # looks like they forgot to set the image type drop | |||
| # down, going with the extension. | |||
| warnings.warn( | |||
| cbook._warn_external( | |||
There was a problem hiding this comment.
logging
(this is most likely called throgh gui interaction)
| @@ -1837,10 +1836,10 @@ def trigger(self, *args): | |||
| if ext in ('svg', 'pdf', 'ps', 'eps', 'png') and format != ext: | |||
| # looks like they forgot to set the image type drop | |||
| # down, going with the extension. | |||
| warnings.warn( | |||
| cbook._warn_external( | |||
lib/matplotlib/backend_bases.py
Outdated
| @@ -2396,7 +2395,7 @@ def _get_uniform_gridstate(ticks): | |||
| try: | |||
| ax.set_yscale('log') | |||
| except ValueError as exc: | |||
| warnings.warn(str(exc)) | |||
| cbook._warn_external(str(exc)) | |||
There was a problem hiding this comment.
logging (most likely called through gui interaction)
lib/matplotlib/backend_bases.py
Outdated
| @@ -2409,7 +2408,7 @@ def _get_uniform_gridstate(ticks): | |||
| try: | |||
| ax.set_xscale('log') | |||
| except ValueError as exc: | |||
| warnings.warn(str(exc)) | |||
| cbook._warn_external(str(exc)) | |||
lib/matplotlib/lines.py
Outdated
| @@ -472,7 +472,7 @@ def contains(self, mouseevent): | |||
|
|
|||
| # Convert pick radius from points to pixels | |||
| if self.figure is None: | |||
| warnings.warn('no figure set when check if mouse is on line') | |||
| logging.warning('no figure set when check if mouse is on line') | |||
There was a problem hiding this comment.
I think warn_external here (can be callback or direct call).
There was a problem hiding this comment.
Isn't this gui interaction?
There was a problem hiding this comment.
I was thinking that one can also call contains() directly, but actually that's almost certainly much rarer, so logging is fine.
lib/matplotlib/mathtext.py
Outdated
| @@ -1595,7 +1590,7 @@ def _set_glue(self, x, sign, totals, error_type): | |||
| self.glue_ratio = 0. | |||
| if o == 0: | |||
| if len(self.children): | |||
| warnings.warn( | |||
| cbook._warn_external( | |||
There was a problem hiding this comment.
also logging? a bit borderline but consistent with the rest of the mathtext module
lib/matplotlib/__init__.py
Outdated
| @@ -244,7 +244,7 @@ def _set_logger_verbose_level(level_str='silent', file_str='sys.stdout'): | |||
| fileo = open(file_str, 'w') | |||
| # if this fails, we will just write to stdout | |||
| except IOError: | |||
| warnings.warn('could not open log file "{0}"' | |||
| logging.warning('could not open log file "{0}"' | |||
There was a problem hiding this comment.
throughout the PR:
- You should use the module-level logger
_log = logging.getLogger(__name__)then_log.warning(...). - Alignment of subsequent lines are a bit messed up sometimes.
There was a problem hiding this comment.
- Ah, right. I even read that I should do that, but for some reason it didn't register.
- Thanks for pointing that out. I wasn't really paying attention to that.
|
Thanks for the thorough changes! Left some comments. |
416fed2 to
1bece33
Compare
lib/matplotlib/mathtext.py
Outdated
|
|
||
| ############################################################################## | ||
| # FONTS | ||
|
|
||
|
|
There was a problem hiding this comment.
I added it because I got E302 expected 2 blank lines, found 1 from flake8 when it wasn't there.
Is there a better solution?
There was a problem hiding this comment.
Putting the blank line before the ##### seems more logical? Should hopefully also placate the style checker.
There was a problem hiding this comment.
You're right. That fixed it.
lib/matplotlib/tight_layout.py
Outdated
| matplotlib.cbook._warn_external( | ||
| 'The left and right margins cannot be made large enough to ' | ||
| 'accommodate all axes decorations. ') | ||
| matplotlib.cbook._warn_external('The left and right margins cannot ' |
There was a problem hiding this comment.
just do from matplotlib import cbook at the top?
6e355a7 to
bd01a00
Compare
|
Squashed. |
doc/devel/contributing.rst
Outdated
| `warnings.warn`) is that `cbook._warn_external` should be used for things the | ||
| user must change to stop the warning (typically in the source), whereas | ||
| `logging.warning` can be more persistent. Moreover, note that | ||
| `cbook._warn_extrenal` will by default only emit a given warning *once* for |
doc/devel/contributing.rst
Outdated
| layouting or rendering) should only log at this level. | ||
| By default, `warnings.warn` displays the line of code that has the `warn` call. | ||
| This usually isn't more informative than the warning message itself. Therefore, | ||
| Matplotlib uses `cbook._warn_external` which uses `warnings.warn`, but it goes |
doc/devel/contributing.rst
Outdated
| up the stack and displays the first line of code outside of Matplotlib. | ||
| For example, for the module:: | ||
|
|
||
| #in my_matplotlib_module.py |
doc/devel/contributing.rst
Outdated
| running the script:: | ||
|
|
||
| from matplotlib import my_matplotlib_module | ||
| my_matplotlib_module.set_range(0,0) #set range |
There was a problem hiding this comment.
Space after , and #; two spaces before #.
doc/devel/contributing.rst
Outdated
| UserWarning: Attempting to set identical bottom==top | ||
| warnings.warn('Attempting to set identical bottom==top') | ||
|
|
||
| Modifiying the module to use `cbook._warn_extermal`:: |
lib/matplotlib/bezier.py
Outdated
| @@ -2,7 +2,7 @@ | |||
| A module providing some utility functions regarding bezier path manipulation. | |||
| """ | |||
|
|
|||
| import warnings | |||
| import matplotlib.cbook as cbook | |||
There was a problem hiding this comment.
Move down to below numpy (can also add a blank line after numpy)
lib/matplotlib/colorbar.py
Outdated
| @@ -20,7 +20,7 @@ | |||
| ''' | |||
|
|
|||
| import logging | |||
| import warnings | |||
| import matplotlib.cbook as cbook | |||
There was a problem hiding this comment.
Move down to matplotlib section below.
| @@ -29,6 +28,9 @@ | |||
| from matplotlib import cbook, rcParams, backend_tools | |||
|
|
|||
| import wx | |||
| import logging | |||
There was a problem hiding this comment.
Move up to stdlib section of imports.
lib/matplotlib/dates.py
Outdated
| 'range. It may be necessary to add an ' | ||
| 'interval value to the ' | ||
| 'AutoDateLocator\'s intervald ' | ||
| 'dictionary. Defaulting to {' |
There was a problem hiding this comment.
Funny place to break; better to keep {0} together.
lib/matplotlib/image.py
Outdated
| warnings.warn( | ||
| "Casting input data from '{0}' to 'float64'" | ||
| "for imshow".format(A.dtype)) | ||
| cbook._warn_external("Casting input data from '{" |
|
Thanks for the thorough review @QuLogic. I addressed all your comments (and fixed a few other places where I had the same issues). I'll squash again when you're happy. |
|
Sorry, but what did I do to make the travis/no language test angry? |
|
Seems to be a bug in Homebrew's NumPy package. Feel free to squash, but it probably won't fix it. |
6cf17f3 to
9ecdec3
Compare
|
OK. Squashed. The travis issues here seem to be common to all the commits in PRs in the last ~15 hours, so I assume it's not something I'm did wrong. |
9ecdec3 to
226f1d4
Compare
|
Rebased. |
| warnings.warn("streamed pgf-code does not support raster " | ||
| "graphics, consider using the pgf-to-pdf option", | ||
| UserWarning, stacklevel=2) | ||
| _log.warning("streamed pgf-code does not support raster " |
There was a problem hiding this comment.
Isn't this of the category "things the that the user must change to stop the warning" and thus should be _warn_external?
| @@ -241,8 +242,8 @@ def handle_event(self, event): | |||
| return handler(event) | |||
|
|
|||
| def handle_unknown_event(self, event): | |||
| warnings.warn('Unhandled message type {0}. {1}'.format( | |||
| event['type'], event), stacklevel=2) | |||
| _log.warning('Unhandled message type {0}. {1}'.format( | |||
There was a problem hiding this comment.
This was changed to _log.warning following @anntzer's suggestion.
There was a problem hiding this comment.
In practice this will almost always get called asynchronously by the webserver event handler so "external" will point to the call to mainloop(), which is not really helpful.
| @@ -1573,10 +1575,10 @@ def save_figure(self, *args): | |||
| if ext in ('svg', 'pdf', 'ps', 'eps', 'png') and format != ext: | |||
| # looks like they forgot to set the image type drop | |||
| # down, going with the extension. | |||
| warnings.warn( | |||
| _log.warning( | |||
There was a problem hiding this comment.
improper use -> _warn_external?
There was a problem hiding this comment.
This was changed to _log.warning following @anntzer's suggestion.
There was a problem hiding this comment.
In practice this will almost always get called through a wx GUI event handler so "external" will point to the call to mainloop(), which is not really helpful.
| @@ -1837,10 +1839,10 @@ def trigger(self, *args): | |||
| if ext in ('svg', 'pdf', 'ps', 'eps', 'png') and format != ext: | |||
| # looks like they forgot to set the image type drop | |||
| # down, going with the extension. | |||
| warnings.warn( | |||
| _log.warning( | |||
There was a problem hiding this comment.
improper use -> _warn_external?
There was a problem hiding this comment.
This was changed to _log.warning following @anntzer's suggestion.
There was a problem hiding this comment.
In practice this will almost always get called through a wx GUI event handler so "external" will point to the call to mainloop(), which is not really helpful.
| @@ -93,7 +94,7 @@ def to_qcolor(color): | |||
| try: | |||
| rgba = mcolors.to_rgba(color) | |||
| except ValueError: | |||
| warnings.warn('Ignoring invalid color %r' % color, stacklevel=2) | |||
| _log.warning('Ignoring invalid color %r' % color) | |||
There was a problem hiding this comment.
improper value passed -> _warn_external?
lib/matplotlib/figure.py
Outdated
| warnings.warn('Matplotlib is currently using %s, which is a ' | ||
| 'non-GUI backend, so cannot show the figure.' | ||
| % get_backend()) | ||
| and warn): |
There was a problem hiding this comment.
Why the additional spaces? PEP-8 example suggests:
if (this_is_one_thing
and that_is_another_thing):
do_something()
| "Using bbox_to_anchor=(0,0,1,1) now.") | ||
| cbook._warn_external("Using the axes or figure transform " | ||
| "requires a bounding box in the respective " | ||
| "coordinates. Using bbox_to_anchor=(0,0,1," |
There was a problem hiding this comment.
I wouldn't break the parenthesis for better readability in the code. Would break befrore "Using" here even though the line will get quite short.
lib/mpl_toolkits/mplot3d/axes3d.py
Outdated
| @@ -1074,7 +1080,7 @@ def mouse_init(self, rotate_btn=1, zoom_btn=3): | |||
| c3 = canv.mpl_connect('button_release_event', self._button_release) | |||
| self._cids = [c1, c2, c3] | |||
| else: | |||
| warnings.warn( | |||
| _log.warning( | |||
There was a problem hiding this comment.
Is this not also a case the user should do something about (and thus _warn_external).
| @@ -765,7 +767,7 @@ def include_dirs_hook(): | |||
| ext.include_dirs.append(numpy.get_include()) | |||
| if not has_include_file( | |||
| ext.include_dirs, os.path.join("numpy", "arrayobject.h")): | |||
| warnings.warn( | |||
| _log.warning( | |||
There was a problem hiding this comment.
User action required -> _warn_extenal.
There was a problem hiding this comment.
This doesn't live in the matplotlib package so "external" will point to this very file; showing the source won't help.
|
Agreed with @timhoffm on some, left comments on others. |
…_external. 2) Updated contributions guidelines to use cbook._warn_external.
226f1d4 to
67e57b2
Compare
|
Added @timhoffm's suggestions. |
|
|
|
Can the title of this PR be updated to reflect its contents? I had a hard time finding it because its title ("Added stacklevel=2 to all warnings.warn calls (issue 10643)") leaves out the important part of changing every warning.warn call. |
PR Summary
Fix issue #10643
Note:
I liked @ImportanceOfBeingErnest 's suggestion of advising to set stacklevel in the documentation. I didn't find a good place for it, so I created a new section in contributing.rst. Please let me know if there's a better place or if it's too long.
PR Checklist