Please flatten the PyFPDF Namespace... to recover lost user-developer time due to a "warning" that stops execution and results in an error.

[richlysakowski]

I appreciate the hard work that so many people have done on fpdf2 to develop and maintain it all these years. We picked it because it really is simpler than most other PDF generators / report writers.

I want to make a suggestion to simplify it even more, because we lost about 4 hours of time the past few days tracking down an error caused by an obscure and misleading deprecation "warning" Exception type. We were trying to apply fpdf2 within a Streamlit application. A poorly worded exception misled us for a long time.... fpdf simple examples worked in one environment and not another, then by itself, but not when called inside the Streamlit script.

We were in the process of completely removing the "deprecation.py" module and all references to it, when I asked the developer how he was importing and referencing the constructor. Then I parsed the namespace from installation to the final constructor function to get the shortest namespace path to reference the constructor. Tracing the full namespace path gave us the correct way to reference it. It was confusing to track down the names because there is an FPDF() inside "fpdf" inside "fpdf" inside "fpdf2" inside PyFPDF.

PROBLEM:
The full path to the FPDF class constructor is:

https://github.com/PyFPDF/fpdf2/blob/master/fpdf/fpdf.py and then instantiate the class FPDF()

The full path through the package name, import and path reference is: PyFPDF.fpdf2.fpdf.fpdf.FPDF()

The class FPDF(GraphicsStateMixin) is located in github.com/PyFPDF/fpdf2/fpdf)/fpdf.py

When we finally got it working, the "bug" was due to a simple misnaming of imports.
Should it have been fpdf, fpdf2, FPDF, or "from fpdf2 import FPDF"? Or was it "from fpdf import FPDF"?

The error we got was "TypeError: 'WarnOnDeprecatedModuleAttributes' object is not callable".

The currently 3-level nested namespace path "fpdf2.fpdf.fpdf.FPDF()" made it easy to unwittingly rename / misname the imports and throw an exception error. The exception thrown is: "WarnOnDeprecatedModuleAttributes", which has nothing to do with improper imports or module naming.

POSSIBLE SOLUTION
Flatten the namespace. Take out the "hoisting" being done in init.py to get FPDF() to the top. Drop what you don't need any more. Make a break with the past (somewhere in PHP in ?)

Don't use init.py to try to flatten references to an overly nested namespace.

QUESTIONS:
The main fpdf.py module has this warning object in two places.
It is not clear why line 4508 reassigns WarnOnDeprecatedModuleAttributes (or why does it exist?)

52: from .deprecation import WarnOnDeprecatedModuleAttributes
4508: sys.modules[name].class = WarnOnDeprecatedModuleAttributes

What is the "font_cache_dir optional argument of the fpdf.FPDF constructor" and why does it exist? There are no instructions on how to use it?

MORE DETAIL

Inspecting the documentation for this custom Exception type gives the following code. It is not clear why and how getattr() exist and how to use them. What are "fpdf.FPDF_CACHE_DIR" and "fpdf.FPDF_CACHE_MODE" used for ??

There are no docstrings for this class or its functions.

class WarnOnDeprecatedModuleAttributes
(
*args, **kwargs)
Create a module object.

The name must be a string; the optional doc argument can have any type.

EXPAND SOURCE CODE
class WarnOnDeprecatedModuleAttributes(ModuleType):
    def __getattr__(self, name):
        if name in ("FPDF_CACHE_DIR", "FPDF_CACHE_MODE"):
            warnings.warn(
                "fpdf.FPDF_CACHE_DIR & fpdf.FPDF_CACHE_MODE"
                " have been deprecated in favour of"
                " FPDF(font_cache_dir=...)",
                DeprecationWarning,
                stacklevel=2,
            )
            return None
        # pylint: disable=no-member
        return super().__getattribute__(name)

    def __setattr__(self, name, value):
        if name in ("FPDF_CACHE_DIR", "FPDF_CACHE_MODE"):
            warnings.warn(
                "fpdf.FPDF_CACHE_DIR & fpdf.FPDF_CACHE_MODE"
                " have been deprecated in favour of"
                " FPDF(font_cache_dir=...)",
                DeprecationWarning,
                stacklevel=2,
            )
            return
        super().__setattr__(name, value)

[Lucas-C]

Hi @richlysakowski!

Thank you for the time you took to report this bad user experience.
That's very useful feedback to improve fpdf2.

we lost about 4 hours of time the past few days tracking down an error caused by an obscure and misleading deprecation "warning" Exception type.

Could you please mention what was the exact deprecation warning? And what was misleading?
Given your experience, it seems important to me that we improve the wording of this warning.
The TypeError: 'WarnOnDeprecatedModuleAttributes' object is not callable error that you mentioned is not a deprecation warning,
so I guess that you faced another misleading message.

When we finally got it working, the "bug" was due to a simple misnaming of imports.

What was the exact import you used?
I don't understand why the same import statement was working in one environment, but not in another.

The error we got was "TypeError: 'WarnOnDeprecatedModuleAttributes' object is not callable".

This class is instantiated there: https://github.com/PyFPDF/fpdf2/blob/2.6.1/fpdf/__init__.py#L24
Its purpose is to warn users trying to use deprecated module constants of fpdf2.
Getting a object is not callable error could mean that you tried to use the module as a class and tried to instantiated it:

from fpdf import fpdf
fpdf()

Was that the problem in your case?

Flatten the namespace. Take out the "hoisting" being done in init.py to get FPDF() to the top. Drop what you don't need any more. Make a break with the past (somewhere in PHP in ?). Don't use init.py to try to flatten references to an overly nested namespace.

