spn-client 0.1.0__tar.gz

spn_client-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+.venv/

spn_client-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Hammett
+
+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.

spn_client-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: spn-client
+Version: 0.1.0
+Summary: A hardened client for archive.org's availability and Save Page Now (SPN2) APIs — process-wide rate pacing with a circuit breaker, dual-mode anonymous/S3-authenticated submission, and an explicit archive-outcome vocabulary.
+Project-URL: Homepage, https://github.com/MHammett/spn-client
+Project-URL: Issues, https://github.com/MHammett/spn-client/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: requests<3.0,>=2.31.0
+Description-Content-Type: text/markdown
+
+# spn-client
+
+A hardened Python client for archive.org's availability API and Save Page Now
+(SPN2) — the pieces that are easy to get wrong when you actually run this
+against archive.org at any volume:
+
+- **Process-wide rate pacing with a circuit breaker.** archive.org throttles
+  per IP, not per thread or per endpoint. A naive per-thread backoff (or none
+  at all) looks fine in testing and then silently stops archiving anything
+  the first time it's run concurrently or against a busy queue.
+- **Both submission modes.** Anonymous `GET /save/<url>` (capture runs inline,
+  answer comes back as a redirect) and S3-key-authenticated `POST /save`
+  (capture is queued, answer comes back as a `job_id` you poll for).
+- **An explicit outcome vocabulary.** `submitted` is not `archived`. This
+  library only ever reports `archived: True` alongside a real snapshot URL
+  that came back from archive.org — never as a synonym for "we asked."
+- **Staleness checking**, so callers can skip re-archiving a URL that already
+  has a recent-enough snapshot.
+
+Every non-obvious piece of behavior in `client.py` is a documented response to
+a specific, dated, measured incident against the real archive.org API — not
+a guess.
+
+## Install
+
+```bash
+pip install spn-client
+```
+
+## Usage
+
+```python
+import spn_client
+
+result = spn_client.check("https://example.com/some-page")
+if result["archived"] is False or result.get("snapshot_stale"):
+    submission = spn_client.submit(
+        "https://example.com/some-page",
+        access_key=ACCESS_KEY,   # optional — omit for anonymous, lower-rate submission
+        secret_key=SECRET_KEY,
+    )
+    if submission["job_id"]:
+        # authenticated path: poll for the real outcome
+        status = spn_client.check_job_status(
+            submission["job_id"], access_key=ACCESS_KEY, secret_key=SECRET_KEY
+        )
+```
+
+Call `spn_client.reset_rate_limit_state()` once at the start of each
+independent run/process if you're running this as a long-lived worker —
+the pacing/breaker state is process-wide and intentionally does not reset
+itself, so a breaker tripped by one run would otherwise silently degrade
+the next.
+
+## What this doesn't do
+
+This is the archive.org client only — it has no opinion about:
+- What staleness policy is right for your use case (`stale_days` is always a
+  caller-supplied parameter)
+- How you track which URLs you've already archived (that's a caller-side
+  ledger/cache concern)
+- Batch-loop concerns like a progress heartbeat or a wall-clock budget across
+  many submissions — those depend on your own operational needs
+
+## License
+
+MIT

spn_client-0.1.0/README.md

@@ -0,0 +1,67 @@
+# spn-client
+
+A hardened Python client for archive.org's availability API and Save Page Now
+(SPN2) — the pieces that are easy to get wrong when you actually run this
+against archive.org at any volume:
+
+- **Process-wide rate pacing with a circuit breaker.** archive.org throttles
+  per IP, not per thread or per endpoint. A naive per-thread backoff (or none
+  at all) looks fine in testing and then silently stops archiving anything
+  the first time it's run concurrently or against a busy queue.
+- **Both submission modes.** Anonymous `GET /save/<url>` (capture runs inline,
+  answer comes back as a redirect) and S3-key-authenticated `POST /save`
+  (capture is queued, answer comes back as a `job_id` you poll for).
+- **An explicit outcome vocabulary.** `submitted` is not `archived`. This
+  library only ever reports `archived: True` alongside a real snapshot URL
+  that came back from archive.org — never as a synonym for "we asked."
+- **Staleness checking**, so callers can skip re-archiving a URL that already
+  has a recent-enough snapshot.
+
+Every non-obvious piece of behavior in `client.py` is a documented response to
+a specific, dated, measured incident against the real archive.org API — not
+a guess.
+
+## Install
+
+```bash
+pip install spn-client
+```
+
+## Usage
+
+```python
+import spn_client
+
+result = spn_client.check("https://example.com/some-page")
+if result["archived"] is False or result.get("snapshot_stale"):
+    submission = spn_client.submit(
+        "https://example.com/some-page",
+        access_key=ACCESS_KEY,   # optional — omit for anonymous, lower-rate submission
+        secret_key=SECRET_KEY,
+    )
+    if submission["job_id"]:
+        # authenticated path: poll for the real outcome
+        status = spn_client.check_job_status(
+            submission["job_id"], access_key=ACCESS_KEY, secret_key=SECRET_KEY
+        )
+```
+
+Call `spn_client.reset_rate_limit_state()` once at the start of each
+independent run/process if you're running this as a long-lived worker —
+the pacing/breaker state is process-wide and intentionally does not reset
+itself, so a breaker tripped by one run would otherwise silently degrade
+the next.
+
+## What this doesn't do
+
+This is the archive.org client only — it has no opinion about:
+- What staleness policy is right for your use case (`stale_days` is always a
+  caller-supplied parameter)
+- How you track which URLs you've already archived (that's a caller-side
+  ledger/cache concern)
+- Batch-loop concerns like a progress heartbeat or a wall-clock budget across
+  many submissions — those depend on your own operational needs
+
+## License
+
+MIT

