Import of fitz prints to console instead of generating a DeprecationWarning

[plesubc]

Description of the bug

Suppressing deprecation warning does not suppress the deprecation warning.

How to reproduce the bug

import something_up_the_chain_that_uses_fitz

warning: The fitzAPI is deprecated and will be removed in future. Useimport pymupdf instead

---

While I understand why you have a deprecation warning as of 1.28.2, it appears that your warnings (ie, message and message_warning in __init__.py are sent directly to stdout instead of using warnings and emitting, say a DeprecationWarning . (see __init__py:22307)

The end result of this is that the warning can't be suppressed in the way you might expect. That is, using warnings.filterwarnings("ignore", category=DeprecationWarning, module="fitz") doesn't suppress the output of the message to the console as one would hope. Which also means that any CLI program using PyMuPDF indirectly, will display a (useless or confusing) warning to the end user who now thinks that something is going wrong. And the programmer several levels up has to perform a kludgy workaround like:

sys.stdout = open(os.devnull, 'w')
import something_up_the_chain_that_uses_fitz
sys.stdout = sys.__stdout__

While this works, of course, it's kind of sub-optimal. I realize that the ideal fix is having everyone update their imports but if the import is indirect it's either not possible or involves tracking down the issue in someone else's work. The other option, of course, is to put a ceiling on the PyMuPDF import, which has obvious flaws.

Everything still works, though, so a cosmetic fix may not be high on your priority list.

PyMuPDF version

1.28.2

Operating system

MacOS

Python version

3.13

[JorjMcKie]

Instead of waiting for a fix, I recommend to start the migration away from import fitz.
The final removal of fitz will happen very soon anyway.
The easiest way with the least effort is doing a one-line change: import pymupdf as fitz.

[plesubc]

I realize that, but I'm not using PyMuPDF directly; I'm using a library 3 levels up. I've already mentioned this to the developers of the problematic libraries, but the problem is that the error message can't be suppressed by people with which it has no connection.

For instance, markdown-pdf uses import fitz. Short of forking the code and implementing the fix yourself, you are forced to use a the workaround. The problem isn't a direct import, it's when it happens far down the dependency chain.

[JorjMcKie]

@plesubc I do understand that you own options are limited here. But I wonder what the migration plans are then: "deprecation" means that things will seize to exist some time soon after all.

@julian-smith-artifex-com - maybe you could comment on this too?

[plesubc]

Yes, but I'm not using PyMuPDF; I'm using a library that uses PyMuPDF somewhere in the dependency chain of my software. My choices are:

• Find whatever in my imported library is using PyMuPDF and inform the creator of the package and suggest the very obvious fix. I have done this already. However, I have zero control over whether or not this is done, or when. Although development of that package is still active, I have no direct involvement.
• Fork the problematic package (if the licence permits) and then publish a fix to PyPi. That would solve the problem, but is not a particularly useful long-term solution.
• Force a lower version of PyMuPDF to a time when the warning did not exist
• Use a kludgy hack to suppress the warning

What I should, in ideal world, be able to do is use the warnings module in the Python standard library to suppress the warning so it doesn't print a meaningless and confusing warning to end users of a CLI application. It gives them information that they have no idea about and can't fix.

I can and have suppressed the warning with the kludgy hack routing stderr to /dev/null when I import the problem package. If the problematic import is never fixed, that's fine — I can fork it or find alternatives, but doing that now would be dumb as the package development is still active.

But my point is that developers should ideally be able to suppress the deprecation warning in the same way that they normally can handle other warning, ie, with warnings. Obviously, not being able to do so is not a deal breaker, but I had to look through your code to find out why my suppression of the warning wasn't working the way it traditionally does. My suggestion is that warnings are emitted using warnings.

[julian-smith-artifex-com]

Unfortunately wasn't aware of the warnings module when i made the change. I agree it would be better to use it instead of the current plain write to stdout, and we'll do that in our next release.

Thanks for notifying the upstream developers by the way, that's really helpful.

[plesubc]

Thanks! In other good news, the package developers in my dependency chain have already implemented the fix. I'm sure there's more out there but at least the word is out now. . .