fix: support env-var auth config for REST catalog (JSON string decode + flat properties)

[GayathriSrividya]

Summary

Fixes #3422.

This PR implements the fix designed by @kevinjqliu in the issue comment.

RestCatalog._create_session() expected auth to be a dict, but values loaded from environment variables always arrive as strings. This caused auth initialization to fail silently or with a confusing AttributeError for all pluggable auth types (basic, oauth2, google, entra, custom) when configured via PYICEBERG_CATALOG__<NAME>__AUTH.

Fixes

Implementation follows the tolerant auth parsing order suggested by @kevinjqliu:

1. JSON string decode (primary fix)

If the auth property value is a str, JSON-parse it before processing.
This unblocks:

export PYICEBERG_CATALOG__REST__AUTH='{"type":"oauth2", "oauth2":{"client_id":"id","client_secret":"secret","token_url":"https://auth.example/token"}}'

2. Flat env-var property support (alternative fix)

Supports the canonical PyIceberg env-var style — no JSON blob required, no quoting/escaping issues:

export PYICEBERG_CATALOG__REST__AUTH__TYPE=oauth2
export PYICEBERG_CATALOG__REST__AUTH__OAUTH2__CLIENT_ID=id
export PYICEBERG_CATALOG__REST__AUTH__OAUTH2__CLIENT_SECRET=secret
export PYICEBERG_CATALOG__REST__AUTH__OAUTH2__TOKEN_URL=https://auth.example/token

The env-var parser maps these to flat properties (auth.type, auth.oauth2.client-id, etc.). _create_session now checks for auth.type when the auth dict is absent, builds the config dict from the flat auth.* properties, and converts kebab-case keys to snake_case to match AuthManager constructor parameters.

Tests

Five new regression tests added to tests/catalog/test_rest.py (covering the test cases specified by @kevinjqliu):

Test	What it covers
test_rest_catalog_with_basic_auth_as_json_string	JSON string → Basic auth
test_rest_catalog_with_oauth2_auth_as_json_string	JSON string → OAuth2 auth
test_rest_catalog_with_invalid_json_auth_string	Invalid JSON → descriptive ValueError
test_rest_catalog_with_basic_auth_flat_properties	Flat auth.* props → Basic auth
test_rest_catalog_with_oauth2_auth_flat_properties	Flat auth.* props → OAuth2 auth

All 13 test_rest_catalog_with_* tests pass; the 4 pre-existing failures (test_token_200, test_config_200, test_auth_header, etc.) are unrelated to this change and also fail on main.

[abnobdoss]

This looks good, just a few suggestions!

[rambleraptor]

Thanks for writing this up! I've run into similar issues before and I think this will be a huge help!

Can you run make lint and re-push?

[GayathriSrividya]

Thanks! I ran make lint locally and re-pushed the changes. CI is green now — please take another look when you have a chance.

[abnobdoss]

Thanks for the updates! I took another look and may be missing it, but I still only see the basic/simple OAuth2 test cases covered for flat auth.* env vars.

Could we also cover the typed flat-auth cases, like OAuth2 numeric fields and Google/Entra scopes?

[GayathriSrividya]

Thanks for the updates! I took another look and may be missing it, but I still only see the basic/simple OAuth2 test cases covered for flat auth.* env vars.

Could we also cover the typed flat-auth cases, like OAuth2 numeric fields and Google/Entra scopes?

Thanks, I added coverage for the typed flat auth.* cases you called out. The flat env-var path now coerces typed auth-manager kwargs before construction, and the tests now cover OAuth2 numeric fields (refresh_margin, expires_in) plus Google and Entra scopes as list[str]. I also reran the focused REST auth tests and make lint.

[rambleraptor]

This looks great! Thanks for the rounds of iteration on this.

[kevinjqliu]

Thank you for the PR. Im not sure if its a good idea to accept both JSON string and flattened properties. I think we should just pick one. My vote is the flattened properties, we dont really have other patterns of accepting JSON string as config.

Accepting both makes documentation confusing. and JSON string might contain other arbitrary key/value pairs

I would also like to keep changes to pyiceberg/catalog/rest/__init__.py to a minimum, seems like there are a lot of helper functions that might not be necessary. Hopefully dropping JSON string support will get rid of a lot of the changes. If we truly need to define helper methods, it might be better to add them to pyiceberg/catalog/rest/auth.py instead.