Scope and Namespaces

When Python encounters a variable name, it searches for it in a specific order: Local, Enclosing, Global, Built-in. This is called the LEGB rule and determines which variable you get when multiple scopes have the same name.

Local Scope

Variables created inside a function are local to that function. They exist only while the function runs and cannot be accessed from outside.

def my_function():
    x = 10  # Local variable
    print(f"Inside function: x = {x}")

my_function()  # Output: Inside function: x = 10

# This would cause an error:
# print(x)  # NameError: name 'x' is not defined

def another_function():
    y = 20  # Different local scope
    print(y)

# Each function has its own local scope

Global Scope

Variables defined at the module level (outside any function) are global. They can be read from inside functions, but modifying them requires the global keyword.

count = 0  # Global variable

def show_count():
    print(f"Count is: {count}")  # Reading global is OK

show_count()  # Output: Count is: 0

def try_to_modify():
    # This creates a NEW local variable, not modifying global
    count = 100
    print(f"Inside: {count}")

try_to_modify()  # Output: Inside: 100
print(f"Global still: {count}")  # Output: Global still: 0

Enclosing Scope

When you have nested functions, inner functions can access variables from the enclosing (outer) function. This is the "E" in LEGB.

def outer():
    message = "Hello from outer"  # Enclosing scope
    
    def inner():
        print(message)  # Accesses enclosing variable
    
    inner()

outer()  # Output: Hello from outer

# The inner function "remembers" the enclosing scope
def make_multiplier(n):
    def multiplier(x):
        return x * n  # n comes from enclosing scope
    return multiplier

double = make_multiplier(2)
print(double(5))  # Output: 10

x = "global"

def test():
    x = "local"
    print(x)

test()
print(x)

# Output:
# local   (function uses its local x)
# global  (global x is unchanged)

value = "global"

def outer():
    value = "enclosing"
    
    def inner():
        value = "local"
        print(value)
    
    inner()
    print(value)

outer()
print(value)

# Output:
# local      (inner's local)
# enclosing  (outer's local)
# global     (module level)

counter = 0

def increment():
    counter = counter + 1
    return counter

print(increment())

# UnboundLocalError: local variable 'counter' 
# referenced before assignment

# The assignment makes Python treat counter as local,
# but it tries to read it before the assignment completes.
# Fix: use 'global counter' at the start of the function

list = [1, 2, 3]
print(list)

# Later in the code...
numbers = list(range(5))  # What happens?

# TypeError: 'list' object is not callable

# The first line shadows the built-in 'list' function
# with a list object. When we try to call list(range(5)),
# we're calling the list [1,2,3] as a function.

# Fix: Never use built-in names as variable names
# Use descriptive names like 'my_list' or 'numbers'

Sometimes you need to modify variables from outer scopes. The global keyword lets you modify module-level variables. The nonlocal keyword lets you modify enclosing function variables.

Using global

The global keyword tells Python that a variable inside a function refers to the global variable, not a new local one.

counter = 0

def increment():
    global counter  # Declare we're using the global
    counter = counter + 1
    return counter

print(increment())  # Output: 1
print(increment())  # Output: 2
print(increment())  # Output: 3
print(f"Final: {counter}")  # Output: Final: 3

Using nonlocal

The nonlocal keyword is for nested functions. It lets an inner function modify a variable from the enclosing function.

def make_counter():
    count = 0  # Enclosing variable
    
    def increment():
        nonlocal count  # Modify enclosing, not create local
        count += 1
        return count
    
    return increment

counter = make_counter()
print(counter())  # Output: 1
print(counter())  # Output: 2
print(counter())  # Output: 3

# Each counter is independent
counter2 = make_counter()
print(counter2())  # Output: 1

total = 100

def add_to_total(amount):
    total = total + amount
    return total

add_to_total(50)
print(total)  # Should print 150

total = 100

def add_to_total(amount):
    global total
    total = total + amount
    return total

add_to_total(50)
print(total)  # Output: 150

def make_accumulator():
    total = 0
    
    def add(n):
        nonlocal total
        total += n
        return total
    
    return add

acc = make_accumulator()
print(acc(10))  # Output: 10
print(acc(5))   # Output: 15
print(acc(3))   # Output: 18

