Address review gaps: docs, tests, and docstring for DIGEST-MD5 auth

- Document that hive.kerberos-service-name applies to both KERBEROS and DIGEST-MD5
- Add precedence note for hive.metastore.authentication vs legacy boolean
- Add test for empty-string auth mechanism raising HiveAuthError
- Add integration test for KERBEROS via hive.metastore.authentication config
- Expand HiveAuthError docstring to cover token file errors

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ShreyeshArangath

mkdocs/docs/configuration.md

@@ -683,12 +683,14 @@ catalog:
 |------------------------------| ------- | ------------------------------------ |
 | hive.hive2-compatible        | true    | Using Hive 2.x compatibility mode    |
 | hive.kerberos-authentication | true    | Using authentication via Kerberos    |
-| hive.kerberos-service-name   | hive    | Kerberos service name (default hive) |
+| hive.kerberos-service-name   | hive    | SASL service name used for both KERBEROS and DIGEST-MD5 auth (default hive) |
 | ugi                 | t-1234:secret                    | Hadoop UGI for Hive client.                                                                        |
 | hive.metastore.authentication | DIGEST-MD5 | Auth mechanism: `NONE` (default), `KERBEROS`, or `DIGEST-MD5` |
 
 When using DIGEST-MD5 authentication, PyIceberg reads a Hive delegation token from the file pointed to by the `$HADOOP_TOKEN_FILE_LOCATION` environment variable. This is the standard mechanism used in secure Hadoop environments where delegation tokens are distributed to jobs. Install PyIceberg with `pip install "pyiceberg[hive]"` to get the required `pure-sasl` dependency.
 
+Note: `hive.metastore.authentication` takes precedence over the legacy `hive.kerberos-authentication` boolean. New deployments should prefer `hive.metastore.authentication`.
+
 When using Hive 2.x, make sure to set the compatibility flag:
 
 ```yaml

pyiceberg/exceptions.py

@@ -133,4 +133,4 @@ class ValidationException(Exception):
 
 
 class HiveAuthError(Exception):
-    """Raised when Hive Metastore authentication fails."""
+    """Raised when Hive Metastore authentication fails or the delegation token file is missing or malformed."""

tests/catalog/test_hive.py

@@ -1466,6 +1466,25 @@ def test_auth_mechanism_unknown_raises() -> None:
         _HiveClient(uri="thrift://localhost:9083", auth_mechanism="PLAIN")
 
 
+def test_auth_mechanism_empty_string_raises() -> None:
+    """Empty string auth mechanism should raise HiveAuthError."""
+    from pyiceberg.exceptions import HiveAuthError
+
+    with pytest.raises(HiveAuthError, match="Unknown auth mechanism.*''"):
+        _HiveClient(uri="thrift://localhost:9083", auth_mechanism="")
+
+
+def test_create_hive_client_passes_kerberos_via_config(monkeypatch: pytest.MonkeyPatch) -> None:
+    """_create_hive_client passes hive.metastore.authentication=KERBEROS to _HiveClient."""
+    monkeypatch.setattr(TTransport.TSaslClientTransport, "__init__", lambda *a, **kw: None)
+    properties = {
+        "uri": "thrift://localhost:9083",
+        HIVE_METASTORE_AUTH: "KERBEROS",
+    }
+    client = HiveCatalog._create_hive_client(properties)
+    assert client._auth_mechanism == "KERBEROS"
+
+
 def test_auth_mechanism_case_insensitive(monkeypatch: pytest.MonkeyPatch) -> None:
     """Auth mechanism should be case-insensitive."""
     monkeypatch.setattr("pyiceberg.catalog.hive.read_hive_delegation_token", _fake_read_token)