Best Practices for Sharing Global Variables Between Python Modules

Problem Background and Common Misconceptions

In large Python projects, developers often need to share data across multiple modules. A common requirement is defining global variables that can be accessed and modified across different files. However, many developers encounter various issues when working with global variables, especially when projects contain dozens of files.

From the Q&A data, we can see that developers typically attempt two common but incorrect approaches: the first involves defining global variables in the main module and expecting other modules to access them directly; the second creates a dedicated global variable file but handles initialization incorrectly. Both methods fail to properly implement cross-module variable sharing.

Python Module System and Global Variable Scope

To understand why these approaches fail, we need to deeply understand Python's module system. In Python, each module has its own global namespace. When a variable is defined in one module, it only exists within that module's global scope. Other modules cannot directly access these variables unless through explicit import mechanisms.

Using the global keyword only affects the current module's global namespace and cannot cross module boundaries. Similarly, the globals() function returns the global dictionary of the current module, not that of other modules.

Dedicated Configuration Module Solution

Based on the best answer recommendation, we adopt the dedicated configuration module approach. The core idea of this method is to create a module specifically responsible for managing global variables, with all other modules accessing shared variables by importing this configuration module.

First, create the configuration module settings.py:

# settings.py

def init():
    global myList
    myList = []

The key aspect of this design is encapsulating variable initialization within a function rather than executing it automatically during module loading. This allows precise control over initialization timing, avoiding variable creation when not needed.

Submodule Implementation

In submodules that need to use global variables, we import the configuration module and directly use its variables:

# subfile.py

import settings

def stuff():
    settings.myList.append('hey')

Note that submodules don't need to call the initialization function—they simply use the already initialized variables. This design follows the single responsibility principle, with the configuration module managing variable lifecycles while other modules focus on usage.

Main Module Coordination Role

The main module is responsible for application startup and coordination, including global variable initialization:

# main.py

import settings
import subfile

settings.init()          # Call only once
subfile.stuff()         # Perform operations with global variables
print(settings.myList[0]) # Check results

This design ensures global variables are properly initialized before use while avoiding duplicate initialization issues. The main module serves as the application entry point, coordinating execution order across modules.

Technical Principles Deep Analysis

This solution works because of Python's module import mechanism. When multiple modules import the same module, Python ensures the module is loaded only once. This means the settings module is the same instance across all importing modules, with its variables being shared.

Module-level variables in Python are actually attributes of the module object. When we execute settings.myList, we're accessing the myList attribute of the settings module object. Since all imports point to the same module object, attribute modifications are visible at all import locations.

Avoiding Common Pitfalls

This solution successfully avoids several common issues mentioned in the Q&A:

Namespace Pollution: By encapsulating global variables in a dedicated module, we avoid polluting other modules' namespaces. Each module imports only the configuration variables it needs, not all global variables.

Initialization Timing Issues: By encapsulating initialization within a function, we can precisely control when variables are created. This is particularly useful for lazy initialization or conditional initialization scenarios.

Circular Imports: The dedicated configuration module design reduces circular import risks since configuration modules typically don't depend on other business modules.

Extended Application Scenarios

This pattern can extend beyond simple list sharing to more complex application scenarios:

Configuration Management: Application configuration parameters (such as database connection strings, API keys, etc.) can be stored in configuration modules.

State Sharing: When application state needs to be shared across modules, this pattern can manage shared state effectively.

Cache Management: For cached data that needs sharing across multiple modules, configuration modules provide unified management interfaces.

Best Practice Recommendations

Based on real project experience, we propose the following best practices:

Naming Conventions: Use clear names for configuration modules, such as config.py, settings.py, or globals.py.

Documentation: Add detailed documentation in configuration modules explaining each global variable's purpose and expected usage.

Type Hints: Add type hints for global variables to improve code readability and maintainability.

Access Control: For variables requiring protection, consider using properties or methods to control access.

Alternative Approach Comparison

While dedicated configuration modules are the most recommended solution, understanding other alternatives is valuable:

Class Singleton Pattern: Classes can implement similar shared state, but module-level singletons are more concise in Python.

Environment Variables: For configuration information, environment variables are another option but aren't suitable for shared state requiring runtime modifications.

External Storage: For persistence needs, consider database or file storage, though this adds complexity.

Conclusion

Implementing global variable sharing between Python modules through dedicated configuration modules is a proven and reliable method. It not only solves technical problems but also provides good software engineering practices. This approach is simple, clear, and easy to maintain, making it particularly suitable for medium to large Python project development.

In practical applications, developers should adapt this pattern according to specific requirements, but the core principle—managing shared state through dedicated modules—remains valid guidance.