is redudant to use `__all__` and `import specific_module`?

Question:

Background

Reading the answers for this question, and looking at the Pandas and Django repository.

If __all__ is defined then when you import * from your package, only the names defined in __all__ are imported in the current namespace.

I immediately draw the conclusion that if I use import package.specific_module, then there is no benefit of defining __all__.

However, digging around some common project like Pandas, Django… I realised that developers import specific modules and pass all of them as a list to the __all__ variable, like the below example:

from pandas.core.groupby.generic import (
    DataFrameGroupBy,
    NamedAgg,
    SeriesGroupBy,
)
from pandas.core.groupby.groupby import GroupBy
from pandas.core.groupby.grouper import Grouper

__all__ = [
    "DataFrameGroupBy",
    "NamedAgg",
    "SeriesGroupBy",
    "GroupBy",
    "Grouper",
]

Question

I know that pydocs will ignore modules that aren’t in the __all__ variable.
But besides that, what are the other benefits of importing specific modules from within __init__.py and at the same time pass them as a list to the __all__ variable? isn’t it redundant?

Asked By: asa

||

Answers:

If you see the commit that introduced this code, you’ll notice that this style of coding will not trigger the Flake8 rule "Module imported but unused (F401)", thus leading to a cleaner code. In my opinion, it is easier to understand the purpose of the __all__ declaration than to understand those noqa pragmas at the imports.

By the way, the commit message itself states the intent clearly, it says:

Removed "# noqa: F401" comments (#30832)

Implemented __all__ for each changed file

And here’s the relevant part of the commit:

diff --git a/pandas/core/groupby/__init__.py b/pandas/core/groupby/__init__.py
index 252f20ed40068..0c5d2658978b4 100644
--- a/pandas/core/groupby/__init__.py
+++ b/pandas/core/groupby/__init__.py
@@ -1,7 +1,11 @@
-from pandas.core.groupby.generic import (  # noqa: F401
-    DataFrameGroupBy,
-    NamedAgg,
-    SeriesGroupBy,
-)
-from pandas.core.groupby.groupby import GroupBy  # noqa: F401
-from pandas.core.groupby.grouper import Grouper  # noqa: F401
+from pandas.core.groupby.generic import DataFrameGroupBy, NamedAgg, SeriesGroupBy
+from pandas.core.groupby.groupby import GroupBy
+from pandas.core.groupby.grouper import Grouper
+
+__all__ = [
+    "DataFrameGroupBy",
+    "NamedAgg",
+    "SeriesGroupBy",
+    "GroupBy",
+    "Grouper",
+]

At the end of the day, we’re all trying to write code that’s easier to read by both programmers and our code quality tools.

Answered By: Fábio Batista
Categories: questions Tags: , ,
Answers are sorted by their score. The answer accepted by the question owner as the best is marked with
at the top-right corner.