cisco-eox-query 1.0.0__py3-none-any.whl

cisco_eox_query/__init__.py

@@ -0,0 +1,55 @@
+"""Client for the Cisco End-of-Life (EOX) API.
+
+Versioning
+----------
+Library major versions track the EOX API version:
+
+- ``cisco-eox-query`` 1.x implements the EOX API **v5**.
+- ``cisco-eox-query`` 2.x will implement the EOX API **v6** (when released).
+
+The versioned implementation lives in :mod:`cisco_eox_query.v5`; this module
+re-exports it as the default. Pin an explicit version with::
+
+    from cisco_eox_query.v5 import EOXClient
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from cisco_eox_query._base import PaginationError, RateLimitError, RetryError
+from cisco_eox_query.v5 import (
+    EOX_ATTRIBS,
+    OS_TYPES,
+    EOXAPIError,
+    EOXClient,
+    EOXErrorInfo,
+    EOXRecord,
+    EOXResponse,
+    MigrationDetails,
+    PaginationResponseRecord,
+)
+
+try:
+    __version__ = version("cisco-eox-query")
+except PackageNotFoundError:
+    __version__ = "1.0.0"
+
+SUPPORTED_API_VERSION = 5
+
+__all__ = [
+    "EOXClient",
+    "EOXRecord",
+    "EOXResponse",
+    "EOXErrorInfo",
+    "EOXAPIError",
+    "MigrationDetails",
+    "PaginationResponseRecord",
+    "RetryError",
+    "RateLimitError",
+    "PaginationError",
+    "EOX_ATTRIBS",
+    "OS_TYPES",
+    "SUPPORTED_API_VERSION",
+    "__version__",
+]

cisco_eox_query/_base.py

@@ -0,0 +1,279 @@
+"""Shared transport, retries, and OAuth2 client-credentials authentication.
+
+All Cisco Support APIs authenticate with a bearer token obtained from the
+Cisco API Console using the client-credentials grant, and are subject to rate
+limiting. This base class encapsulates token acquisition/caching/refresh,
+request throttling, and retry handling so each versioned API client only
+concerns itself with endpoints and models.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from http import HTTPStatus
+from typing import Any, Self
+
+import httpx
+
+from cisco_eox_query.constants import (
+    BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_MIN_REQUEST_INTERVAL,
+    DEFAULT_RETRY_DELAY,
+    DEFAULT_TIMEOUT,
+    MAX_REQUESTS_PER_DAY,
+    MAX_REQUESTS_PER_SECOND,
+    TOKEN_URL,
+)
+
+logger = logging.getLogger(__name__)
+
+_RETRYABLE_STATUS_CODES = frozenset(
+    {
+        HTTPStatus.REQUEST_TIMEOUT,               # 408
+        HTTPStatus.TOO_EARLY,                     # 425
+        HTTPStatus.TOO_MANY_REQUESTS,             # 429
+        HTTPStatus.INTERNAL_SERVER_ERROR,         # 500
+        HTTPStatus.BAD_GATEWAY,                   # 502
+        HTTPStatus.SERVICE_UNAVAILABLE,           # 503
+        HTTPStatus.GATEWAY_TIMEOUT,               # 504
+    }
+)
+
+
+class RetryError(Exception):
+    """Raised when an API request fails after exhausting all retries."""
+
+
+class RateLimitError(RetryError):
+    """Raised when a rate-limited request fails after exhausting all retries."""
+
+
+class PaginationError(RetryError):
+    """Raised when pagination does not terminate within the page limit."""
+
+
+def _retry_after_seconds(response: httpx.Response, default: float) -> float:
+    value = response.headers.get("Retry-After")
+    if not value:
+        return default
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        pass
+    try:
+        retry_at = parsedate_to_datetime(value)
+        if retry_at.tzinfo is None:
+            retry_at = retry_at.replace(tzinfo=timezone.utc)
+        return max(0.0, (retry_at - datetime.now(timezone.utc)).total_seconds())
+    except (TypeError, ValueError):
+        return default
+
+
+class SupportClient:
+    """Base client providing authenticated, rate-limit-aware httpx transport.
+
+    Args:
+        client_id, client_secret: Cisco API Console credentials used to obtain
+            and refresh a bearer token via the client-credentials grant.
+        access_token: an already-obtained bearer token (skips token fetch).
+        base_url, token_url: service endpoints (defaults are current).
+        timeout: per-request httpx timeout.
+        max_retries: number of retries for transient failures (HTTP 429/5xx or
+            transport errors) before giving up.
+        retry_delay: base seconds between retries; the ``Retry-After`` response
+            header takes precedence when present.
+        min_request_interval: minimum seconds between requests to stay under
+            the API's requests-per-second limit (``0`` disables throttling).
+        transport: optional httpx transport (used by tests).
+    """
+
+    def __init__(
+        self,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        access_token: str | None = None,
+        *,
+        base_url: str = BASE_URL,
+        token_url: str = TOKEN_URL,
+        timeout: httpx.Timeout | float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        retry_delay: float = DEFAULT_RETRY_DELAY,
+        min_request_interval: float = DEFAULT_MIN_REQUEST_INTERVAL,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if access_token is None and (client_id is None or client_secret is None):
+            raise ValueError("provide access_token or client_id with client_secret")
+        if max_retries < 0:
+            raise ValueError("max_retries must be >= 0")
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.token_url = token_url
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+        self.min_request_interval = min_request_interval
+        self._access_token = access_token
+        self._token_expiry: float | None = None
+        self._next_request_at = 0.0
+        self._client = httpx.Client(base_url=base_url, timeout=timeout, transport=transport)
+        if self._access_token is None:
+            self._fetch_token()
+
+    def _fetch_token(self) -> None:
+        logger.debug("requesting access token from %s", self.token_url)
+        response = self._request_with_retry(
+            "POST",
+            self.token_url,
+            data={
+                "grant_type": "client_credentials",
+                "client_id": self.client_id,
+                "client_secret": self.client_secret,
+            },
+            headers={
+                "Accept": "application/json",
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+        )
+        if response.status_code >= 400:
+            logger.error("token request failed with %s: %s", response.status_code, response.text[:300])
+        response.raise_for_status()
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise ValueError(
+                f"invalid JSON from token endpoint {self.token_url}: {exc}"
+            ) from exc
+        if "access_token" not in payload:
+            raise ValueError(
+                f"token endpoint {self.token_url} returned no access_token "
+                f"(HTTP {response.status_code})"
+            )
+        self._access_token = payload["access_token"]
+        expires_in = float(payload.get("expires_in", 3600))
+        self._token_expiry = time.monotonic() + expires_in - 300
+        logger.info("obtained access token (expires_in=%ss)", expires_in)
+
+    def _ensure_token(self) -> None:
+        if self._access_token is None:
+            self._fetch_token()
+        elif (
+            self.client_id is not None
+            and self._token_expiry is not None
+            and time.monotonic() >= self._token_expiry
+        ):
+            logger.debug("access token expired, refreshing")
+            self._fetch_token()
+
+    def _throttle(self) -> None:
+        if self.min_request_interval <= 0:
+            return
+        now = time.monotonic()
+        wait = self._next_request_at - now
+        if wait > 0:
+            logger.debug("throttling request for %.2fs", wait)
+            time.sleep(wait)
+        self._next_request_at = time.monotonic() + self.min_request_interval
+
+    def _request_with_retry(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        data: dict[str, str] | None = None,
+    ) -> httpx.Response:
+        request = self._client.build_request(method, url, params=params, headers=headers, data=data)
+        attempts = self.max_retries + 1
+        for attempt in range(attempts):
+            self._throttle()
+            try:
+                response = self._client.send(request)
+            except httpx.TransportError as exc:
+                if attempt >= self.max_retries:
+                    raise RetryError(
+                        f"request to {url} failed after {self.max_retries} retries: {exc}"
+                    ) from exc
+                logger.warning(
+                    "transport error (attempt %d/%d), retrying in %.1fs: %s",
+                    attempt + 1,
+                    attempts,
+                    self.retry_delay,
+                    exc,
+                )
+                time.sleep(self.retry_delay)
+                continue
+            if response.status_code not in _RETRYABLE_STATUS_CODES:
+                return response
+            if attempt >= self.max_retries:
+                if response.status_code == HTTPStatus.TOO_MANY_REQUESTS:
+                    raise RateLimitError(
+                        f"exceeded the Cisco API rate limit after {self.max_retries} retries; "
+                        f"this is likely the daily limit of {MAX_REQUESTS_PER_DAY} requests/day "
+                        f"(or the {MAX_REQUESTS_PER_SECOND} requests/second burst limit); "
+                        "please wait and try again later"
+                    )
+                raise RetryError(
+                    f"request to {url} returned HTTP {response.status_code} "
+                    f"after {self.max_retries} retries"
+                )
+            delay = _retry_after_seconds(response, self.retry_delay)
+            logger.warning(
+                "HTTP %s (attempt %d/%d), retrying in %.1fs",
+                response.status_code,
+                attempt + 1,
+                attempts,
+                delay,
+            )
+            time.sleep(delay)
+
+    def _get_json(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._ensure_token()
+        logger.debug("GET %s params=%s", path, params or {})
+        response = self._request_with_retry(
+            "GET",
+            path,
+            params=params or {},
+            headers={
+                "Authorization": f"Bearer {self._access_token}",
+                "Accept": "application/json",
+            },
+        )
+        if response.status_code == HTTPStatus.UNAUTHORIZED and self.client_id is not None:
+            logger.warning(
+                "GET %s returned %s, refreshing token and retrying once",
+                path,
+                response.status_code,
+            )
+            self._fetch_token()
+            response = self._request_with_retry(
+                "GET",
+                path,
+                params=params or {},
+                headers={
+                    "Authorization": f"Bearer {self._access_token}",
+                    "Accept": "application/json",
+                },
+            )
+        if response.status_code >= 400:
+            logger.error("GET %s failed with %s: %s", path, response.status_code, response.text[:300])
+        response.raise_for_status()
+        logger.debug("GET %s -> %s (%d bytes)", path, response.status_code, len(response.content))
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise ValueError(
+                f"invalid JSON response from {path} (HTTP {response.status_code}): {exc}"
+            ) from exc
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *exc_info: object) -> None:
+        self.close()

cisco_eox_query/cli.py

@@ -0,0 +1,272 @@
+"""Command-line interface for cisco-eox-query.
+
+Installed as the ``eox-query`` console script.
+"""
+
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import sys
+from typing import Sequence
+
+import httpx
+
+from cisco_eox_query import (
+    EOXAPIError,
+    EOXClient,
+    EOXRecord,
+    PaginationError,
+    RateLimitError,
+    RetryError,
+    __version__,
+)
+from cisco_eox_query.constants import DEFAULT_MAX_PAGES
+from cisco_eox_query.examples import (
+    COMMAND_EXAMPLES,
+    ROOT_EXAMPLES,
+    format_epilog,
+    format_examples,
+)
+
+LOG_FORMAT = "%(asctime)s - %(levelname)s - %(name)s - %(message)s"
+LOG_DATEFMT = "%Y-%m-%d %H:%M:%S"
+
+EXIT_RATE_LIMIT = 2
+
+logger = logging.getLogger(__name__)
+
+
+class _ExamplesAction(argparse.Action):
+    """Print usage examples and exit (mirrors the ``--version`` action)."""
+
+    def __init__(
+        self,
+        option_strings,
+        dest,
+        nargs=0,
+        examples=None,
+        title=None,
+        **kwargs,
+    ):
+        super().__init__(option_strings, dest, nargs=nargs, **kwargs)
+        self.examples = examples or []
+        self.title = title
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        print(format_examples(self.examples, title=self.title))
+        parser.exit()
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="eox-query",
+        description="Query the Cisco End-of-Life (EOX) API.",
+        epilog=format_epilog(ROOT_EXAMPLES)
+        + "\n\nRun 'eox-query --examples' for more examples.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser.add_argument(
+        "--examples",
+        action=_ExamplesAction,
+        examples=ROOT_EXAMPLES,
+        title="Examples",
+        help="show usage examples and exit",
+    )
+    parser.add_argument(
+        "--client-id",
+        default=os.environ.get("EOX_CLIENT_ID"),
+        help="Cisco API console client ID (or EOX_CLIENT_ID)",
+    )
+    parser.add_argument(
+        "--client-secret",
+        default=os.environ.get("EOX_CLIENT_SECRET"),
+        help="Cisco API console client secret (or EOX_CLIENT_SECRET)",
+    )
+    parser.add_argument(
+        "--access-token",
+        default=os.environ.get("EOX_ACCESS_TOKEN"),
+        help="pre-obtained bearer token (or EOX_ACCESS_TOKEN)",
+    )
+    parser.add_argument("--timeout", type=float, default=30.0, help="request timeout in seconds")
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        action="count",
+        default=0,
+        help="increase log verbosity (-v info, -vv debug)",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    pid = subparsers.add_parser(
+        "pid",
+        help="search by product ID(s)",
+        description="Search the Cisco EOX API by product ID(s).",
+        epilog=format_epilog(COMMAND_EXAMPLES["pid"])
+        + "\n\nRun 'eox-query pid --examples' for more examples.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    pid.add_argument(
+        "--examples",
+        action=_ExamplesAction,
+        examples=COMMAND_EXAMPLES["pid"],
+        title="Examples for 'pid'",
+        help="show usage examples and exit",
+    )
+    pid.add_argument("product_ids", nargs="+", help="one or more PIDs (wildcards allowed)")
+
+    serial = subparsers.add_parser(
+        "serial",
+        help="search by serial number(s)",
+        description="Search the Cisco EOX API by serial number(s).",
+        epilog=format_epilog(COMMAND_EXAMPLES["serial"])
+        + "\n\nRun 'eox-query serial --examples' for more examples.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    serial.add_argument(
+        "--examples",
+        action=_ExamplesAction,
+        examples=COMMAND_EXAMPLES["serial"],
+        title="Examples for 'serial'",
+        help="show usage examples and exit",
+    )
+    serial.add_argument("serial_numbers", nargs="+", help="one or more serial numbers")
+
+    software = subparsers.add_parser(
+        "software",
+        help="search by software release string(s)",
+        description="Search the Cisco EOX API by software release string(s).",
+        epilog=format_epilog(COMMAND_EXAMPLES["software"])
+        + "\n\nRun 'eox-query software --examples' for more examples.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    software.add_argument(
+        "--examples",
+        action=_ExamplesAction,
+        examples=COMMAND_EXAMPLES["software"],
+        title="Examples for 'software'",
+        help="show usage examples and exit",
+    )
+    software.add_argument("releases", nargs="+", help="SWversion[,OSType] tuples, e.g. 12.4(15)T,IOS")
+
+    dates = subparsers.add_parser(
+        "dates",
+        help="search by date range",
+        description="Search the Cisco EOX API by date range.",
+        epilog=format_epilog(COMMAND_EXAMPLES["dates"])
+        + "\n\nRun 'eox-query dates --examples' for more examples.",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    dates.add_argument(
+        "--examples",
+        action=_ExamplesAction,
+        examples=COMMAND_EXAMPLES["dates"],
+        title="Examples for 'dates'",
+        help="show usage examples and exit",
+    )
+    dates.add_argument("start", help="start date YYYY-MM-DD")
+    dates.add_argument("end", help="end date YYYY-MM-DD")
+    dates.add_argument("--attribs", help="comma-separated eoxAttrib values")
+
+    return parser
+
+
+def setup_logging(level: int = logging.WARNING) -> None:
+    logging.basicConfig(level=level, format=LOG_FORMAT, datefmt=LOG_DATEFMT)
+
+
+def _log_level(verbose: int) -> int:
+    if verbose >= 2:
+        return logging.DEBUG
+    if verbose == 1:
+        return logging.INFO
+    return logging.WARNING
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    setup_logging(_log_level(args.verbose))
+    try:
+        with _build_client(args) as client:
+            records = _dispatch(client, args)
+        for record in records:
+            _print_record(record)
+        if records:
+            logger.info("found %d EOX record(s)", len(records))
+        else:
+            logger.warning("No EOX records found.")
+    except RateLimitError as exc:
+        logger.error("%s", exc)
+        return EXIT_RATE_LIMIT
+    except (ValueError, httpx.HTTPError, EOXAPIError, RetryError) as exc:
+        logger.error("%s", exc)
+        return 1
+    return 0
+
+
+def _build_client(args: argparse.Namespace) -> EOXClient:
+    if args.access_token:
+        return EOXClient(access_token=args.access_token, timeout=args.timeout)
+    if args.client_id and args.client_secret:
+        return EOXClient(client_id=args.client_id, client_secret=args.client_secret, timeout=args.timeout)
+    raise ValueError(
+        "credentials required: --client-id and --client-secret "
+        "(or EOX_CLIENT_ID/EOX_CLIENT_SECRET), or --access-token"
+    )
+
+
+def _dispatch(client: EOXClient, args: argparse.Namespace) -> list[EOXRecord]:
+    if args.command == "pid":
+        return _collect(client.search_by_product_ids, ",".join(args.product_ids))
+    if args.command == "serial":
+        return _collect(client.search_by_serial_numbers, ",".join(args.serial_numbers))
+    if args.command == "software":
+        return _collect(client.search_by_software_releases, *args.releases)
+    if args.command == "dates":
+        attribs = args.attribs.split(",") if args.attribs else None
+        return _collect(client.search_by_dates, args.start, args.end, attribs=attribs)
+    raise AssertionError(f"unhandled command: {args.command}")
+
+
+def _collect(request_fn, *args, **kwargs) -> list[EOXRecord]:
+    records = []
+    page = 1
+    while True:
+        if page > DEFAULT_MAX_PAGES:
+            raise PaginationError(
+                f"pagination did not terminate after {DEFAULT_MAX_PAGES} pages"
+            )
+        response = request_fn(*args, page=page, **kwargs)
+        response.raise_for_error()
+        records.extend(response.records)
+        last = response.pagination.last_index if response.pagination and response.pagination.last_index else 1
+        if page >= last:
+            return records
+        page += 1
+
+
+def _print_record(record: EOXRecord) -> None:
+    migration = record.migration_details
+    print(record.eol_product_id or "<no product id>")
+    for label, value in [
+        ("Product Description", record.product_id_description),
+        ("Bulletin", record.product_bulletin_number),
+        ("Bulletin Link", record.link_to_product_bulletin_url),
+        ("Announcement", record.eox_external_announcement_date),
+        ("End Of Sale", record.end_of_sale_date),
+        ("SW Maintenance Ends", record.end_of_sw_maintenance_releases),
+        ("Security Vulnerability Support Ends", record.end_of_security_vul_support_date),
+        ("Routine Failure Analysis Ends", record.end_of_routine_failure_analysis_date),
+        ("Service Contract Renewal", record.end_of_service_contract_renewal),
+        ("Last Date of Support", record.last_date_of_support),
+        ("Service Attach Ends", record.end_of_svc_attach_date),
+        ("Migration Product", migration.migration_information if migration else None),
+        ("Migration Product Info URL", migration.migration_product_info_url if migration else None),
+        ("Migration Product ID", migration.migration_product_id if migration else None),
+        ("Migration Strategy", migration.migration_strategy if migration else None),
+    ]:
+        if value is not None:
+            print(f"  {label:<30} {value}")

cisco_eox_query/constants.py

@@ -0,0 +1,29 @@
+"""Constants shared across Cisco EOX API client versions."""
+
+from __future__ import annotations
+
+import httpx
+
+BASE_URL = "https://apix.cisco.com"
+TOKEN_URL = "https://id.cisco.com/oauth2/default/v1/token"
+DEFAULT_TIMEOUT = httpx.Timeout(30.0)
+
+MAX_REQUESTS_PER_SECOND = 5
+MAX_REQUESTS_PER_DAY = 5000
+
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_RETRY_DELAY = 5.0
+DEFAULT_MIN_REQUEST_INTERVAL = 0.25
+DEFAULT_MAX_PAGES = 1000
+
+__all__ = [
+    "BASE_URL",
+    "TOKEN_URL",
+    "DEFAULT_TIMEOUT",
+    "MAX_REQUESTS_PER_SECOND",
+    "MAX_REQUESTS_PER_DAY",
+    "DEFAULT_MAX_RETRIES",
+    "DEFAULT_RETRY_DELAY",
+    "DEFAULT_MIN_REQUEST_INTERVAL",
+    "DEFAULT_MAX_PAGES",
+]