def make_toggle():
    state = False
    
    def toggle():
        nonlocal state
        state = not state
        return state
    
    return toggle

switch = make_toggle()
print(switch())  # Output: True
print(switch())  # Output: False
print(switch())  # Output: True

config = {"theme": "light", "font_size": 12}

def update_config(key, value):
    global config
    config[key] = value
    return f"Updated {key} to {value}"

def get_config(key):
    return config.get(key, "Not found")

print(get_config("theme"))      # Output: light
print(update_config("theme", "dark"))
print(get_config("theme"))      # Output: dark
print(update_config("font_size", 16))
print(get_config("font_size"))  # Output: 16

A closure is a function that remembers values from its enclosing scope even after that scope has finished executing. Closures enable powerful patterns like function factories and data encapsulation.

Closure Example

When you return an inner function, it carries its enclosing scope with it. This scope persists independently for each call to the outer function.

def make_greeting(greeting):
    def greet(name):
        return f"{greeting}, {name}!"
    return greet

# Create specialized greeting functions
say_hello = make_greeting("Hello")
say_hi = make_greeting("Hi")
say_welcome = make_greeting("Welcome")

print(say_hello("Alice"))    # Output: Hello, Alice!
print(say_hi("Bob"))         # Output: Hi, Bob!
print(say_welcome("Carol"))  # Output: Welcome, Carol!

Practical Closure: Caching

Closures can store state, making them perfect for caching expensive computations.

def make_cached_function(func):
    cache = {}
    
    def cached(*args):
        if args not in cache:
            cache[args] = func(*args)
        return cache[args]
    
    return cached

@make_cached_function
def slow_square(n):
    print(f"Computing {n}^2...")
    return n ** 2

print(slow_square(5))  # Computing 5^2... 25
print(slow_square(5))  # 25 (cached, no computation)
print(slow_square(3))  # Computing 3^2... 9

Closure: Private State

Closures can create private state that cannot be accessed directly from outside, similar to private variables in object-oriented programming.

def make_bank_account(initial_balance):
    balance = initial_balance  # Private state
    
    def deposit(amount):
        nonlocal balance
        balance += amount
        return balance
    
    def withdraw(amount):
        nonlocal balance
        if amount > balance:
            return "Insufficient funds"
        balance -= amount
        return balance
    
    def get_balance():
        return balance
    
    return deposit, withdraw, get_balance

dep, wd, bal = make_bank_account(100)
print(bal())    # Output: 100
print(dep(50))  # Output: 150
print(wd(30))   # Output: 120

Common Closure Pitfall: Loop Variables

A common mistake with closures involves capturing loop variables. All closures end up sharing the same variable, leading to unexpected results.

# WRONG: All functions share the same i
functions = []
for i in range(3):
    functions.append(lambda: i)

for f in functions:
    print(f())  # Output: 2, 2, 2 (not 0, 1, 2!)

# FIX: Capture the value with a default parameter
functions = []
for i in range(3):
    functions.append(lambda i=i: i)  # i=i captures current value

for f in functions:
    print(f())  # Output: 0, 1, 2 (correct!)

def make_multiplier(factor):
    def multiply(x):
        return x * factor
    return multiply

triple = make_multiplier(3)
quadruple = make_multiplier(4)

print(triple(10))     # Output: 30
print(quadruple(10))  # Output: 40

def count_calls(func):
    count = 0
    
    def wrapper(*args, **kwargs):
        nonlocal count
        count += 1
        return func(*args, **kwargs)
    
    def get_count():
        return count
    
    wrapper.get_count = get_count
    return wrapper

@count_calls
def add(a, b):
    return a + b

print(add(1, 2))           # Output: 3
print(add(3, 4))           # Output: 7
print(add.get_count())     # Output: 2

def rate_limiter(max_calls):
    def decorator(func):
        calls = 0
        def wrapper(*args, **kwargs):
            nonlocal calls
            if calls >= max_calls:
                return "Rate limit exceeded"
            calls += 1
            return func(*args, **kwargs)
        return wrapper
    return decorator

@rate_limiter(3)
def greet(name):
    return f"Hello, {name}!"

print(greet("Alice"))  # Output: Hello, Alice!
print(greet("Bob"))    # Output: Hello, Bob!
print(greet("Carol"))  # Output: Hello, Carol!
print(greet("Dave"))   # Output: Rate limit exceeded

