refactor(auth): rename PAT credential to pat

Rename the PAT-credential parameter/attribute from access_token to pat.
The env var was already QODER_PAT. Vault MCP OAuth access_token params are
unaffected.

Author: moonyue-w

README.md

@@ -54,7 +54,7 @@ Explicit arguments take precedence over environment variables. The clients never
 
 ```python
 client = Forward(
-    access_token="your-access-token",
+    pat="your-access-token",
     base_url="https://api.qoder.com.cn/api/v1/forward",
     timeout=30.0,
     max_retries=2,
@@ -358,7 +358,7 @@ For tokens that expire, pass a credential provider instead of a static token. It
 client = Forward(credential=my_credential)
 ```
 
-A static `access_token` takes precedence over a provider, and an explicit `Authorization` header takes precedence over both.
+A static `pat` takes precedence over a provider, and an explicit `Authorization` header takes precedence over both.
 
 ## Versioning
 

examples/common/live.py

@@ -56,7 +56,7 @@ def read_env(path: str | Path) -> dict[str, str]:
 @dataclass
 class Config:
     mode: str
-    access_token: str = field(repr=False)
+    pat: str = field(repr=False)
     base_url: str = ""
     model: str = ""
     timeout: float = 300
@@ -89,7 +89,7 @@ def load(cls, mode: str, *, env_file: str = ".env.live", region: str | None = No
         return cls(mode, token, str(url), values.get(prefix + "MODEL", ""), timeout)
 
     def client_options(self) -> dict[str, Any]:
-        return dict(access_token=self.access_token, base_url=self.base_url, max_retries=0, timeout=30)
+        return dict(pat=self.pat, base_url=self.base_url, max_retries=0, timeout=30)
 
 
 def safe_error(error: BaseException, token: str = "") -> str:
@@ -163,7 +163,7 @@ def cleanup(self) -> None:
             try:
                 action()
             except Exception as error:
-                failures.append(f"{kind} {resource_id}: {safe_error(error, self.config.access_token)}")
+                failures.append(f"{kind} {resource_id}: {safe_error(error, self.config.pat)}")
         self.cleanups.clear()
         if failures:
             raise RuntimeError("Cleanup failed:\n" + "\n".join(failures))
@@ -314,9 +314,9 @@ def run_cli(mode: str, client_type: Any, scenarios: dict[str, Callable[[Any, Run
                     try:
                         context.cleanup()
                     except Exception as error:
-                        errors.append(safe_error(error, config.access_token))
+                        errors.append(safe_error(error, config.pat))
         except Exception as error:
-            errors.insert(0, safe_error(error, config.access_token))
+            errors.insert(0, safe_error(error, config.pat))
         results.append({"scenario": scenario, "passed": not errors, "outputs": context.outputs, "errors": errors})
         if args.output == "text":
             print(f"{scenario}: {'FAIL' if errors else 'PASS'}")

src/qca/common/_base_client.py

@@ -54,7 +54,7 @@ class BaseClient:
     def _configure(
         self,
         *,
-        access_token: str | None,
+        pat: str | None,
         base_url: str | httpx.URL | None,
         timeout: float | httpx.Timeout | None,
         max_retries: int,
@@ -64,7 +64,7 @@ def _configure(
     ) -> None:
         if not isinstance(max_retries, int) or isinstance(max_retries, bool) or max_retries < 0:
             raise ValueError("max_retries must be a non-negative integer")
-        self.access_token = access_token if access_token is not None else os.environ.get("QODER_PAT")
+        self.pat = pat if pat is not None else os.environ.get("QODER_PAT")
         self.credential = credential
         self.base_url = httpx.URL(base_url or os.environ.get(self._base_url_env) or self._default_base_url)
         if self.base_url.scheme not in ("http", "https") or not self.base_url.host or self.base_url.userinfo:
@@ -80,7 +80,7 @@ def _configure(
 
     def _copy(self, *, raw: bool = False, streaming: bool = False, **overrides: Any) -> Self:
         options = dict(
-            access_token=self.access_token,
+            pat=self.pat,
             base_url=self.base_url,
             timeout=self.timeout,
             max_retries=self.max_retries,
@@ -98,16 +98,14 @@ def _copy(self, *, raw: bool = False, streaming: bool = False, **overrides: Any)
     def with_options(
         self,
         *,
-        access_token: str | NotGiven = NOT_GIVEN,
+        pat: str | NotGiven = NOT_GIVEN,
         base_url: str | httpx.URL | NotGiven = NOT_GIVEN,
         timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
         max_retries: int | NotGiven = NOT_GIVEN,
         default_headers: Mapping[str, str] | NotGiven = NOT_GIVEN,
         default_query: Mapping[str, Any] | NotGiven = NOT_GIVEN,
     ) -> Self:
-        values: dict[str, Any] = dict(
-            access_token=access_token, base_url=base_url, timeout=timeout, max_retries=max_retries
-        )
+        values: dict[str, Any] = dict(pat=pat, base_url=base_url, timeout=timeout, max_retries=max_retries)
         if not isinstance(default_headers, NotGiven):
             values["default_headers"] = {**self.default_headers, **default_headers}
         if not isinstance(default_query, NotGiven):
@@ -243,7 +241,7 @@ class SyncAPIClient(BaseClient):
     def __init__(
         self,
         *,
-        access_token: str | None = None,
+        pat: str | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: float | httpx.Timeout | None = DEFAULT_TIMEOUT,
         max_retries: int = 2,
@@ -253,7 +251,7 @@ def __init__(
         credential: Credential | None = None,
     ) -> None:
         self._configure(
-            access_token=access_token,
+            pat=pat,
             base_url=base_url,
             timeout=timeout,
             max_retries=max_retries,
@@ -270,12 +268,7 @@ def _send(self, request: httpx.Request, *, storage: bool = False) -> httpx.Respo
         for attempt in range(self.max_retries + 1):
             if track_retries and attempt:
                 request.headers["X-Qoder-Retry-Count"] = str(attempt)
-            if (
-                not storage
-                and self.credential
-                and not self.access_token
-                and "Authorization" not in self.default_headers
-            ):
+            if not storage and self.credential and not self.pat and "Authorization" not in self.default_headers:
                 # Dynamic credentials can rotate between retries. Explicit request
                 # headers still take priority and are marked by request().
                 if not request.extensions.get("qca_explicit_auth"):
@@ -315,7 +308,7 @@ def request(
         download_link: bool = False,
         file_fields: list[str] | None = None,
     ) -> Any:
-        args = self._request_args(method, path, options, self.access_token, file_fields)
+        args = self._request_args(method, path, options, self.pat, file_fields)
         if stream:
             args["headers"]["Accept"] = "text/event-stream"
         request = self._client.build_request(**args)
@@ -361,7 +354,7 @@ class AsyncAPIClient(BaseClient):
     def __init__(
         self,
         *,
-        access_token: str | None = None,
+        pat: str | None = None,
         base_url: str | httpx.URL | None = None,
         timeout: float | httpx.Timeout | None = DEFAULT_TIMEOUT,
         max_retries: int = 2,
@@ -371,7 +364,7 @@ def __init__(
         credential: Credential | AsyncCredential | None = None,
     ) -> None:
         self._configure(
-            access_token=access_token,
+            pat=pat,
             base_url=base_url,
             timeout=timeout,
             max_retries=max_retries,
@@ -388,12 +381,7 @@ async def _send(self, request: httpx.Request, *, storage: bool = False) -> httpx
         for attempt in range(self.max_retries + 1):
             if track_retries and attempt:
                 request.headers["X-Qoder-Retry-Count"] = str(attempt)
-            if (
-                not storage
-                and self.credential
-                and not self.access_token
-                and not request.extensions.get("qca_explicit_auth")
-            ):
+            if not storage and self.credential and not self.pat and not request.extensions.get("qca_explicit_auth"):
                 token = self.credential.get_token()
                 if inspect.isawaitable(token):
                     token = await token
@@ -436,10 +424,10 @@ async def request(
         if file_fields:
             # Reading local file objects should not block the event loop.
             args = await anyio.to_thread.run_sync(
-                lambda: self._request_args(method, path, options, self.access_token, file_fields)
+                lambda: self._request_args(method, path, options, self.pat, file_fields)
             )
         else:
-            args = self._request_args(method, path, options, self.access_token, None)
+            args = self._request_args(method, path, options, self.pat, None)
         if stream:
             args["headers"]["Accept"] = "text/event-stream"
         request = self._client.build_request(**args)

tests/_surface.py

@@ -155,7 +155,7 @@ def _endpoint(mode: str, attribute: str, function: Any) -> Endpoint:
 def endpoints() -> list[Endpoint]:
     found = []
     for mode in ("forward", "managed"):
-        client = CLIENTS[mode, False](access_token=TOKEN)
+        client = CLIENTS[mode, False](pat=TOKEN)
         found.extend(_endpoint(mode, attribute, function) for attribute, function in _methods(client))
         client.close()
     return sorted(found, key=lambda endpoint: endpoint.id)
@@ -197,7 +197,7 @@ def client_for(endpoint: Endpoint, async_: bool, handle: Callable[[httpx.Request
     transport = httpx.MockTransport(handle)
     http_client = httpx.AsyncClient(transport=transport) if async_ else httpx.Client(transport=transport)
     return CLIENTS[endpoint.mode, async_](
-        access_token=TOKEN,
+        pat=TOKEN,
         base_url=f"{BASE_URL}/{endpoint.mode}",
         max_retries=0,
         http_client=http_client,
@@ -207,7 +207,7 @@ def client_for(endpoint: Endpoint, async_: bool, handle: Callable[[httpx.Request
 
 def plain_client(mode: str, async_: bool) -> Any:
     """A client for tests that only introspect the resource tree."""
-    return CLIENTS[mode, async_](access_token=TOKEN)
+    return CLIENTS[mode, async_](pat=TOKEN)
 
 
 async def call(endpoint: Endpoint, client: Any, *, raw: bool = False, **overrides: Any) -> Any:

tests/test_client.py

@@ -35,7 +35,7 @@
 
 def make_client(handler, cls=Forward, **kwargs):
     return cls(
-        access_token="test-token",
+        pat="test-token",
         base_url="https://api.test/prefix/",
         http_client=httpx.Client(transport=httpx.MockTransport(handler)),
         **kwargs,
@@ -49,10 +49,10 @@ def test_environment_defaults_and_explicit_precedence(monkeypatch, cls, env, suf
     monkeypatch.setenv("QODER_PAT", "from-env")
     monkeypatch.setenv(env, f"https://configured.test/api/v1/{suffix}")
     with cls() as client:
-        assert client.access_token == "from-env"
+        assert client.pat == "from-env"
         assert str(client.base_url) == f"https://configured.test/api/v1/{suffix}/"
-    with cls(access_token="explicit", base_url="https://explicit.test/root") as client:
-        assert client.access_token == "explicit"
+    with cls(pat="explicit", base_url="https://explicit.test/root") as client:
+        assert client.pat == "explicit"
         assert str(client.base_url) == "https://explicit.test/root/"
 
 
@@ -383,7 +383,7 @@ def handle(request):
     http = httpx.Client(
         transport=httpx.MockTransport(handle), headers={"x-sensitive": "secret"}, cookies={"session": "cookie"}
     )
-    with Managed(access_token="api-token", base_url="https://api.test/cloud", http_client=http) as client:
+    with Managed(pat="api-token", base_url="https://api.test/cloud", http_client=http) as client:
         response = client.files.download("file", workspace_id="workspace")
         response.write_to_file(tmp_path / "download.txt")
         assert response.http_response.is_closed
@@ -439,7 +439,7 @@ async def handle(request):
         return httpx.Response(200, json={"url": "https://storage.test/asset"})
 
     async with AsyncManaged(
-        access_token="secret", http_client=httpx.AsyncClient(transport=httpx.MockTransport(handle))
+        pat="secret", http_client=httpx.AsyncClient(transport=httpx.MockTransport(handle))
     ) as client:
         item = await client.files.upload(file=("file.txt", b"hello"))
         result = await client.files.download(item.id)
@@ -533,7 +533,7 @@ def handle(request):
         calls.append(request)
         return httpx.Response(status, json={"error": {"message": "retry"}}, headers={"retry-after-ms": "25"})
 
-    async with cls(access_token="test", http_client=httpx.AsyncClient(transport=httpx.MockTransport(handle))) as client:
+    async with cls(pat="test", http_client=httpx.AsyncClient(transport=httpx.MockTransport(handle))) as client:
         with pytest.raises(APIStatusError):
             if verb == "GET":
                 await client.models.list()
@@ -558,7 +558,7 @@ def handle(request):
         return httpx.Response(500, json={})
 
     transport = httpx.MockTransport(handle)
-    async with AsyncForward(access_token="test", http_client=httpx.AsyncClient(transport=transport)) as client:
+    async with AsyncForward(pat="test", http_client=httpx.AsyncClient(transport=transport)) as client:
         with pytest.raises(APIStatusError):
             await client.models.list()
     assert counts == ["0", "1", "2"]

tests/test_examples.py

@@ -327,10 +327,10 @@ def test_config_file_is_data_and_environment_wins(tmp_path, monkeypatch):
     monkeypatch.setenv("QODER_FORWARD_PAT", "env-token")
     monkeypatch.delenv("QODER_FORWARD_BASE_URL", raising=False)
     config = Config.load("forward", env_file=str(path))
-    assert config.access_token == "env-token"
+    assert config.pat == "env-token"
     assert config.model == "ultimate"
     assert "env-token" not in repr(config)
-    assert "env-token" not in safe_error(ValueError("env-token"), config.access_token)
+    assert "env-token" not in safe_error(ValueError("env-token"), config.pat)
 
 
 def test_choose_model_rejects_disabled_preference():
@@ -350,7 +350,7 @@ def test_single_scenario_cli_defaults_to_that_scenario_and_cleans_up(fails, monk
     monkeypatch.setattr(Config, "load", lambda *args, **kwargs: config)
     monkeypatch.setattr(sys, "argv", ["examples.forward.memory", "--output", "json"])
     http_client = httpx.Client(transport=httpx.MockTransport(lambda request: httpx.Response(200)))
-    client = Forward(access_token=config.access_token, http_client=http_client)
+    client = Forward(pat=config.pat, http_client=http_client)
     calls = []
 
     def memory(client, context):
@@ -476,7 +476,7 @@ def test_status_error_shows_server_reason_and_redacts_token_and_signed_url():
     from qca import BadRequestError
 
     with Forward(
-        access_token="test-token",
+        pat="test-token",
         base_url="https://api.test/api/v1/forward",
         http_client=httpx.Client(
             transport=httpx.MockTransport(

tests/test_resource_surface.py

@@ -175,7 +175,7 @@ async def test_resource_tree_is_built_once_and_reused(mode, async_):
 
 
 def test_unknown_resource_attributes_fail_loudly():
-    with Forward(access_token=TOKEN, http_client=httpx.Client()) as client:
+    with Forward(pat=TOKEN, http_client=httpx.Client()) as client:
         with pytest.raises(AttributeError):
             client.sessions.no_such_method
         with pytest.raises(AttributeError):