As a maintainer, I consider backward compatibility a major goal & commitment toward the library users.
It can be a very painful experience to have your code base broken by a library version upgrade,
especially when you really need this upgrade in order to benefit from a new feature or bugfix.
This is why I prefer not to break backward compatibility unless absolutely needed.
Moreover, this approach helps newcommers to migrate from PyFPDF to fpdf2,
and our oldest deprecated feature is only 2 years old.

For all those reasons, I'm not convinced by your suggestion for now.
But I'd be willing to: 1) avoid pitfalls like the one you faced 2) make fpdf2 imports clearer.

1. in order to avoid users to face the problem you had, I'm going to patch fpdf2 so that the error raised is clearer,
   and that instead of a message like TypeError: 'WarnOnDeprecatedModuleAttributes' object is not callable,
   users get something like You tried to instantied the fpdf module. You probably want to import the FPDF class instead: from fpdf import FPDF. What do you think of this @richlysakowski? Before implementing this, I'd like to be sure that this was indeed the origin of your problem: could you confirm that please?

2. currently, this is how one imports & uses the FPDF class:

from fpdf import FPDF
doc = FPDF()

Would you have any suggestions @richlysakowski on how to make the import clearer?
In my humble opinion, this is simple and clear enough, so I'd be happy to get other people feedbacks 😊

Just out of curiosity:

• how old is your fpdf2 code base? I'm just interested in an order of magnitude: a few weeks or a several years.
• have you enabled deprecation warnings on your project, as fpdf2 recommend to do?
• if so, have you noticed that your code used deprecated features?

What is the "font_cache_dir optional argument of the fpdf.FPDF constructor" and why does it exist? There are no instructions on how to use it?

As mentioned in the documentation and in the code, this argument is deprecated and useless.
For more information on the removal of this feature, see #345

As I mentioned above, the goal of the WarnOnDeprecatedModuleAttributes class
is to warn users if they use the deprecated FPDF_CACHE_DIR & FPDF_CACHE_MODE module constants,
without breaking their code.

I hope I answer all your questions at this point.

Again, thank you for your message! 😊

[richlysakowski]

We are first-time users of fpdf2, and are using the latest version (v2.6.1).

We actually got 2 error messages that were confusing to track down.
The first error message from the WarnOnDeprecatedModuleAttributes class was that the "name" object needed to be a string, because apparently something else was being passed (probably the WarnOnDeprecatedModuleAttributes object type) when we tried to instantiate FPDF.

Our application did not use any prior version, so deprecation warnings did not apply in our circumstance. In our case, we tried to eliminate the deprecation messages because they did not apply. We tried various ways to eliminate the deprecation messages, including a rather humorous Python package named "shutup" that we found via StackOverflow. That did not work either.

The lead developer is a very good recent Python programmer, but did not understand why the warning and error messages was thrown.

The import that used was "from fpdf import FPDF", and then instantiated with "pdf_doc = FPDF()", which threw an error.

Your suggestion for the error message will help "You tried to instantiate the fpdf module. You probably want to import the FPDF class instead: from fpdf import FPDF."

I fully understand the need for backward compatibility, so the best resolution is to improve error handling and reporting, and provide descriptive docstrings for any custom Exception types, and explain what the fix should be for legacy users and how best for new users to ignore the exception warnings.

How to handle the nested namespace issue? I am not really sure. I like following the Zen of Python philosophy that "Flat is better than nested" to keep things simple, but I know the world of software architecture is not flat. Anyway, I will look at the package object hierarachy to understand its architecture better. Very instructive for me.

Personally, I don't like seeing __init__.py package initializers with much code in them, because I don't expect to see really substantial functionality hidden there. Some people hide functional scripts there. My personal opinion is that any substantial functionality code should be moved into its own module, and only left in init.py if deals with subpackage imports and loading dependent modules. I just re-examined fpdf2/fpdf/__init__.py file and I see that the dependency import section is not very long, but it is a reach to get to the FPDF() constructor function: fpdf2/fpdf/fpdf.py/ FPDF().

I am still not clear what this line does; sys.modules[__name__].__class__ = WarnOnDeprecatedModuleAttributes

I see it in two different places (fpdf/init.py line 24, and fpdf.py, line 4589) :

It looks like it is assigning or adding to the current sys.modules namespace, i.e., sys.modules[__name__].__class__. But I don't understand why, is it to get FPDF's custom exception into the runtime session?

[Lucas-C]

The first error message from the WarnOnDeprecatedModuleAttributes class was that the "name" object needed to be a string, because apparently something else was being passed (probably the WarnOnDeprecatedModuleAttributes object type) when we tried to instantiate FPDF.

Interesting. Thank you for the details.
I really do not see how to reproduce this...
Would you have some code reproducing this error by any chance?

Our application did not use any prior version, so deprecation warnings did not apply in our circumstance. In our case, we tried to eliminate the deprecation messages because they did not apply.

I don't quite follow you there... What is the meaning of "did not apply" in this context?
If you built your application recently using fpdf2, you should not have any deprecation warning produced,
as you must not have used any deprecated method or parameter.

While you mentioned two kind of error messages,
so far you did not mention the content of any deprecation message:
do you remind what deprecation warnings were produced exactly?

I am still not clear what this line does; sys.modules[__name__].__class__ = WarnOnDeprecatedModuleAttributes

This is a Python pattern from sir Guido Von Rossum: https://stackoverflow.com/a/72911884/636849

a module can define a class with the desired functionality, and then at
the end, replace itself in sys.modules with an instance of that class

---

I opened PR #690 to improve the error message in case the fpdf module is instantiated, as suggested.