Di Region

1"""Region resolution for the dynamic-instrumentation host scripts.
2
3WHY THIS EXISTS
4``di_instrumentation.py`` (application-signals client) and ``di_snapshots.py``
5(CloudWatch Logs client) both need to pick an AWS region, and they must pick it
6the SAME way so a breakpoint created in one region and the snapshots later read
7for it land in the same region. Centralizing the policy here keeps the two
8host scripts from drifting apart.
9
10POLICY (mirrors boto3's own precedence, minus the profile region)
11    explicit --region flag  >  AWS_REGION  >  AWS_DEFAULT_REGION  >  us-east-1
12
13* ``AWS_PROFILE`` is honored for CREDENTIALS only (by the client builders); the
14  profile's configured region is deliberately ignored so the target region is
15  always explicit and overridable per invocation.
16* Both ``AWS_REGION`` and ``AWS_DEFAULT_REGION`` are consulted because boto3
17  itself honors both; reading only ``AWS_REGION`` would surprise a caller who
18  set ``AWS_DEFAULT_REGION`` instead.
19* The ``us-east-1`` fallback means a call never fails for lack of a region, but
20  callers are expected to pass ``--region`` or set the env var to target the
21  region their service actually runs in (see SKILL.md).
22
23The ``--region`` flag is a thin front-end: the host script sets
24``AWS_REGION`` from the flag before dispatch, so the existing env-driven client
25builders pick it up with no change to operation signatures.
26"""
27
28import os
29from typing import Optional
30
31DEFAULT_REGION = "us-east-1"
32
33
34def resolve_region(explicit: Optional[str] = None) -> str:
35    """Resolve the AWS region using the documented precedence.
36
37    Args:
38        explicit: A region passed directly (e.g. from a ``--region`` flag).
39            When falsy, environment variables and the default are consulted.
40
41    Returns:
42        ``explicit`` if provided, else ``AWS_REGION``, else
43        ``AWS_DEFAULT_REGION``, else ``us-east-1``.
44    """
45    if explicit:
46        return explicit
47    return os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION") or DEFAULT_REGION