This class provides a base implementation for monitoring file system changes and triggering application reloads. It manages a registry of watched files and directories, coordinates with the application's startup state, and defines a lifecycle for continuous execution via a run loop. Subclasses are expected to implement the specific polling or event-based mechanism for detecting file modifications.
Attributes
| Attribute | Type | Description |
|---|
| extra_files | set = set() | A set of additional file paths to be monitored for changes alongside standard Python module files. |
| directory_globs | defaultdict = defaultdict(set) | A mapping of directory paths to sets of glob patterns used to identify groups of files that should trigger a reload. |
| _stop_condition | threading.Event = threading.Event() | A threading event used to signal and manage the termination of the reloader's execution loop. |
Constructor
Signature
Methods
watch_dir()
@classmethod
def watch_dir(
path: string,
glob: string
) - > null
Registers a directory and a glob pattern to be monitored for file changes. The path is resolved to an absolute path before being added to the watch list.
Parameters
| Name | Type | Description |
|---|
| path | string | The filesystem path to the directory that should be monitored. |
| glob | string | A glob pattern used to filter which files within the directory trigger a reload. |
Returns
| Type | Description |
|---|
null | Nothing is returned. |
watched_files()
@classmethod
def watched_files(
include_globs: boolean = True
) - > generator
Yield all files that need to be watched, including module files and files within globs.
Parameters
| Name | Type | Description |
|---|
| include_globs | boolean = True | Determines whether to include files matching the registered directory glob patterns in the result. |
Returns
| Type | Description |
|---|
generator | An iterable yielding Path objects for all discovered python modules, extra files, and glob matches. |
wait_for_apps_ready()
@classmethod
def wait_for_apps_ready(
app_reg: django.apps.registry.Apps,
django_main_thread: threading.Thread
) - > boolean
Wait until Django reports that the apps have been loaded. If the given thread has terminated before the apps are ready, then a SyntaxError or other non-recoverable error has been raised. In that case, stop waiting for the apps_ready event and continue processing.
Parameters
| Name | Type | Description |
|---|
| app_reg | django.apps.registry.Apps | The Django app registry instance containing the ready_event. |
| django_main_thread | threading.Thread | The primary thread running the Django application to monitor for premature termination. |
Returns
| Type | Description |
|---|
boolean | True if the thread is alive and the ready event has been triggered, or False if the thread is terminated while waiting for the event. |
run()
@classmethod
def run(
django_main_thread: threading.Thread
) - > null
Initializes the reloader by waiting for the application to be ready, pre-loading URL configurations, and starting the main execution loop.
Parameters
| Name | Type | Description |
|---|
| django_main_thread | threading.Thread | The main execution thread of the Django application. |
Returns
| Type | Description |
|---|
null | Nothing is returned. |
run_loop()
@classmethod
def run_loop() - > null
Executes the reloader's main loop, repeatedly calling tick() until the stop condition is met or the ticker is exhausted.
Returns
| Type | Description |
|---|
null | Nothing is returned. |
tick()
@classmethod
def tick() - > generator
This generator is called in a loop from run_loop. It's important that the method takes care of pausing or otherwise waiting for a period of time. This split between run_loop() and tick() is to improve the testability of the reloader implementations by decoupling the work they do from the loop.
Returns
| Type | Description |
|---|
generator | A generator that yields control back to the run loop after performing a check. |
check_availability()
@classmethod
def check_availability() - > boolean
Checks if the specific reloader implementation is available for use in the current environment.
Returns
| Type | Description |
|---|
boolean | True if the reloader can be used, otherwise raises NotImplementedError. |
notify_file_changed()
@classmethod
def notify_file_changed(
path: Path
) - > null
Signals that a specific file has changed and triggers a reload if no signal receivers prevent it.
Parameters
| Name | Type | Description |
|---|
| path | Path | The filesystem path of the file that was modified. |
Returns
| Type | Description |
|---|
null | Nothing is returned. |
should_stop()
@classmethod
def should_stop() - > boolean
Indicates whether the reloader has received a signal to terminate its execution loop.
Returns
| Type | Description |
|---|
boolean | True if the internal stop event is set, False otherwise. |
stop()
@classmethod
def stop() - > null
Sets the internal stop condition to signal that the reloader should cease operations and exit its loop.
Returns
| Type | Description |
|---|
null | Nothing is returned. |