Load Env

1"""Discover .env-style files and import their keys into os.environ.
2
3Used by both:
4- scripts/publish_dataset.py (imported at runtime)
5- agent-observability/agent-observability-experiment-bootstrap/references/python/env_setup_template.py
6  (kept in sync as a verbatim copy — that copy is embedded into the
7  user's generated experiment file so the file runs standalone without
8  depending on this skill being installed)
9
10Discovery order (first hit per variable wins; shell env vars always
11override file-loaded values):
12
13  1. Any path in `extra` (typically the resolved --env-file argument)
14  2. <this-script-dir>/.env  and  .env.local
15  3. <cwd>/.env  and  .env.local
16  4. Parent-walk from cwd up to /  (stops at $HOME's parent)
17  5. ~/.datadog/credentials  (well-known Datadog convention)
18
19Never overwrites a value that is already in os.environ — that is the
20contract that lets users override anything by `export KEY=...` in
21their shell before running.
22"""
23from __future__ import annotations
24
25import os
26import pathlib
27
28
29def load_env_files(extra: list[str] | None = None) -> list[str]:
30    """Walk discovery locations and return the absolute paths of files loaded."""
31    here = pathlib.Path(__file__).resolve().parent
32    cwd = pathlib.Path.cwd().resolve()
33    candidates: list[pathlib.Path] = []
34    for p in extra or []:
35        candidates.append(pathlib.Path(p).expanduser())
36    candidates += [
37        here / ".env",
38        here / ".env.local",
39        cwd / ".env",
40        cwd / ".env.local",
41    ]
42    p = cwd
43    while p != p.parent and p != pathlib.Path.home().parent:
44        candidates.append(p / ".env")
45        p = p.parent
46    candidates.append(pathlib.Path.home() / ".datadog" / "credentials")
47
48    loaded: list[str] = []
49    seen: set[pathlib.Path] = set()
50    for path in candidates:
51        try:
52            path = path.resolve()
53        except Exception:
54            continue
55        if path in seen or not path.is_file():
56            continue
57        seen.add(path)
58        try:
59            text = path.read_text()
60        except Exception:
61            continue
62        for line in text.splitlines():
63            line = line.strip()
64            if not line or line.startswith("#") or "=" not in line:
65                continue
66            if line.startswith("export "):
67                line = line[len("export "):]
68            k, _, v = line.partition("=")
69            k = k.strip()
70            v = v.strip().strip('"').strip("'")
71            if k and k not in os.environ:  # shell wins over file
72                os.environ[k] = v
73        loaded.append(str(path))
74    return loaded