move monkeypatching from app's ready() method to function (#3)

Author: joshuadavidthomas

CHANGELOG.md

@@ -17,6 +17,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 ## [Unreleased]
 
+### Changed
+
+- **Breaking**: Move monkeypatching from Django app's `ready()` method to dedicated function. Instead of just adding the app to `INSTALLED_APPS`, you now need to explicitly call `django_lazy_gdal.monkeypatch()` at the top of your settings file.
+
 ## [0.1.0]
 
 ### Added

README.md

@@ -24,21 +24,22 @@ A Django app that patches `django.contrib.gis` to lazily load the GDAL library,
     uv sync
     ```
 
-2. Add the app to your Django project's `INSTALLED_APPS` **after** `django.contrib.gis`:
+2. Import and call the `monkeypatch` function at the top of your Django project's settings module:
 
    ```python
-   INSTALLED_APPS = [
-       # Add these at the top 
-       'django.contrib.gis',
-       'django_lazy_gdal',
-       # ...
-   ]
+   # settings.py - add these lines at the TOP of the file
+   import django_lazy_gdal
+
+
+   django_lazy_gdal.monkeypatch()
+
+   # ... rest of your settings file
    ```
 
-> [!NOTE]
-> **Order matters!** It's crucial to place `'django_lazy_gdal'` immediately after `'django.contrib.gis'` and before any other apps that might access the GeoDjango models in `django.contrib.gis.models` or access `django.contrib.gis.gdal.libgdal` directly. This ensures that the patching occurs before other apps access the module, making the lazy loading effective throughout your project.
+> [!IMPORTANT]
+> **Timing matters!** It's crucial to call `django_lazy_gdal.monkeypatch()` before any GeoDjango modules are imported. This is because Django imports models, which in turn imports the existing eager GDAL loading via imports in `django.contrib.gis.models`, *before* running app `ready()` methods. Calling the monkeypatch function at the top of your settings ensures the patching occurs before any other imports that might access `django.contrib.gis.gdal.libgdal`.
 
-3. That's it! The library will automatically patch Django's `django.contrib.gis.gdal.libgdal` module to use lazy loading.
+3. That's it! The library will patch Django's `django.contrib.gis.gdal.libgdal` module to use lazy loading.
 
 ## Why?
 

RELEASING.md

@@ -65,4 +65,3 @@ When it comes time to cut a new release, follow these steps:
 We try our best to adhere to [Semantic Versioning](https://semver.org/), but we do not promise to follow it perfectly (and let's be honest, this is the case with a lot of projects using SemVer).
 
 In general, use your best judgement when choosing the next version number. If you are unsure, you can always ask for a second opinion from another contributor.
-

pyproject.toml

@@ -76,7 +76,7 @@ exclude_lines = [
 ]
 # since we are not testing the actual functionality of libgdal
 # we don't need to cover all code paths
-fail_under = 60
+fail_under = 50
 
 [tool.coverage.run]
 omit = [
@@ -194,4 +194,3 @@ keep-runtime-typing = true
 
 [tool.uv]
 required-version = "<0.8"
-

src/django_lazy_gdal/__init__.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import importlib
+import logging
+import sys
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+_patching_done = False
+
+
+def monkeypatch() -> None:
+    """
+    Monkeypatches Django's GDAL library loader to use our lazy loader instead.
+
+    This function must be called before Django's model importing phase to be effective.
+    Typically, it should be called at the top of your settings module, before any
+    apps or models are imported.
+    """
+    global _patching_done
+
+    if _patching_done:
+        logger.debug("Patching already attempted. Skipping.")
+        return
+    _patching_done = True
+
+    from django_lazy_gdal import lazy_libgdal
+
+    django_libgdal_mod = "django.contrib.gis.gdal.libgdal"
+    lazy_libgdal_mod = "django_lazy_gdal.lazy_libgdal"
+
+    original_libgdal = None
+    original_module_dict: dict[str, Any] = {}
+    try:
+        if (
+            django_libgdal_mod in sys.modules
+            and sys.modules[django_libgdal_mod] is not lazy_libgdal
+        ):
+            logger.warning(
+                f"{django_libgdal_mod} was imported before django_lazy_gdal could monkeypatch it. "
+                "Call django_lazy_gdal.monkeypatch_libgdal() early in your settings module."
+            )
+            original_libgdal = sys.modules[django_libgdal_mod]
+        elif django_libgdal_mod not in sys.modules:
+            try:
+                original_libgdal = importlib.import_module(django_libgdal_mod)
+            except ImportError:
+                # This might happen if django.contrib.gis is partially available
+                # but libgdal itself fails to import. Patching might still be desired
+                # but attribute copying won't work.
+                logger.warning(
+                    f"Could not import original {django_libgdal_mod} for attribute copying.",
+                    exc_info=True,
+                )
+                pass
+
+        if original_libgdal:
+            original_module_dict = original_libgdal.__dict__.copy()
+
+    except Exception:
+        logger.exception(
+            f"Error trying to access original module {django_libgdal_mod} for attribute copying."
+        )
+        # Decide whether to proceed without attribute copying or bail out.
+        # Let's proceed but without attributes.
+        pass
+
+    sys.modules[django_libgdal_mod] = lazy_libgdal
+    logger.debug(f"Monkeypatched {django_libgdal_mod} to use {lazy_libgdal_mod}")
+
+    # Transfer attributes from the original module dict if we have it
+    if original_module_dict:
+        copied_attrs_count = 0
+        for key, value in original_module_dict.items():
+            # Only copy if the attribute doesn't already exist on the lazy module
+            if not hasattr(lazy_libgdal, key):
+                try:
+                    setattr(lazy_libgdal, key, value)
+                    copied_attrs_count += 1
+                except Exception:
+                    logger.warning(
+                        f"Failed to copy attribute '{key}' from original {django_libgdal_mod} to lazy module.",
+                        exc_info=True,
+                    )
+                    pass
+        logger.debug(
+            f"Transferred {copied_attrs_count} missing attributes from {django_libgdal_mod}."
+        )
+    else:
+        logger.debug(
+            f"Skipping attribute transfer as original module dict for {django_libgdal_mod} wasn't available."
+        )

src/django_lazy_gdal/apps.py

@@ -1,93 +1,11 @@
 from __future__ import annotations
 
-import importlib
-import logging
-import sys
 from typing import final
 
 from django.apps import AppConfig
 
-from ._typing import override
-
-logger = logging.getLogger(__name__)
-
 
 @final
 class DjangoLazyGDALConfig(AppConfig):
     name = "django_lazy_gdal"
     verbose_name = "Django Lazy GDAL"
-    _patching_done = False  # Sentinel flag
-
-    @override
-    def ready(self):
-        # Check if patching has already been done or attempted
-        if DjangoLazyGDALConfig._patching_done:
-            logger.debug("Patching already attempted. Skipping.")
-            return
-        DjangoLazyGDALConfig._patching_done = True
-
-        from django_lazy_gdal import lazy_libgdal
-
-        django_libgdal_mod = "django.contrib.gis.gdal.libgdal"
-        lazy_libgdal_mod = "django_lazy_gdal.lazy_libgdal"
-
-        original_libgdal = None
-        original_module_dict = {}
-        try:
-            if (
-                django_libgdal_mod in sys.modules
-                and sys.modules[django_libgdal_mod] is not lazy_libgdal
-            ):
-                logger.warning(
-                    f"{django_libgdal_mod} was imported before django_lazy_gdal could monkeypatch it. Ensure 'django_lazy_gdal' is placed early in INSTALLED_APPS."
-                )
-                original_libgdal = sys.modules[django_libgdal_mod]
-            elif django_libgdal_mod not in sys.modules:
-                try:
-                    original_libgdal = importlib.import_module(django_libgdal_mod)
-                except ImportError:
-                    # This might happen if django.contrib.gis is partially available
-                    # but libgdal itself fails to import. Patching might still be desired
-                    # but attribute copying won't work.
-                    logger.warning(
-                        f"Could not import original {django_libgdal_mod} for attribute copying.",
-                        exc_info=True,
-                    )
-                    pass
-
-            if original_libgdal:
-                original_module_dict = original_libgdal.__dict__.copy()
-
-        except Exception:
-            logger.exception(
-                f"Error trying to access original module {django_libgdal_mod} for attribute copying."
-            )
-            # Decide whether to proceed without attribute copying or bail out.
-            # Let's proceed but without attributes.
-            pass
-
-        sys.modules[django_libgdal_mod] = lazy_libgdal
-        logger.info(f"Monkeypatched {django_libgdal_mod} to use {lazy_libgdal_mod}")
-
-        # Transfer attributes from the original module dict if we have it
-        if original_module_dict:
-            copied_attrs_count = 0
-            for key, value in original_module_dict.items():
-                # Only copy if the attribute doesn't already exist on the lazy module
-                if not hasattr(lazy_libgdal, key):
-                    try:
-                        setattr(lazy_libgdal, key, value)
-                        copied_attrs_count += 1
-                    except Exception:
-                        logger.warning(
-                            f"Failed to copy attribute '{key}' from original {django_libgdal_mod} to lazy module.",
-                            exc_info=True,
-                        )
-                        pass
-            logger.debug(
-                f"Transferred {copied_attrs_count} missing attributes from {django_libgdal_mod}."
-            )
-            # else:
-            logger.debug(
-                f"Skipping attribute transfer as original module dict for {django_libgdal_mod} wasn't available."
-            )