spn_client-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "spn-client"
+version = "0.1.0"
+description = "A hardened client for archive.org's availability and Save Page Now (SPN2) APIs — process-wide rate pacing with a circuit breaker, dual-mode anonymous/S3-authenticated submission, and an explicit archive-outcome vocabulary."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "requests>=2.31.0,<3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/MHammett/spn-client"
+Issues = "https://github.com/MHammett/spn-client/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/spn_client"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "--disable-socket --allow-hosts=127.0.0.1,::1"
+
+[tool.mypy]
+python_version = "3.10"
+strict = false
+ignore_missing_imports = true

spn_client-0.1.0/src/spn_client/__init__.py

@@ -0,0 +1,43 @@
+"""spn-client: a hardened client for archive.org's availability and Save Page Now APIs."""
+
+from spn_client.client import (
+    ARCHIVE_ARCHIVED,
+    ARCHIVE_CAPTURE_FAILED,
+    ARCHIVE_NOT_ATTEMPTED,
+    ARCHIVE_OUTCOME_LABELS,
+    ARCHIVE_PENDING,
+    ARCHIVE_SUBMIT_FAILED,
+    ARCHIVE_SUBMITTED,
+    DEFAULT_STALE_DAYS,
+    capture_capacity,
+    check,
+    check_job_status,
+    rate_limited_out,
+    reset_rate_limit_state,
+    service_health_note,
+    snapshot_raw_url,
+    submit,
+    system_status,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ARCHIVE_ARCHIVED",
+    "ARCHIVE_CAPTURE_FAILED",
+    "ARCHIVE_NOT_ATTEMPTED",
+    "ARCHIVE_OUTCOME_LABELS",
+    "ARCHIVE_PENDING",
+    "ARCHIVE_SUBMIT_FAILED",
+    "ARCHIVE_SUBMITTED",
+    "DEFAULT_STALE_DAYS",
+    "capture_capacity",
+    "check",
+    "check_job_status",
+    "rate_limited_out",
+    "reset_rate_limit_state",
+    "service_health_note",
+    "snapshot_raw_url",
+    "submit",
+    "system_status",
+]

spn_client-0.1.0/src/spn_client/_http.py

@@ -0,0 +1,22 @@
+"""Outbound-HTTP identity for spn-client.
+
+A dedicated User-Agent, separate from any consuming project's own — this
+package is meant to be embedded in several unrelated projects, and its
+requests to archive.org should identify the library making them, not whatever
+application happens to import it.
+"""
+
+from importlib import metadata
+
+try:
+    _VERSION = metadata.version("spn-client")
+except metadata.PackageNotFoundError:  # pragma: no cover - source/dev checkout
+    _VERSION = "0.0.0"
+
+USER_AGENT = f"spn-client/{_VERSION}"
+
+DEFAULT_HEADERS = {
+    "User-Agent": USER_AGENT,
+    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    "Accept-Language": "en-US,en;q=0.9",
+}

spn_client-0.1.0/src/spn_client/_redact.py

@@ -0,0 +1,51 @@
+"""Secret-redaction helpers.
+
+Vendored from a sister project's ``ci_core.redact`` module rather than taken
+as a dependency on it — this package is deliberately decoupled from any
+project-specific shared library, and these two functions are the only pieces
+``client.py`` needs.
+"""
+
+import re
+
+# The sensitive word a credential parameter ends with. Hyphenated spellings are
+# not hypothetical: Azure OpenAI names its parameter `api-key` and Google sends
+# `X-Goog-Api-Key`. An underscore-only list matched neither, nor
+# `client_secret`, `refresh_token`, `subscription-key`, `password`, `auth` or
+# `sig` — eight of twelve real-world spellings tested on 2026-09-04 passed
+# straight through into whatever log or report the error text reached.
+_SENSITIVE_WORD = (
+    r"(?:api[-_]?key|access[-_]?token|refresh[-_]?token|id[-_]?token"
+    r"|client[-_]?secret|subscription[-_]?key|session[-_]?key"
+    r"|key|token|secret|password|passwd|credentials?|auth|signature|sig)"
+)
+
+# Any dash/underscore-separated prefix, then that word, then `=`. Anchoring the
+# end on `=` is what leaves innocent parameters alone: `author=` cannot match,
+# because `auth` would have to consume the whole name and `or` is left over.
+# `keywords=` survives for the same reason.
+_PARAM_NAME = rf"(?:[A-Za-z0-9]+[-_])*{_SENSITIVE_WORD}"
+
+# Matches ?key=..., &apiKey=..., &api-key=... in a URL and replaces the value.
+# Stops at the next &, whitespace, quote, or closing bracket so we don't eat
+# the rest of the message.
+_KEY_QUERY_RE = re.compile(
+    rf"([?&]{_PARAM_NAME}=)[^&\s'\"<>)\]]+",
+    re.IGNORECASE,
+)
+
+
+def redact_url_keys(text):
+    """Replace key/token query-parameter values in any string with [REDACTED].
+
+    Provider-agnostic: works even when the key value isn't available to compare
+    against, because it matches on the parameter name.
+    """
+    return _KEY_QUERY_RE.sub(r"\1[REDACTED]", str(text))
+
+
+def redact_value(text, secret):
+    """Replace a known secret value with [REDACTED] wherever it appears."""
+    if secret and secret in str(text):
+        return str(text).replace(secret, "[REDACTED]")
+    return str(text)