Extract _resolve_profile to simplify config file loading (#1333)

## Summary

Follow-up to #1325 (default_profile support). Applies the same
refactoring we did in the Go SDK to improve readability and error
messages.

**Before:** `_known_file_config_loader` used two booleans
(`has_explicit_profile`, `has_default_profile_setting`) to track where
the profile came from. The interaction between them encoded a three-way
state (explicit, from settings, legacy fallback) that required careful
reading to verify correctness. `__settings__` handling was scattered
across three locations in the method.

**Now:** A `_resolve_profile` static method handles all resolution logic
and returns `(profile, is_fallback)`. The loader no longer needs to know
about `__settings__` internals. The two booleans collapse into a single
`is_fallback` flag.

### Changes

- Extract `_resolve_profile(requested_profile, ini_file)` as a static
method that resolves the profile name through three sources: explicit,
`[__settings__].default_profile`, or `[DEFAULT]` fallback.
- Simplify `_known_file_config_loader` to use the resolved result. No
more `has_explicit_profile` / `has_default_profile_setting` booleans.
- Improve error messages: using `__settings__` as a profile name (either
explicitly or via `default_profile`) now returns `"__settings__ is a
reserved section name and cannot be used as a profile"` instead of the
generic `"has no __settings__ profile configured"`.
- Fix flaky SCIM pagination integration test: the raw `GET
/scim/v2/Groups` was fetching the full result set just to read
`totalResults`, causing read timeouts on large workspaces. Now passes
`count=1` since SCIM always returns `totalResults` regardless of page
size.
- Fix pre-existing formatting issues in 3 test files (`test_auth.py`,
`test_config.py`, `test_core.py`) so the CI fmt check passes.

### Why this matters

The three sources for a profile name (explicit, settings-based, legacy
fallback) produce two distinct behaviors:

1. **Explicit and settings-based** both require the profile to exist
(error if missing) and record the active profile on `cfg.profile`.
2. **Legacy fallback** silently returns if `[DEFAULT]` doesn't exist
(unconfigured machine) and doesn't set `cfg.profile`.

A single `is_fallback` boolean captures this distinction. The previous
two-boolean approach worked correctly but required tracing through their
interactions to confirm that.

## Test plan

- All 8 existing `test_default_profile.py` tests pass (updated 2 tests
to match the improved error messages).
- No behavioral changes except the error message text for reserved
section name usage.

This pull request was AI-assisted by Isaac.

Author: simonfaltum

NEXT_CHANGELOG.md

@@ -12,5 +12,6 @@
 
 ### Internal Changes
 * Replace the async-disabling mechanism on token refresh failure with a 1-minute retry backoff. Previously, a single failed async refresh would disable proactive token renewal until the token expired. Now, the SDK waits a short cooldown period and retries, improving resilience to transient errors.
+* Extract `_resolve_profile` to simplify config file loading and improve `__settings__` error messages.
 
 ### API Changes

databricks/sdk/config.py

@@ -716,6 +716,37 @@ def _load_from_env(self):
         if found:
             logger.debug("Loaded from environment")
 
+    @staticmethod
+    def _resolve_profile(requested_profile, ini_file):
+        """Resolve which profile to load from the config file.
+
+        Returns (profile_name, is_fallback):
+          - If requested_profile is set explicitly, returns it with is_fallback=False.
+          - If [__settings__].default_profile is set, returns it with is_fallback=False.
+          - If [DEFAULT] has keys, returns "DEFAULT" with is_fallback=True.
+          - Otherwise returns (None, True) to signal no config is available.
+
+        Raises ValueError if the resolved profile is the reserved __settings__ section.
+        """
+        _SETTINGS_SECTION = "__settings__"
+
+        if requested_profile is not None:
+            if requested_profile == _SETTINGS_SECTION:
+                raise ValueError(f"{_SETTINGS_SECTION} is a reserved section name" " and cannot be used as a profile")
+            return requested_profile, False
+
+        settings = ini_file._sections.get(_SETTINGS_SECTION, {})
+        default_profile = settings.get("default_profile", "").strip()
+        if default_profile:
+            if default_profile == _SETTINGS_SECTION:
+                raise ValueError(f"{_SETTINGS_SECTION} is a reserved section name" " and cannot be used as a profile")
+            return default_profile, False
+
+        if ini_file.defaults():
+            return "DEFAULT", True
+
+        return None, True
+
     def _known_file_config_loader(self):
         if not self.profile and (self.is_any_auth_configured or self.host or self.azure_workspace_resource_id):
             # skip loading configuration file if there's any auth configured
@@ -730,31 +761,22 @@ def _known_file_config_loader(self):
             return
         ini_file = configparser.ConfigParser()
         ini_file.read(config_path)
-        profile = self.profile
-        has_explicit_profile = self.profile is not None
-        has_default_profile_setting = False
         # In Go SDK, we skip merging the profile with DEFAULT section, though Python's ConfigParser.items()
         # is returning profile key-value pairs _including those from DEFAULT_. This is not what we expect
         # from Unified Auth test suite at the moment. Hence, the private variable access.
         # See: https://docs.python.org/3/library/configparser.html#mapping-protocol-access
-        if not has_explicit_profile:
-            # Check [__settings__].default_profile before falling back to [DEFAULT].
-            settings = ini_file._sections.get("__settings__", {})
-            default_profile = settings.get("default_profile", "").strip()
-            if default_profile:
-                profile = default_profile
-                has_default_profile_setting = True
-            elif ini_file.defaults():
-                profile = "DEFAULT"
-            else:
-                logger.debug(f"{config_path} has no DEFAULT profile configured")
-                return
+        profile, is_fallback = self._resolve_profile(self.profile, ini_file)
+        if profile is None:
+            logger.debug(f"{config_path} has no DEFAULT profile configured")
+            return
         profiles = {name: values for name, values in ini_file._sections.items()}
-        # [__settings__] is not a profile; exclude it from the profile map.
         profiles.pop("__settings__", None)
         if ini_file.defaults():
             profiles["DEFAULT"] = ini_file.defaults()
         if profile not in profiles:
+            if is_fallback:
+                logger.debug(f"{config_path} has no {profile} profile configured")
+                return
             raise ValueError(f"resolve: {config_path} has no {profile} profile configured")
         raw_config = profiles[profile]
         logger.info(f"loading {profile} profile from {config_file}: {', '.join(raw_config.keys())}")
@@ -763,7 +785,7 @@ def _known_file_config_loader(self):
                 # don't overwrite a value previously set
                 continue
             self.__setattr__(k, v)
-        if has_default_profile_setting:
+        if not is_fallback:
             self.profile = profile
 
     def _validate(self):

tests/integration/test_iam.py

@@ -36,7 +36,8 @@ def test_scim_get_user_as_dict(w):
     ],
 )
 def test_workspace_users_list_pagination(w, path, call):
