importlib.reload in CPython 3.11: keeping existing object state consistent after a zero-downtime module swap

Answer the exact question first

In CPython 3.11 importlib.reload() re‑executes the module body and swaps sys.modules[mod] for a brand‑new module object. Existing instances created from classes defined in that module keep referencing the old class objects, so a naive reload will leave two versions of the same class in memory. Below is a minimal, idiomatic pattern that:

• reloads the module,
• migrates existing instances to the new class definition,
• guards one‑time side effects such as signal handler registration,
• and highlights where stale references may still exist.

1. Reload and migrate instances

import importlib, sys

# The module we want to hot‑swap
mod_name = 'myservice'
mod = sys.modules[mod_name]

# Keep a reference to the old class before the reload
OldCls = getattr(mod, 'Service')

# Perform the reload
new_mod = importlib.reload(mod)
NewCls = getattr(new_mod, 'Service')

# Migrate every live instance that was created from OldCls
for obj in list(globals().values()):
    if isinstance(obj, OldCls):
        # Preserve attributes that exist in the old instance
        obj.__class__ = NewCls
        # If the new class has a different layout (e.g. __slots__), copy missing attrs
        for name, value in obj.__dict__.items():
            if not hasattr(obj, name):
                setattr(obj, name, value)

Key assumptions:

• Both OldCls and NewCls are plain Python classes (no __slots__ or custom metaclass). If __slots__ is used, the migration must explicitly copy slot attributes or avoid __class__ reassignment.
• The application runs in a single thread or a lock protects the reload/migration window to avoid race conditions.

2. Guarding module‑level side effects

Side effects that should only run once (e.g. signal handlers) can be protected by a sentinel attribute in the module:

# In myservice.py
import signal

if not getattr(sys.modules[__name__], '_handlers_registered', False):
    def handler(signum, frame):
        print('Signal received')
    signal.signal(signal.SIGINT, handler)
    sys.modules[__name__]._handlers_registered = True

When the module body is re‑executed, the sentinel prevents re‑registration. If the sentinel is missing, reload() will run the body again and you’ll get duplicate handlers.

3. Stale references that require manual cleanup

Reloading does not touch references that other modules or objects hold to the old module object. Common stale spots:

• Imported submodules that were imported before the reload; they still point to the old definitions unless you reload them explicitly.
• Global registries or caches defined in the module that were populated before the reload; they will stay in memory until you clear or merge them.
• Objects that stored a reference to the old module object (e.g. mod.__dict__ snapshots).

A conservative approach is to expose a cleanup() function in the module that removes or merges such stale state, and call it after the reload before assigning new classes to instances.

4. Verification steps

1. Create a test instance of Service, call importlib.reload(), assign __class__ as shown, and assert that instance attributes (including those set in __init__) are still present.
2. Use signal.getsignal(signal.SIGINT) before and after reload to confirm the handler is registered only once.
3. Check sys.modules['myservice'] before and after reload to ensure the module object has changed.
4. Optionally, inspect other modules that import myservice to verify they still reference the old module; if so, reload those modules explicitly.

Question for you

Does myservice.Service use __slots__ or a custom metaclass? That detail determines whether the simple __class__ reassignment will work or whether you need a more elaborate migration routine.