sap-adt-cli 1.5.0__py3-none-any.whl

sap_adt/__init__.py

@@ -0,0 +1 @@
+"""sap-adt: SAP ADT REST API CLI and transport request collector."""

sap_adt/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m sap_adt` entry — equivalent to the `sap-adt` console script."""
+from sap_adt.cli import main
+
+if __name__ == "__main__":
+    main(prog_name="sap-adt")

sap_adt/adt/client.py

@@ -0,0 +1,185 @@
+from typing import Optional
+from urllib.parse import parse_qsl, urlencode, urlparse, urlunparse
+
+import requests
+import urllib3
+from requests.auth import HTTPBasicAuth
+
+from .. import log_redaction
+from ..config import SapConfig, get_config
+
+_session: Optional[requests.Session] = None
+_csrf_token: Optional[str] = None
+_session_cookies: Optional[dict] = None
+# Explicit connection override (transport collection, tests). When None the
+# client resolves the active profile on every request as before.
+_active_config: Optional[SapConfig] = None
+
+
+def set_config(config: Optional[SapConfig]) -> None:
+    """Use an explicit connection for subsequent requests (None = resolve)."""
+    global _active_config
+    _active_config = config
+
+
+def config_override() -> Optional[SapConfig]:
+    """Return the injected config (or None when none was injected)."""
+    return _active_config
+
+
+def active_config() -> SapConfig:
+    """Return the explicit override, or resolve the active profile/env."""
+    return _active_config if _active_config is not None else get_config()
+
+# Query parameters whose values must never appear in error messages.
+_SENSITIVE_QUERY_RE = ("token", "password", "passwd", "secret", "codepage",
+                       "lockhandle")
+_MAX_BODY_CHARS = 500
+
+
+class AdtHttpError(Exception):
+    """HTTP failure carrying only sanitized, safe-to-print information."""
+
+    def __init__(self, message: str, *, status: Optional[int] = None):
+        super().__init__(message)
+        self.status = status
+
+
+def _get_session() -> requests.Session:
+    global _session
+    if _session is None:
+        _session = requests.Session()
+    return _session
+
+
+def _safe_url(url: str) -> str:
+    """Strip sensitive query parameters before including a URL in any message."""
+    try:
+        parsed = urlparse(url)
+        kept = [(k, v) for k, v in parse_qsl(parsed.query)
+                if not any(s in k.lower() for s in _SENSITIVE_QUERY_RE)]
+        return urlunparse(parsed._replace(query=urlencode(kept)))
+    except ValueError:
+        return url
+
+
+def _redact(text, config: SapConfig) -> str:
+    return log_redaction.redact(text, secret=config.password, username=config.username)
+
+
+def _wrap_error(exc: Exception, config: SapConfig, method: str, url: str) -> AdtHttpError:
+    """Translate requests exceptions into sanitized AdtHttpError instances."""
+    safe_url = _safe_url(url)
+    if isinstance(exc, requests.HTTPError) and exc.response is not None:
+        response = exc.response
+        body = _redact(response.text or "", config)[:_MAX_BODY_CHARS]
+        return AdtHttpError(
+            f"HTTP {response.status_code} for {method} {safe_url}: {body}".rstrip(": "),
+            status=response.status_code,
+        )
+    message = _redact(str(exc), config)
+    return AdtHttpError(f"{type(exc).__name__} for {method} {safe_url}: {message}")
+
+
+def _request(config: SapConfig, method: str, url: str, **kwargs) -> requests.Response:
+    try:
+        return _get_session().request(method=method, url=url, **kwargs)
+    except requests.RequestException as e:
+        # Chain discarded ('from None'): a requests PreparedRequest repr in
+        # the chain carries the Authorization header.
+        raise _wrap_error(e, config, method, url) from None
+
+
+def _auth_headers(config: SapConfig) -> dict:
+    return {"X-SAP-Client": config.client}
+
+
+def _fetch_csrf_token(url: str, config: SapConfig,
+                      params: Optional[dict] = None) -> str:
+    global _session_cookies
+    resp = _request(
+        config,
+        "GET",
+        url,
+        auth=HTTPBasicAuth(config.username, config.password),
+        headers={**_auth_headers(config), "x-csrf-token": "fetch"},
+        params=params,
+        verify=config.verify_ssl,
+        timeout=30,
+    )
+    token = resp.headers.get("x-csrf-token")
+    if not token:
+        raise AdtHttpError("No CSRF token received from SAP server")
+    if resp.cookies:
+        _session_cookies = dict(resp.cookies)
+    return token
+
+
+def make_adt_request(
+    url: str,
+    method: str = "GET",
+    timeout: int = 30,
+    data=None,
+    params: Optional[dict] = None,
+    extra_headers: Optional[dict] = None,
+) -> requests.Response:
+    global _csrf_token, _session_cookies
+
+    config = active_config()
+    # Feed the live secret to the log filter so literal/Base64 leaks are
+    # scrubbed even from libraries that log raw objects.
+    log_redaction.set_secret(config.password, config.username)
+    headers = _auth_headers(config)
+    if extra_headers:
+        headers.update(extra_headers)
+
+    # Some gateways select/mandate the SAP client via the sap-client query
+    # parameter during Basic Auth login, so send it on every request -- the
+    # CSRF pre-flight, the business call, and the CSRF retry included. Copy
+    # the caller's dict (never mutate it) and let an explicit sap-client win.
+    request_params = dict(params or {})
+    request_params.setdefault("sap-client", config.client)
+
+    if not config.verify_ssl:
+        urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)
+
+    if method in ("POST", "PUT") and not _csrf_token:
+        _csrf_token = _fetch_csrf_token(url, config, request_params)
+
+    if method in ("POST", "PUT") and _csrf_token:
+        headers["x-csrf-token"] = _csrf_token
+
+    resp = _request(
+        config,
+        method,
+        url,
+        auth=HTTPBasicAuth(config.username, config.password),
+        headers=headers,
+        verify=config.verify_ssl,
+        timeout=timeout,
+        data=data,
+        params=request_params,
+        cookies=_session_cookies or {},
+    )
+
+    if resp.status_code == 403 and "CSRF" in (resp.text or ""):
+        _csrf_token = _fetch_csrf_token(url, config, request_params)
+        headers["x-csrf-token"] = _csrf_token
+        resp = _request(
+            config,
+            method,
+            url,
+            auth=HTTPBasicAuth(config.username, config.password),
+            headers=headers,
+            verify=config.verify_ssl,
+            timeout=timeout,
+            data=data,
+            params=request_params,
+            cookies=_session_cookies or {},
+        )
+
+    try:
+        resp.raise_for_status()
+    except requests.HTTPError as e:
+        raise _wrap_error(e, config, method, url) from None
+    return resp

sap_adt/adt/coverage.py

@@ -0,0 +1,163 @@
+"""Command coverage against the connected system's discovery document.
+
+Pure functions: given the parsed discovery ``collections`` and the
+``COMMAND_CAPABILITIES`` map (command -> discovery hrefs it depends on),
+split everything into three buckets. Local commands that do not talk to ADT
+(configure/profile/credentials/status) are intentionally absent from the map
+and counted separately by the CLI.
+"""
+from __future__ import annotations
+
+from collections import OrderedDict
+from typing import Iterable
+
+# Commands that mutate/read SAP via ADT and the discovery hrefs they need.
+# A command is "covered & available" when ANY listed href exists; a command
+# spans object types (write/activate) when one of its object resources does.
+_OO = ["/sap/bc/adt/oo/classes", "/sap/bc/adt/oo/interfaces"]
+_PROG = ["/sap/bc/adt/programs/programs", "/sap/bc/adt/programs/includes"]
+_FUGR = ["/sap/bc/adt/functions/groups"]
+_DDL = ["/sap/bc/adt/ddic/ddl/sources"]
+
+COMMAND_CAPABILITIES: "OrderedDict[str, list[str]]" = OrderedDict([
+    ("get-program", _PROG),
+    ("get-class", _OO),
+    ("get-function-group", _FUGR),
+    ("get-function", _FUGR),
+    ("get-include", ["/sap/bc/adt/programs/includes"]),
+    ("get-interface", ["/sap/bc/adt/oo/interfaces"]),
+    ("get-cds-view", _DDL),
+    ("get-type-group", ["/sap/bc/adt/ddic/typegroups"]),
+    ("get-table", ["/sap/bc/adt/ddic/tables"]),
+    ("get-structure", ["/sap/bc/adt/ddic/structures"]),
+    ("get-type-info",
+     ["/sap/bc/adt/ddic/domains", "/sap/bc/adt/ddic/dataelements"]),
+    ("get-transaction",
+     ["/sap/bc/adt/repository/informationsystem/objectproperties/values"]),
+    ("search-object",
+     ["/sap/bc/adt/repository/informationsystem/search"]),
+    ("get-package", ["/sap/bc/adt/repository/nodestructure"]),
+    ("where-used",
+     ["/sap/bc/adt/repository/informationsystem/usageReferences"]),
+    ("syntax-check", ["/sap/bc/adt/checkruns"]),
+    ("run-unit-test", ["/sap/bc/adt/abapunit/testruns"]),
+    ("run-atc", ["/sap/bc/adt/atc/runs", "/sap/bc/adt/atc/worklists"]),
+    ("run-sql", ["/sap/bc/adt/datapreview/freestyle"]),
+    ("list-transports", ["/sap/bc/adt/cts/transportrequests"]),
+    ("create-transport", ["/sap/bc/adt/cts/transports"]),
+    ("release-transport", ["/sap/bc/adt/cts/transports"]),
+    ("write-source", _OO + _PROG + _FUGR),
+    ("activate", _OO + _PROG + _FUGR + _DDL +
+     ["/sap/bc/adt/activation", "/sap/bc/adt/activation/runs"]),
+])
+
+# Commands not in the map by design (no ADT resource dependency).
+LOCAL_COMMANDS = [
+    "status", "configure", "profile list", "profile use", "profile remove",
+    "credentials set", "credentials forget", "credentials status",
+    "credentials doctor", "discovery",
+]
+
+
+def _available_hrefs(collections: Iterable[dict]) -> set[str]:
+    return {c["href"] for c in collections if c.get("href")}
+
+
+def _command_available(prefixes: list[str], hrefs: set[str]) -> bool:
+    return any(p in hrefs for p in prefixes)
+
+
+def _group_key(href: str) -> str:
+    # Absolute entries are service roots (contain the host) — bucket them
+    # without surfacing the hostname in examples.
+    if href.startswith("http://") or href.startswith("https://"):
+        return "(service root)"
+    # /sap/bc/adt/ddic/tables -> /ddic ; /sap/bc/adt/oo/classes -> /oo
+    marker = "/sap/bc/adt/"
+    if marker in href:
+        rest = href.split(marker, 1)[1].strip("/")
+        return "/" + (rest.split("/", 1)[0] if rest else "adt")
+    return href.split("/", 2)[-1].split("/", 1)[0] or "/"
+
+
+def compute_coverage(collections: list[dict]) -> dict:
+    hrefs = _available_hrefs(collections)
+    by_href = {c["href"]: c for c in collections}
+
+    available_commands = []
+    unavailable_commands = []
+    for command, prefixes in COMMAND_CAPABILITIES.items():
+        (available_commands if _command_available(prefixes, hrefs)
+         else unavailable_commands).append(command)
+
+    referenced = {p for prefixes in COMMAND_CAPABILITIES.values() for p in prefixes}
+    uncovered = [c for c in collections if c.get("href") not in referenced]
+
+    groups: "OrderedDict[str, dict]" = OrderedDict()
+    for c in sorted(uncovered, key=lambda x: x["href"] or ""):
+        key = _group_key(c["href"])
+        g = groups.setdefault(key, {"count": 0, "examples": []})
+        g["count"] += 1
+        if len(g["examples"]) < 4:
+            # Never surface absolute (host-bearing) URLs in examples.
+            g["examples"].append(
+                "<system base URL>" if key == "(service root)" else c["href"]
+            )
+
+    return {
+        "implemented_available": available_commands,
+        "available_not_covered": {
+            "total": len(uncovered),
+            "groups": [{"prefix": k, **v} for k, v in groups.items()],
+            "collections": [
+                {"href": c["href"], "title": c.get("title"),
+                 "content_types": c.get("content_types", [])}
+                for c in uncovered
+            ],
+        },
+        "covered_not_available": unavailable_commands,
+        "local_commands": len(LOCAL_COMMANDS),
+    }
+
+
+def render_discovery_markdown(collections: list[dict]) -> str:
+    """Render discovery collections to a generated endpoint table.
+
+    Generated output only — the curated adt_api.md keeps human annotations
+    (verified protocol facts, SICF, authorizations) that discovery lacks.
+    """
+    lines = [
+        "<!-- GENERATED by `sap-adt discovery --emit-markdown PATH`.",
+        "     Do not merge over adt_api.md; its protocol notes are curated. -->",
+        "",
+        "# ADT discovery — exposed resources",
+        "",
+        "| Href | Title | Accept content types |",
+        "|------|-------|----------------------|",
+    ]
+    for c in collections:
+        types = ", ".join(c.get("content_types") or []) or "—"
+        title = (c.get("title") or "").replace("|", "\\|")
+        lines.append(f"| `{c.get('href')}` | {title} | {types} |")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def render_text(report: dict) -> str:
+    """Text mode: per-segment counts; uncovered shown as path groups only."""
+    lines = []
+    avail = report["implemented_available"]
+    lines.append(f"implemented & available : {len(avail)}")
+    lines.append("  " + ", ".join(avail))
+    unc = report["available_not_covered"]
+    lines.append(f"available but NOT covered : {unc['total']}")
+    for g in unc["groups"]:
+        lines.append(f"  {g['prefix']}/*  {g['count']}")
+        for ex in g["examples"]:
+            lines.append(f"      {ex}")
+    missing = report["covered_not_available"]
+    lines.append(f"covered but NOT available : {len(missing)}")
+    for cmd in missing:
+        lines.append(f"  {cmd}")
+    lines.append(f"local commands (no ADT resource) : {report['local_commands']}")
+    return "\n".join(lines)