refactor: use import datetime as dt consistently

Replaces `from datetime import UTC, datetime, timedelta` with
`import datetime as dt` across src/, tests/, examples/, and docs so
datetime symbols are accessed via a single namespace.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: nficano

docs/guides/leases.md

@@ -39,9 +39,9 @@ handle = await client.submit(
 ## Absolute expiry timestamp
 
 ```python
-from datetime import datetime, timezone, timedelta
+import datetime as dt
 
-expiry = datetime.now(timezone.utc) + timedelta(minutes=5)
+expiry = dt.datetime.now(dt.UTC) + dt.timedelta(minutes=5)
 
 handle = await client.submit(
     agent="slow-agent",

examples/lease_expires_at/client.py

@@ -4,9 +4,9 @@
 
 import asyncio
 import contextlib
+import datetime as dt
 import os
 import sys
-from datetime import UTC, datetime, timedelta
 
 from arcp import ClientInfo, LeaseConstraints, LeaseExpiredError, WebSocketTransport
 from arcp.client import ARCPClient
@@ -25,7 +25,9 @@ async def main() -> int:
     async with contextlib.aclosing(client):
         transport = await WebSocketTransport.connect(URL)
         await client.connect(transport)
-        expires_at = (datetime.now(UTC) + timedelta(seconds=2)).isoformat().replace("+00:00", "Z")
+        expires_at = (
+            (dt.datetime.now(dt.UTC) + dt.timedelta(seconds=2)).isoformat().replace("+00:00", "Z")
+        )
         handle = await client.submit(
             agent="slow",
             lease_constraints=LeaseConstraints(expires_at=expires_at),

src/arcp/_client/dispatch.py

@@ -5,8 +5,8 @@
 from __future__ import annotations
 
 import asyncio
+import datetime as dt
 from collections.abc import Awaitable, Callable
-from datetime import UTC, datetime
 from typing import TYPE_CHECKING, Any
 
 from .._envelope import Envelope
@@ -30,7 +30,7 @@
 
 
 def _now_iso() -> str:
-    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
+    return dt.datetime.now(dt.UTC).isoformat().replace("+00:00", "Z")
 
 
 Handler = Callable[[Envelope], Awaitable[None]]

src/arcp/_client/ops.py

@@ -6,7 +6,7 @@
 
 import asyncio
 import contextlib
-from datetime import UTC, datetime
+import datetime as dt
 from typing import TYPE_CHECKING, Any
 
 from .._envelope import Envelope
@@ -36,7 +36,7 @@
 
 
 def _now_iso() -> str:
-    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
+    return dt.datetime.now(dt.UTC).isoformat().replace("+00:00", "Z")
 
 
 def _require_transport(client: ARCPClient) -> Transport:

src/arcp/_messages/execution.py

@@ -2,8 +2,8 @@
 
 from __future__ import annotations
 
+import datetime as dt
 import re
-from datetime import UTC, datetime
 from decimal import Decimal, InvalidOperation
 from typing import Any, Literal
 
@@ -73,19 +73,19 @@ def format_budget_amount(currency: str, value: Decimal) -> str:
 """A lease maps capability namespace to a list of glob patterns."""
 
 
-def _ensure_utc_iso8601(value: str) -> datetime:
+def _ensure_utc_iso8601(value: str) -> dt.datetime:
     """Parse a strict UTC ISO 8601 timestamp (`Z` or `+00:00` only).
 
     Python 3.11+ `datetime.fromisoformat` accepts a trailing `Z` natively,
     so no `Z` → `+00:00` rewrite is required.
     """
     try:
-        dt = datetime.fromisoformat(value)
+        parsed = dt.datetime.fromisoformat(value)
     except ValueError as e:
         raise ValueError(f"invalid ISO 8601 timestamp: {value!r}") from e
-    if dt.tzinfo is None or dt.utcoffset() != UTC.utcoffset(dt):
+    if parsed.tzinfo is None or parsed.utcoffset() != dt.UTC.utcoffset(parsed):
         raise ValueError(f"expires_at must be UTC: {value!r}")
-    return dt
+    return parsed
 
 
 class LeaseConstraints(BaseModel):

src/arcp/_runtime/_handler_list_jobs.py

@@ -4,7 +4,7 @@
 
 from __future__ import annotations
 
-from datetime import datetime
+import datetime as dt
 from typing import TYPE_CHECKING
 
 from .._envelope import Envelope
@@ -28,10 +28,10 @@ async def handle_list_jobs(runtime: ARCPRuntime, ctx: SessionContext, env: Envel
     body = SessionListJobsPayload.model_validate(env.payload)
     limit = body.limit or 100
     offset = int(body.cursor) if body.cursor and body.cursor.isdigit() else 0
-    created_after_dt: datetime | None = None
+    created_after_dt: dt.datetime | None = None
     if body.filter is not None and body.filter.created_after:
         try:
-            created_after_dt = datetime.fromisoformat(body.filter.created_after)
+            created_after_dt = dt.datetime.fromisoformat(body.filter.created_after)
         except ValueError as exc:
             raise InvalidRequestError(
                 f"filter.created_after is not a valid ISO 8601 timestamp: "
@@ -56,7 +56,7 @@ def _filter_jobs(
     ctx: SessionContext,
     body: SessionListJobsPayload,
     auth_cls: type[AuthorizationContext],
-    created_after_dt: datetime | None,
+    created_after_dt: dt.datetime | None,
 ) -> list[Job]:
     # PLR0913: passes the pre-parsed created_after to avoid re-parsing
     # the ISO string for every job in the loop.
@@ -73,7 +73,7 @@ def _filter_jobs(
 
 
 def _matches_filter(
-    job: Job, body: SessionListJobsPayload, created_after_dt: datetime | None
+    job: Job, body: SessionListJobsPayload, created_after_dt: dt.datetime | None
 ) -> bool:
     if body.filter is None:
         return True

src/arcp/_runtime/_handlers.py

@@ -6,7 +6,7 @@
 
 import asyncio
 import contextlib
-from datetime import UTC, datetime
+import datetime as dt
 from typing import TYPE_CHECKING
 
 from .._envelope import Envelope
@@ -50,7 +50,7 @@
 
 
 def _now_iso() -> str:
-    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
+    return dt.datetime.now(dt.UTC).isoformat().replace("+00:00", "Z")
 
 
 async def handle_ping(_runtime: ARCPRuntime, ctx: SessionContext, env: Envelope) -> None:

src/arcp/_runtime/_handshake.py

@@ -5,8 +5,8 @@
 from __future__ import annotations
 
 import asyncio
+import datetime as dt
 import hmac
-from datetime import UTC, datetime
 from typing import TYPE_CHECKING, Any
 
 from .._envelope import Envelope
@@ -26,7 +26,7 @@
 
 
 def _now_iso() -> str:
-    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
+    return dt.datetime.now(dt.UTC).isoformat().replace("+00:00", "Z")
 
 
 async def perform_handshake(runtime: ARCPRuntime, transport: Any) -> SessionContext:
@@ -104,7 +104,7 @@ async def _perform_resume(  # noqa: PLR0913
             runtime.heartbeat_interval_sec if "heartbeat" in negotiated else None
         ),
         resume_window_sec=runtime.resume_window_sec,
-        accepted_at=datetime.now(UTC),
+        accepted_at=dt.datetime.now(dt.UTC),
     )
     send_queue: asyncio.Queue[Envelope | None] = asyncio.Queue()
     ctx = SessionContext(

src/arcp/_runtime/_job_runner.py

@@ -5,7 +5,7 @@
 from __future__ import annotations
 
 import asyncio
-from datetime import UTC, datetime
+import datetime as dt
 from typing import TYPE_CHECKING, Any
 
 from .._errors import ARCPError, InternalError, LeaseExpiredError
@@ -19,7 +19,7 @@
 
 
 def _now_iso() -> str:
-    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
+    return dt.datetime.now(dt.UTC).isoformat().replace("+00:00", "Z")
 
 
 async def run_job(
@@ -181,7 +181,7 @@ async def _revoke_with_retry(runtime: ARCPRuntime, credential_id: str) -> bool:
 
 async def _lease_watchdog(runtime: ARCPRuntime, job: Job, expires_at_iso: str) -> None:
     expiry = _parse_iso_utc(expires_at_iso)
-    delay = (expiry - datetime.now(UTC)).total_seconds()
+    delay = (expiry - dt.datetime.now(dt.UTC)).total_seconds()
     if delay > 0:
         try:
             await asyncio.sleep(delay)

src/arcp/_runtime/job.py

@@ -3,9 +3,9 @@
 from __future__ import annotations
 
 import asyncio
+import datetime as dt
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field, replace
-from datetime import UTC, datetime
 from decimal import Decimal, InvalidOperation
 from typing import TYPE_CHECKING, Any, Literal
 
@@ -36,7 +36,7 @@
 
 
 def _now_iso() -> str:
-    return datetime.now(UTC).isoformat().replace("+00:00", "Z")
+    return dt.datetime.now(dt.UTC).isoformat().replace("+00:00", "Z")
 
 
 @dataclass
@@ -59,7 +59,7 @@ class Job:
     state: JobStateName = "pending"
     chunked_result_started: bool = False
     inline_result_emitted: bool = False
-    submitted_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    submitted_at: dt.datetime = field(default_factory=lambda: dt.datetime.now(dt.UTC))
     idempotency_key: str | None = None
     # Wire dict of the most-recent terminal envelope (job.result / job.error)
     # this job emitted; used by the idempotency store to replay terminals on
@@ -302,7 +302,7 @@ def authorize(
         target: str,
         *,
         cost: dict[str, Decimal] | None = None,
-        now: datetime | None = None,
+        now: dt.datetime | None = None,
     ) -> None:
         validate_lease_op(
             self.lease,
@@ -311,7 +311,7 @@ def authorize(
             budget=self.job.budget if "cost.budget" in self.lease else None,
         )
 
-    def authorize_model(self, model_id: str, *, now: datetime | None = None) -> None:
+    def authorize_model(self, model_id: str, *, now: dt.datetime | None = None) -> None:
         """Authorize an upstream model id against the job's `model.use` lease."""
         validate_lease_op(
             self.lease,