Add use_paw_oauth to TM1Service for one-line PAW sign-in

[bdunleavy22]

Depends on #1494 (and through it #1488). Until those merge, this diff also shows their commits;
only the last commit is new here.

Open question: with use_paw_oauth, TM1Service can open a browser. It's strictly opt-in, and nothing
changes for existing connections, but it's a first for TM1py, so I'd value your view on whether that's acceptable
or whether you'd rather keep only the explicit PawOAuthSession route from #1494.

Summary

Sign in to PAW as a user, through the browser, with one extra kwarg:

with TM1Service(
    base_url="https://<paw-host>/api/v1/tm1/<database>",  # TM1 12: https://<paw-host>/api/<tenant>/v0/tm1/<database>
    use_paw_oauth=True,  # or "keyring" to sign in once across runs, or a TokenCache
    paw_client_id="<client id>",
    paw_client_secret=os.environ["PAW_CLIENT_SECRET"],
) as tm1:
    ...

 RestService.__init__
+  if use_paw_oauth
+    oauth = PawOAuthSession.from_base_url(base_url, paw_client_id, ...)   # /oauth2/* on base_url's host
+    oauth.login()                                                         # browser, or silent refresh
+    access_token = oauth.access_token                                     # callable from #1488
+    keep_authorization_header defaults to True                            # flag from #1488
   determine auth mode  -> ACCESS_TOKEN
   connect

TM1py/Services/RestService.py        # use_paw_oauth, paw_client_id, paw_client_secret, paw_redirect_uri
TM1py/Utils/PawOAuth.py              # PawOAuthSession.from_base_url, default redirect_uri
Tests/RestService_paw_oauth_test.py  # offline: endpoint derivation, wiring, cache choices, invalid combinations
docs/getting-started.md              # leads with use_paw_oauth; PawOAuthSession as the explicit alternative

paw_client_id is deliberately separate from application_client_id, which is a TM1 12 engine application client
for headless service-to-service sign-in. paw_redirect_uri defaults to http://127.0.0.1:8000/oauth/paw/callback.
use_paw_oauth accepts True/False and their config.ini spellings, "in_memory", "keyring", or a
TokenCache.

Evidence

Offline unit tests (Tests/RestService_paw_oauth_test.py, 10 tests with subtests); the browser sign-in is stubbed
and connect() is patched out:

base_url https://<env>.planning-analytics.cloud.ibm.com/api/v1/tm1/CONS        -> /oauth2/authorize, /oauth2/token on that host
base_url https://<region>.planninganalytics.saas.ibm.com/api/<t>/v0/tm1/<db>    -> /oauth2/authorize, /oauth2/token on that host
use_paw_oauth=True                    -> login() once, ACCESS_TOKEN mode, keep_authorization_header on, Bearer sent at session start
use_paw_oauth="keyring" / TokenCache  -> that cache is used
use_paw_oauth False/None/"False"/""   -> no sign-in, other auth modes unchanged
"memory", no paw_client_id, no base_url, unparseable base_url, also access_token -> ValueError, no sign-in

Against real instances with my own user (manual smoke test, not committed), using only
TM1Service(base_url=..., use_paw_oauth="keyring", paw_client_id=..., paw_client_secret=..., **connection_options),
with no access_token, OAuth URLs or keep_authorization_header passed:

	TM1 11.8 on IBM Cloud	TM1 12.5.9 PAaaS
OAuth endpoints derived from base_url match the client's real ones	✅	✅
Default redirect URI (http://127.0.0.1:8000/oauth/paw/callback)	✅	✅
Signed in silently from the keyring-cached refresh token, no browser	✅	✅
whoami after session start (header kept automatically)	✅	✅
Logout	✅	✅

The interactive path is the same PawOAuthSession.login() that #1494's smoke tests exercised with a real browser
sign-in on both instances.

Merge Danger

Door: two-way for behaviour, but adds public kwargs

Off by default and reverted cleanly. Once released, the use_paw_oauth / paw_* names are public API, so they're
worth settling in review.

Blast Radius: opt-in

Only TM1Service/RestService constructions with use_paw_oauth set are affected; the helper module isn't even
imported otherwise. With it on, TM1Service(...) blocks until the browser sign-in completes (up to 180 s), unless a
cached refresh token signs in silently. Token requests don't yet use TM1Service's verify or proxies settings.

🤖 Generated with Claude Code