def make_history_tracker():
    history = []
    
    def add(value):
        history.append(value)
        return f"Added: {value}"
    
    def get_all():
        return history.copy()
    
    def get_last(n=1):
        return history[-n:]
    
    return add, get_all, get_last

add, get_all, get_last = make_history_tracker()
print(add("first"))     # Output: Added: first
print(add("second"))    # Output: Added: second
print(add("third"))     # Output: Added: third
print(get_all())        # Output: ['first', 'second', 'third']
print(get_last(2))      # Output: ['second', 'third']

Python provides built-in functions to examine namespaces at runtime. You can inspect local and global variables, check what names exist in any scope, and even modify namespaces dynamically. This introspection is powerful for debugging and metaprogramming.

Using locals() and globals()

These functions return dictionaries representing the current namespace, allowing you to see exactly what variables exist and their values.

module_var = "I'm global"

def show_namespaces():
    local_var = "I'm local"
    another_local = 42
    
    print("Local namespace:")
    for name, value in locals().items():
        print(f"  {name} = {value}")
    
    print("\nGlobal namespace (filtered):")
    for name, value in globals().items():
        if not name.startswith('_'):
            print(f"  {name} = {value}")

show_namespaces()
# Output:
# Local namespace:
#   local_var = I'm local
#   another_local = 42
# Global namespace (filtered):
#   module_var = I'm global
#   show_namespaces = 

Using dir() for Exploration

The dir() function lists names in the current scope or, when given an object, lists that object's attributes and methods.

# dir() with no argument shows current scope
x = 10
y = 20

def my_func():
    pass

print("Current scope names:")
print([n for n in dir() if not n.startswith('_')])
# Output: ['my_func', 'x', 'y']

# dir() with an object shows its attributes
text = "hello"
print("\nString methods (sample):")
print([m for m in dir(text) if not m.startswith('_')][:10])
# Output: ['capitalize', 'casefold', 'center', 'count', 'encode', ...]

Dynamic Variable Access

Using namespace dictionaries, you can access variables by name dynamically, which is useful for configuration and reflection.

settings = {
    "debug_mode": True,
    "max_retries": 3,
    "timeout": 30
}

def get_setting(name):
    return globals()['settings'].get(name, None)

def create_variables_from_dict(data):
    for key, value in data.items():
        globals()[key] = value

# Access setting dynamically
print(get_setting("max_retries"))  # Output: 3

# Create global variables from dictionary
config = {"api_url": "https://api.example.com", "version": "2.0"}
create_variables_from_dict(config)
print(api_url)   # Output: https://api.example.com
print(version)   # Output: 2.0

def print_variables(**kwargs):
    for name, value in locals()['kwargs'].items():
        print(f"{name} = {value}")

print_variables(x=10, name="Alice", active=True)
# Output:
# x = 10
# name = Alice
# active = True

def get_user_functions():
    return [
        name for name, obj in globals().items()
        if callable(obj) and not name.startswith('_')
        and not isinstance(obj, type)  # Exclude classes
    ]

def greet(): pass
def calculate(): pass

print(get_user_functions())
# Output: ['get_user_functions', 'greet', 'calculate']

from contextlib import contextmanager
import sys

@contextmanager
def track_new_variables():
    frame = sys._getframe(1)
    before = set(frame.f_locals.keys())
    yield
    after = set(frame.f_locals.keys())
    new_vars = after - before
    if new_vars:
        print(f"New variables: {new_vars}")
    
# Usage requires careful scope handling
# This is an advanced introspection technique

def set_attributes(obj, attributes):
    for name, value in attributes.items():
        setattr(obj, name, value)
    return obj

class User:
    pass

user = User()
set_attributes(user, {"name": "Alice", "age": 30, "active": True})
print(user.name)    # Output: Alice
print(user.age)     # Output: 30
print(vars(user))   # Output: {'name': 'Alice', 'age': 30, 'active': True}

Understanding scope is one thing; using it effectively is another. Following best practices helps you write code that is easier to understand, test, and maintain. Proper scope management prevents bugs and makes your intentions clear to other developers.

Avoid Mutable Global State

Mutable global variables are particularly dangerous because any part of your program can modify them, leading to unpredictable behavior.

