cisco-eox-query 1.0.0__tar.gz

cisco_eox_query-1.0.0/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Testing
+.pytest_cache/
+.tox/
+.coverage
+coverage.xml
+htmlcov/
+.envrc

cisco_eox_query-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dave Heckman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cisco_eox_query-1.0.0/PKG-INFO

@@ -0,0 +1,171 @@
+Metadata-Version: 2.5
+Name: cisco-eox-query
+Version: 1.0.0
+Summary: Python client for the Cisco End-of-Life (EOX) API
+Project-URL: Homepage, https://github.com/dheckman-dev/cisco-eox-query
+Project-URL: Repository, https://github.com/dheckman-dev/cisco-eox-query
+Project-URL: Documentation, https://github.com/dheckman-dev/cisco-eox-query#readme
+Project-URL: Issues, https://github.com/dheckman-dev/cisco-eox-query/issues
+Author-email: Dave Heckman <david@heckman.network>
+Maintainer-email: Dave Heckman <david@heckman.network>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cisco,end-of-life,end-of-support,eox,httpx,pydantic
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# cisco-eox-query
+
+Python client for the [Cisco End-of-Life (EOX) API](https://developer.cisco.com/docs/support-apis/eox).
+
+Built on `httpx` for transport and `pydantic` for response models. This package
+implements the Cisco EOX API v5 as described by
+`Cisco-End-of-Life-EOX-v5_0.wadl`.
+
+![Python versions](https://img.shields.io/pypi/pyversions/cisco-eox-query)
+![Coverage](https://img.shields.io/codecov/c/github/dheckman-dev/cisco-eox-query)
+
+## Versioning
+
+Library major versions track the EOX API version:
+
+| `cisco-eox-query` | EOX API | Status |
+| --- | --- | --- |
+| 1.x | v5 | current |
+| 2.x | v6 | future, when released |
+
+The versioned implementation lives under `cisco_eox_query.v5`. The top-level
+package re-exports the latest supported version for convenience.
+
+## Install
+
+```bash
+pip install cisco-eox-query
+```
+
+## Authentication
+
+EOX is one of the Cisco Support APIs and requires a Smart Net Total Care (SNTC)
+or Partner Support Service (PSS) entitlement. Register an application at the
+[Cisco API Console](https://apiconsole.cisco.com/) to obtain a client ID and
+client secret. The client exchanges them for a bearer token (client-credentials
+grant) and refreshes it automatically before expiry.
+
+## Usage
+
+```python
+from cisco_eox_query import EOXClient
+
+with EOXClient(client_id="...", client_secret="...") as client:
+    records = list(client.iter_product_ids(["WS-C2960X-48TS-L", "WIC-1T="]))
+    for record in records:
+        print(record.eol_product_id, record.last_date_of_support)
+```
+
+All four WADL endpoints are exposed as `search_*` methods returning an
+`EOXResponse` (with `records`, `pagination`, and optional `error`), plus
+`iter_*` variants that follow pagination automatically:
+
+| Endpoint | Method |
+| --- | --- |
+| `EOXByDates/{pageIndex}/{startDate}/{endDate}` | `search_by_dates` / `iter_dates` |
+| `EOXByProductID/{pageIndex}/{productIDs}` | `search_by_product_ids` / `iter_product_ids` |
+| `EOXBySerialNumber/{pageIndex}/{serialNumbers}` | `search_by_serial_numbers` / `iter_serial_numbers` |
+| `EOXBySWReleaseString/{pageIndex}` | `search_by_software_releases` / `iter_software_releases` |
+
+The `iter_*` variants accept an optional `max_pages` keyword (default 1000) as
+a safety valve against runaway pagination; if the API never reports a final
+page, a `PaginationError` is raised instead of looping forever.
+
+If you already hold a token:
+
+```python
+client = EOXClient(access_token="...")
+```
+
+## Command line
+
+The package installs an `eox-query` console script. Credentials may be passed
+as flags or via `EOX_CLIENT_ID`, `EOX_CLIENT_SECRET`, and `EOX_ACCESS_TOKEN`
+environment variables.
+
+```bash
+eox-query --client-id ... --client-secret ... pid WS-C2960X-48TS-L WIC-1T=
+eox-query --client-id ... --client-secret ... serial JAE11108ESH SAD11510738
+eox-query --client-id ... --client-secret ... software 12.4\(15\)T,IOS
+eox-query --client-id ... --client-secret ... dates 2011-01-01 2015-12-31 --attribs EO_SALES_DATE
+```
+
+Run `eox-query --examples` for annotated usage examples, or
+`eox-query <command> --examples` (e.g. `eox-query pid --examples`) for
+command-specific examples. Examples are also embedded in `--help` output.
+
+Logs go to stderr with the format `YYYY-MM-DD HH:MM:SS - SEVERITY - module - message`; queried records print to stdout so they can be piped. Diagnostics are silent by default and increase with `-v` (info) / `-vv` (debug).
+
+```bash
+eox-query -vv --client-id ... --client-secret ... pid WIC-1T=
+```
+
+Library users get the same structured loggers (`cisco_eox_query._base`, `cisco_eox_query.v5.client`, ...) without any handler configuration.
+
+## Rate limiting and retries
+
+The EOX API is limited to 5 requests/second and 5000 requests/day. The client
+handles this automatically:
+
+- Requests are throttled to stay under the per-second limit (default 0.25s
+  between requests, configurable via `min_request_interval`).
+- HTTP 429/408/425/5xx responses and transport errors are retried up to
+  `max_retries` times (default 3) with `retry_delay` seconds between attempts
+  (default 5s), honoring the server's `Retry-After` header (both delay-seconds
+  and RFC 7231 HTTP-date formats) when present.
+- After retries are exhausted on a 429, a `RateLimitError` is raised; the CLI
+  prints a message about hitting the daily limit and exits with code 2.
+- Non-retryable errors (e.g. HTTP 403) are raised immediately.
+
+```python
+from cisco_eox_query import EOXClient, RateLimitError
+
+with EOXClient(client_id="...", client_secret="...", max_retries=5, retry_delay=2.0) as client:
+    try:
+        for record in client.iter_product_ids(["WIC-1T="]):
+            print(record.eol_product_id)
+    except RateLimitError as exc:
+        print(f"Hit the daily request limit: {exc}")
+```
+
+## Error handling
+
+- `EOXAPIError` — raised when a response contains an `EOXError` payload. Call
+  `response.raise_for_error()` on `search_*` results; the `iter_*` variants
+  raise automatically.
+- `RetryError` — a request failed after exhausting all retries.
+- `RateLimitError` — a rate-limited request failed after exhausting retries
+  (subclass of `RetryError`).
+- `PaginationError` — pagination did not terminate within `max_pages`
+  (subclass of `RetryError`).
+- `ValueError` — invalid input, a malformed JSON response body, or an
+  unexpected response shape (possible API schema change). The message includes
+  the request path and the first validation error.
+
+The client tolerates common API quirks: a `null` `EOXRecord` is treated as an
+empty result set, and a single record returned as a bare object (not wrapped
+in a list) is accepted.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv build
+```

cisco_eox_query-1.0.0/README.md

@@ -0,0 +1,145 @@
+# cisco-eox-query
+
+Python client for the [Cisco End-of-Life (EOX) API](https://developer.cisco.com/docs/support-apis/eox).
+
+Built on `httpx` for transport and `pydantic` for response models. This package
+implements the Cisco EOX API v5 as described by
+`Cisco-End-of-Life-EOX-v5_0.wadl`.
+
+![Python versions](https://img.shields.io/pypi/pyversions/cisco-eox-query)
+![Coverage](https://img.shields.io/codecov/c/github/dheckman-dev/cisco-eox-query)
+
+## Versioning
+
+Library major versions track the EOX API version:
+
+| `cisco-eox-query` | EOX API | Status |
+| --- | --- | --- |
+| 1.x | v5 | current |
+| 2.x | v6 | future, when released |
+
+The versioned implementation lives under `cisco_eox_query.v5`. The top-level
+package re-exports the latest supported version for convenience.
+
+## Install
+
+```bash
+pip install cisco-eox-query
+```
+
+## Authentication
+
+EOX is one of the Cisco Support APIs and requires a Smart Net Total Care (SNTC)
+or Partner Support Service (PSS) entitlement. Register an application at the
+[Cisco API Console](https://apiconsole.cisco.com/) to obtain a client ID and
+client secret. The client exchanges them for a bearer token (client-credentials
+grant) and refreshes it automatically before expiry.
+
+## Usage
+
+```python
+from cisco_eox_query import EOXClient
+
+with EOXClient(client_id="...", client_secret="...") as client:
+    records = list(client.iter_product_ids(["WS-C2960X-48TS-L", "WIC-1T="]))
+    for record in records:
+        print(record.eol_product_id, record.last_date_of_support)
+```
+
+All four WADL endpoints are exposed as `search_*` methods returning an
+`EOXResponse` (with `records`, `pagination`, and optional `error`), plus
+`iter_*` variants that follow pagination automatically:
+
+| Endpoint | Method |
+| --- | --- |
+| `EOXByDates/{pageIndex}/{startDate}/{endDate}` | `search_by_dates` / `iter_dates` |
+| `EOXByProductID/{pageIndex}/{productIDs}` | `search_by_product_ids` / `iter_product_ids` |
+| `EOXBySerialNumber/{pageIndex}/{serialNumbers}` | `search_by_serial_numbers` / `iter_serial_numbers` |
+| `EOXBySWReleaseString/{pageIndex}` | `search_by_software_releases` / `iter_software_releases` |
+
+The `iter_*` variants accept an optional `max_pages` keyword (default 1000) as
+a safety valve against runaway pagination; if the API never reports a final
+page, a `PaginationError` is raised instead of looping forever.
+
+If you already hold a token:
+
+```python
+client = EOXClient(access_token="...")
+```
+
+## Command line
+
+The package installs an `eox-query` console script. Credentials may be passed
+as flags or via `EOX_CLIENT_ID`, `EOX_CLIENT_SECRET`, and `EOX_ACCESS_TOKEN`
+environment variables.
+
+```bash
+eox-query --client-id ... --client-secret ... pid WS-C2960X-48TS-L WIC-1T=
+eox-query --client-id ... --client-secret ... serial JAE11108ESH SAD11510738
+eox-query --client-id ... --client-secret ... software 12.4\(15\)T,IOS
+eox-query --client-id ... --client-secret ... dates 2011-01-01 2015-12-31 --attribs EO_SALES_DATE
+```
+
+Run `eox-query --examples` for annotated usage examples, or
+`eox-query <command> --examples` (e.g. `eox-query pid --examples`) for
+command-specific examples. Examples are also embedded in `--help` output.
+
+Logs go to stderr with the format `YYYY-MM-DD HH:MM:SS - SEVERITY - module - message`; queried records print to stdout so they can be piped. Diagnostics are silent by default and increase with `-v` (info) / `-vv` (debug).
+
+```bash
+eox-query -vv --client-id ... --client-secret ... pid WIC-1T=
+```
+
+Library users get the same structured loggers (`cisco_eox_query._base`, `cisco_eox_query.v5.client`, ...) without any handler configuration.
+
+## Rate limiting and retries
+
+The EOX API is limited to 5 requests/second and 5000 requests/day. The client
+handles this automatically:
+
+- Requests are throttled to stay under the per-second limit (default 0.25s
+  between requests, configurable via `min_request_interval`).
+- HTTP 429/408/425/5xx responses and transport errors are retried up to
+  `max_retries` times (default 3) with `retry_delay` seconds between attempts
+  (default 5s), honoring the server's `Retry-After` header (both delay-seconds
+  and RFC 7231 HTTP-date formats) when present.
+- After retries are exhausted on a 429, a `RateLimitError` is raised; the CLI
+  prints a message about hitting the daily limit and exits with code 2.
+- Non-retryable errors (e.g. HTTP 403) are raised immediately.
+
+```python
+from cisco_eox_query import EOXClient, RateLimitError
+
+with EOXClient(client_id="...", client_secret="...", max_retries=5, retry_delay=2.0) as client:
+    try:
+        for record in client.iter_product_ids(["WIC-1T="]):
+            print(record.eol_product_id)
+    except RateLimitError as exc:
+        print(f"Hit the daily request limit: {exc}")
+```
+
+## Error handling
+
+- `EOXAPIError` — raised when a response contains an `EOXError` payload. Call
+  `response.raise_for_error()` on `search_*` results; the `iter_*` variants
+  raise automatically.
+- `RetryError` — a request failed after exhausting all retries.
+- `RateLimitError` — a rate-limited request failed after exhausting retries
+  (subclass of `RetryError`).
+- `PaginationError` — pagination did not terminate within `max_pages`
+  (subclass of `RetryError`).
+- `ValueError` — invalid input, a malformed JSON response body, or an
+  unexpected response shape (possible API schema change). The message includes
+  the request path and the first validation error.
+
+The client tolerates common API quirks: a `null` `EOXRecord` is treated as an
+empty result set, and a single record returned as a bare object (not wrapped
+in a list) is accepted.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv build
+```

cisco_eox_query-1.0.0/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest 1.x release receives security fixes.
+
+| Version | Supported |
+| ------- | --------- |
+| latest 1.x | Yes |
+| older 1.x | No |
+
+## Reporting a Vulnerability
+
+Please do **not** open a public issue for a security vulnerability.
+
+Instead, report it privately via one of:
+
+- **GitHub private security advisory:** <https://github.com/dheckman-dev/cisco-eox-query/security/advisories/new>
+- **Email:** [david@heckman.network](mailto:david@heckman.network)
+
+We will acknowledge receipt within **48 hours** and work toward coordinated disclosure, generally publishing a fix and advisory within 90 days or as agreed with the reporter.
+
+## Security Considerations for Users
+
+- **Credentials:** Cisco EOX API credentials (`client_id`/`client_secret`) must be supplied at runtime via environment variables (`EOX_CLIENT_ID`, `EOX_CLIENT_SECRET`, `EOX_ACCESS_TOKEN`) or constructor arguments. Never hard-code or commit credentials.
+- **TLS:** All traffic to the Cisco API is over HTTPS. The client does not disable TLS certificate verification.
+- **Network posture:** The package only makes outbound requests to the Cisco EOX API endpoints. It does not accept inbound connections.
+- **Dependencies:** Dependencies are pinned via `uv.lock`. Keep the package updated to receive dependency security fixes.

cisco_eox_query-1.0.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cisco-eox-query"
+version = "1.0.0"
+description = "Python client for the Cisco End-of-Life (EOX) API"
+readme = "README.md"
+authors = [
+    { name = "Dave Heckman", email="david@heckman.network"},
+]
+maintainers = [
+    { name = "Dave Heckman", email="david@heckman.network"},
+]
+requires-python = ">=3.11"
+license = "MIT"
+keywords = ["cisco", "eox", "end-of-life", "end-of-support", "httpx", "pydantic"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.28.1",
+    "pydantic>=2.7",
+]
+
+[project.scripts]
+eox-query = "cisco_eox_query.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/dheckman-dev/cisco-eox-query"
+Repository = "https://github.com/dheckman-dev/cisco-eox-query"
+Documentation = "https://github.com/dheckman-dev/cisco-eox-query#readme"
+Issues = "https://github.com/dheckman-dev/cisco-eox-query/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-cov>=4.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cisco_eox_query"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+  "/.github",
+  "/.envrc",
+  "/.gitignore",
+  "/.pytest_cache",
+  "/.python-version",
+  "/.tox",
+  "/.venv",
+  "/.coverage",
+  "/coverage.xml",
+  "/dist",
+  "/tests",
+  "/tox.ini",
+  "/uv.lock",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.coverage.run]
+source = ["cisco_eox_query"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true

cisco_eox_query-1.0.0/src/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__",
+]