Change settings precedence so env vars override settings.py

Swap the loading order so environment variables are applied after
settings.py, following the 12-factor convention. Extract timezone
setup into _apply_timezone() so it runs after all settings are loaded.

Author: davegaeddert

plain/plain/runtime/README.md

@@ -60,7 +60,7 @@ Plain's built-in settings are defined in [`global_settings.py`](./global_setting
 
 ## Environment variables
 
-Type-annotated settings can be loaded from environment variables using a `PLAIN_` prefix.
+Type-annotated settings can be loaded from environment variables using a `PLAIN_` prefix. Environment variables take the highest precedence — they override values set in `settings.py`, so you can change behavior per deployment without editing code.
 
 For example, if you define a setting with a type annotation:
 

plain/plain/runtime/user_settings.py

@@ -74,10 +74,12 @@ def _setup(self) -> None:
 
         # Load default settings from installed packages
         self._load_default_settings(mod)
-        # Load environment settings
-        self._load_env_settings()
         # Load explicit settings from the settings module
         self._load_explicit_settings(mod)
+        # Load environment settings (last, so env vars override settings.py)
+        self._load_env_settings()
+        # Apply timezone after all settings are loaded
+        self._apply_timezone()
         # Check for any required settings that are missing
         self._check_required_settings()
         # Check for any collected errors
@@ -181,6 +183,7 @@ def _load_explicit_settings(self, settings_module: types.ModuleType) -> None:
                         f"Unknown setting '{setting}'. Custom settings must start with '{_CUSTOM_SETTINGS_PREFIX}'."
                     )
 
+    def _apply_timezone(self) -> None:
         if hasattr(time, "tzset") and self.TIME_ZONE:
             zoneinfo_root = Path("/usr/share/zoneinfo")
             zone_info_file = zoneinfo_root.joinpath(*self.TIME_ZONE.split("/"))

plain/tests/app/settings.py

@@ -8,4 +8,4 @@
 ]
 
 EXPLICIT_SETTING = "explicitly changed"
-ENV_OVERRIDDEN_SETTING = "explicitly overridden"
+EXPLICIT_OVERRIDDEN_SETTING = "explicit value"

plain/tests/app/test/default_settings.py

@@ -1,5 +1,5 @@
 DEFAULT_SETTING: str = "unchanged default"
 EXPLICIT_SETTING: str = "unchanged explicit"
 ENV_SETTING: int = 0
-ENV_OVERRIDDEN_SETTING: str = "unchanged env overridden"
+EXPLICIT_OVERRIDDEN_SETTING: str = "default value"
 NULLABLE_SETTING: int | None = None

plain/tests/conftest.py

@@ -3,5 +3,5 @@
 
 def pytest_configure(config):
     os.environ["PLAIN_ENV_SETTING"] = "1"
-    os.environ["PLAIN_ENV_OVERRIDDEN_SETTING"] = "env value"
+    os.environ["PLAIN_EXPLICIT_OVERRIDDEN_SETTING"] = "env value"
     os.environ["PLAIN_UNDEFINED_SETTING"] = "not used"

plain/tests/test_runtime.py

@@ -6,4 +6,4 @@ def test_user_settings():
     assert settings.DEFAULT_SETTING == "unchanged default"
     assert settings.EXPLICIT_SETTING == "explicitly changed"
     assert settings.ENV_SETTING == 1
-    assert settings.ENV_OVERRIDDEN_SETTING == "explicitly overridden"
+    assert settings.EXPLICIT_OVERRIDDEN_SETTING == "env value"