# BAD: Mutable global state
user_list = []

def add_user(name):
    user_list.append(name)  # Modifies global list

def get_users():
    return user_list

# GOOD: Encapsulated state with a class
class UserManager:
    def __init__(self):
        self._users = []
    
    def add_user(self, name):
        self._users.append(name)
    
    def get_users(self):
        return self._users.copy()  # Return copy for safety

# GOOD: Encapsulated state with closures
def create_user_manager():
    users = []
    
    def add(name):
        users.append(name)
    
    def get_all():
        return users.copy()
    
    return add, get_all

add_user, get_users = create_user_manager()

Parameter Passing vs Global Access

Functions that read global variables have hidden inputs, making them harder to test and understand. Prefer explicit parameters.

# BAD: Hidden dependency on global
config = {"debug": True, "retries": 3}

def process_data(data):
    if config["debug"]:  # Hidden dependency!
        print(f"Processing: {data}")
    for i in range(config["retries"]):
        # process...
        pass

# GOOD: Explicit parameters
def process_data(data, debug=False, retries=3):
    if debug:
        print(f"Processing: {data}")
    for i in range(retries):
        # process...
        pass

# ALSO GOOD: Configuration object passed explicitly
from dataclasses import dataclass

@dataclass
class Config:
    debug: bool = False
    retries: int = 3

def process_data(data, config: Config):
    if config.debug:
        print(f"Processing: {data}")
    # ...

When Global Variables Are Acceptable

Not all global variables are bad. Constants, module-level configurations loaded once, and certain design patterns benefit from global scope.

# OK: Constants (by convention, UPPERCASE)
MAX_CONNECTIONS = 100
DEFAULT_TIMEOUT = 30
API_BASE_URL = "https://api.example.com"

# OK: Module-level logger
import logging
logger = logging.getLogger(__name__)

def process():
    logger.info("Processing started")  # Logger is a reasonable global

# OK: Singleton pattern (sometimes)
_instance = None

def get_database():
    global _instance
    if _instance is None:
        _instance = Database()
    return _instance

total = 0

def add_sale(amount):
    global total
    total += amount

def get_total():
    return total

def reset():
    global total
    total = 0

# Problems:
# 1. Hidden mutable state - total can change unexpectedly
# 2. Hard to test - functions depend on global state
# 3. Not thread-safe - concurrent calls can corrupt total
# 4. Hard to have multiple independent totals

# Better approach: use a class or closure
class SalesTracker:
    def __init__(self):
        self.total = 0
    
    def add_sale(self, amount):
        self.total += amount
    
    def get_total(self):
        return self.total
    
    def reset(self):
        self.total = 0

cache = {}

def expensive_calculation(n):
    if n in cache:
        return cache[n]
    result = n ** 2 + n * 2 + 1  # Pretend this is slow
    cache[n] = result
    return result

# Solution 1: Closure
def create_cached_calculator():
    cache = {}
    
    def calculate(n):
        if n not in cache:
            cache[n] = n ** 2 + n * 2 + 1
        return cache[n]
    
    return calculate

expensive_calculation = create_cached_calculator()

# Solution 2: Use functools.lru_cache
from functools import lru_cache

@lru_cache(maxsize=128)
def expensive_calculation(n):
    return n ** 2 + n * 2 + 1

from dataclasses import dataclass
from typing import Optional

@dataclass
class AppConfig:
    debug: bool = False
    database_url: str = "sqlite:///app.db"
    max_connections: int = 10

class Application:
    def __init__(self, config: AppConfig):
        self.config = config
        self.db = Database(config.database_url, config.max_connections)
    
    def run(self):
        if self.config.debug:
            print("Running in debug mode")
        # ...

# Usage - config passed explicitly
config = AppConfig(debug=True)
app = Application(config)
app.run()

import threading

class ThreadSafeCounter:
    def __init__(self, initial=0):
        self._value = initial
        self._lock = threading.Lock()
    
    def increment(self, amount=1):
        with self._lock:
            self._value += amount
            return self._value
    
    def decrement(self, amount=1):
        with self._lock:
            self._value -= amount
            return self._value
    
    @property
    def value(self):
        with self._lock:
            return self._value

# Usage
counter = ThreadSafeCounter()
# Pass counter to threads that need it