-    raw = w.api_client.do("GET", path)
+    # Use count=1 to avoid serializing the full result set just to read totalResults.
+    raw = w.api_client.do("GET", path, query={"count": 1})
     total = raw["totalResults"]
     all = call(w)
     found = len(list(all))
@@ -61,7 +62,8 @@ def test_workspace_users_list_pagination(w, path, call):
     ],
 )
 def test_account_users_list_pagination(a, path, call):
-    raw = a.api_client.do("GET", path.replace("%s", a.config.account_id))
+    # Use count=1 to avoid serializing the full result set just to read totalResults.
+    raw = a.api_client.do("GET", path.replace("%s", a.config.account_id), query={"count": 1})
     total = raw["totalResults"]
     all = call(a)
     found = len(list(all))

tests/test_default_profile.py

@@ -102,9 +102,9 @@ def test_settings_section_is_not_a_profile(tmp_path):
 token = dapiXYZ
 """,
     )
-    # Explicitly requesting __settings__ as a profile should fail,
-    # proving the SDK excludes it from the profile map.
-    with pytest.raises(ValueError, match="has no __settings__ profile configured"):
+    # Explicitly requesting __settings__ as a profile should fail with a
+    # clear "reserved section name" error, not a generic "no profile" error.
+    with pytest.raises(ValueError, match="__settings__ is a reserved section name"):
         Config(
             config_file=cfg_file,
             profile="__settings__",
@@ -113,7 +113,7 @@ def test_settings_section_is_not_a_profile(tmp_path):
 
 
 def test_default_profile_pointing_to_settings_section_is_rejected(tmp_path):
-    """default_profile = __settings__ should fail like any other non-profile target."""
+    """default_profile = __settings__ should fail with a reserved section name error."""
     cfg_file = _write_cfg(
         tmp_path,
         """\
@@ -125,7 +125,7 @@ def test_default_profile_pointing_to_settings_section_is_rejected(tmp_path):
 token = dapiXYZ
 """,
     )
-    with pytest.raises(ValueError, match="has no __settings__ profile configured"):
+    with pytest.raises(ValueError, match="__settings__ is a reserved section name"):
         Config(config_file=cfg_file, credentials_strategy=noop_credentials)