Understanding `__all__` in Python: Controlling Module Exports

Introduction

In Python, organizing code into modules and packages is a common practice to ensure modularity and reusability. When working with these structures, particularly within package directories, you might encounter the special variable __all__. This tutorial will explain what __all__ does in Python, how it influences module imports, and why it’s an essential tool for controlling what gets exported from a module.

The Role of __all__

The __all__ variable is used within Python modules (often defined in the __init__.py file of a package) to specify which symbols should be accessible when using the from <module> import * statement. It defines a list of strings, each corresponding to a symbol that can be exported by the module.

Default Behavior Without __all__

By default, if you perform an import like:

from some_module import *

Python will import all symbols from some_module that do not start with an underscore (_). This is Python’s way of indicating that these symbols are intended for internal use only.

How __all__ Overrides Default Behavior

When you define the __all__ list in your module, it explicitly sets which symbols should be considered "public" and thus available through the wildcard import. Here’s a simple example:

# foo.py
__all__ = ['bar', 'baz']

waz = 5
bar = 10

def baz():
    return 'baz'

In this module, only bar and baz are included in __all__. Therefore, if someone imports from foo using:

from foo import *

Only bar and baz will be available. Attempting to access waz, which is not listed in __all__, would result in an error because it’s not exported by the wildcard import.

Example Usage

Consider this usage scenario for better understanding:

# main.py
from foo import *

print(bar)      # Outputs: 10
print(baz())    # Outputs: 'baz'

# print(waz)     # This would cause an error because waz is not in __all__

Best Practices

1. Use __all__ for Clarity: Explicitly listing the public API of a module helps other developers understand which parts are meant to be used externally.

2. Restrict Wildcard Imports: While __all__ provides control, it’s generally good practice to avoid using wildcard imports (from <module> import *). They can lead to namespace pollution and make it harder to trace where symbols came from in larger codebases.

3. Consistent Naming Conventions: Use clear naming conventions for private functions or variables (e.g., prefixing with an underscore) and maintain a consistent __all__ list to ensure that only intended parts of the module are exposed.

Conclusion

The __all__ variable in Python is a powerful tool for managing what gets imported when using wildcard imports. By defining this list, developers can explicitly control their module’s public interface, leading to cleaner and more maintainable code. Understanding and utilizing __all__ effectively ensures that your modules’ intended APIs are clear and consistent.