edgarparser-sdk 0.1.0__py3-none-any.whl

edgarparser/__init__.py

@@ -0,0 +1,30 @@
+"""Python SDK for the hosted EdgarParser API."""
+
+from .client import DEFAULT_BASE_URL, DEFAULT_TIMEOUT, EdgarClient
+from .errors import (
+    EdgarAPIError,
+    EdgarAuthError,
+    EdgarError,
+    EdgarNotFoundError,
+    EdgarRateLimitError,
+    EdgarTimeoutError,
+    EdgarTransportError,
+    EdgarValidationError,
+)
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "EdgarAPIError",
+    "EdgarAuthError",
+    "EdgarClient",
+    "EdgarError",
+    "EdgarNotFoundError",
+    "EdgarRateLimitError",
+    "EdgarTimeoutError",
+    "EdgarTransportError",
+    "EdgarValidationError",
+    "__version__",
+]
+
+__version__ = "0.1.0"

edgarparser/_manifest.py

@@ -0,0 +1,175 @@
+"""Pinned API contract metadata for SDK-covered EdgarParser endpoints."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SDKMethodSpec:
+    sdk_method: str
+    tool_name: str
+    api_method: str
+    api_path: str
+    contract_version: str
+    schema_fingerprint: str
+    required_params: tuple[str, ...] = ()
+    optional_params: tuple[str, ...] = ()
+    path_params: tuple[str, ...] = ()
+    body_params: tuple[str, ...] = ()
+
+
+SDK_METHODS: tuple[SDKMethodSpec, ...] = (
+    SDKMethodSpec(
+        sdk_method="get_financials",
+        tool_name="get_financials",
+        api_method="GET",
+        api_path="/api/financials",
+        contract_version="1.0.0",
+        schema_fingerprint="sha256:8c2b5486165eb2628dfb324c558c1148a48a46453f4102f0491e16503316b1c5",
+        required_params=("ticker", "year", "quarter"),
+        optional_params=("full_year_mode", "source"),
+    ),
+    SDKMethodSpec(
+        sdk_method="get_metric",
+        tool_name="get_metric",
+        api_method="GET",
+        api_path="/api/metric",
+        contract_version="1.0.0",
+        schema_fingerprint="sha256:0350ec893a5d3a2a2510dc059711a93f6ec9665a0e068b32d8c4b2d8cb8accd8",
+        required_params=("ticker", "year", "quarter", "metric_name"),
+        optional_params=("full_year_mode", "source", "date_type", "role"),
+    ),
+    SDKMethodSpec(
+        sdk_method="get_metric_series",
+        tool_name="get_metric_series",
+        api_method="GET",
+        api_path="/api/metric/series",
+        contract_version="1.1.0",
+        schema_fingerprint="sha256:dff62ae8bf4eb8c648776ac91e02e324c83a1cccbf3beeefcb7855272970a906",
+        required_params=("ticker", "metric_name", "end_year", "end_quarter"),
+        optional_params=(
+            "periods",
+            "full_year_mode",
+            "source",
+            "date_type",
+            "include_equivalents",
+            "cached_only",
+            "role",
+            "axis_key",
+        ),
+    ),
+    SDKMethodSpec(
+        sdk_method="list_metrics",
+        tool_name="list_metrics",
+        api_method="GET",
+        api_path="/api/financials/list_metrics",
+        contract_version="1.0.0",
+        schema_fingerprint="sha256:07341bd265a257b8c90ee99b42ecef054e6eaa16c2f341f91ffae287bfe907d8",
+        required_params=("ticker", "year", "quarter"),
+        optional_params=(
+            "full_year_mode",
+            "source",
+            "date_type",
+            "limit",
+            "include_values",
+        ),
+    ),
+    SDKMethodSpec(
+        sdk_method="search_metrics",
+        tool_name="search_metrics",
+        api_method="GET",
+        api_path="/api/financials/search_metrics",
+        contract_version="1.0.0",
+        schema_fingerprint="sha256:381c0bf743038780d55c447b0c7103da0e22d13c33b866c73130b7265071853c",
+        required_params=("ticker", "year", "quarter", "query"),
+        optional_params=(
+            "full_year_mode",
+            "source",
+            "date_type",
+            "role",
+            "limit",
+            "include_values",
+        ),
+    ),
+    SDKMethodSpec(
+        sdk_method="get_statement",
+        tool_name="get_statement",
+        api_method="GET",
+        api_path="/api/statement",
+        contract_version="1.0.0",
+        schema_fingerprint="sha256:6da91e176e78fe536130ed3ea11cf9b8dfccf923cbbfc47483d7cb2108383986",
+        required_params=("ticker", "statement"),
+        optional_params=(
+            "year",
+            "quarter",
+            "full_year_mode",
+            "period_from",
+            "period_to",
+            "source",
+            "date_type",
+        ),
+    ),
+    SDKMethodSpec(
+        sdk_method="get_filings",
+        tool_name="get_filings",
+        api_method="GET",
+        api_path="/api/filings",
+        contract_version="1.0.0",
+        schema_fingerprint="sha256:ffa7e669b836cbbc181bc337cb55219e55bf9a5c75ce3d27040a8aad25f8c993",
+        required_params=("ticker", "year", "quarter"),
+        optional_params=("source",),
+    ),
+    SDKMethodSpec(
+        sdk_method="get_filing_document",
+        tool_name="get_filing_document",
+        api_method="GET",
+        api_path="/api/filing/document",
+        contract_version="1.0.0",
+        schema_fingerprint="sha256:4d559aded5c9760ccb498944a984a128254a76349348de297da30ee338ff123a",
+        optional_params=(
+            "ticker",
+            "year",
+            "quarter",
+            "source",
+            "accession",
+            "cik",
+            "form_type",
+            "primary_document",
+            "sections",
+            "char_start",
+            "char_end",
+            "max_chars",
+        ),
+    ),
+    SDKMethodSpec(
+        sdk_method="search_filing_text",
+        tool_name="search_filing_text",
+        api_method="GET",
+        api_path="/api/filing/text/search",
+        contract_version="1.0.0",
+        schema_fingerprint="sha256:be08198a156e55118e9b32a0fb41ead07906469059fb27d3010f1a1f5a9c0c8c",
+        required_params=("ticker", "year", "quarter", "query"),
+        optional_params=("source",),
+    ),
+    SDKMethodSpec(
+        sdk_method="warm_metric_cache",
+        tool_name="warm_metric_cache",
+        api_method="POST",
+        api_path="/api/warm",
+        contract_version="1.0.0",
+        schema_fingerprint="sha256:1636aba36d166ecf2901e72078fc8a6182f7174e541d9183561392781e8f8cbd",
+        body_params=("items",),
+    ),
+    SDKMethodSpec(
+        sdk_method="warm_metric_cache_status",
+        tool_name="warm_metric_cache_status",
+        api_method="GET",
+        api_path="/api/warm/{job_id}",
+        contract_version="1.0.0",
+        schema_fingerprint="sha256:f48e0b9a707e404c640822af06d51f3523f54538fed625a24ee06dc220cb3245",
+        path_params=("job_id",),
+    ),
+)
+
+SDK_METHODS_BY_NAME = {spec.sdk_method: spec for spec in SDK_METHODS}

edgarparser/client.py

@@ -0,0 +1,663 @@
+"""Client scaffold for the hosted EdgarParser API."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping, Sequence
+from types import TracebackType
+from typing import Any
+from urllib.parse import quote
+
+import requests
+
+from .errors import (
+    EdgarAPIError,
+    EdgarAuthError,
+    EdgarError,
+    EdgarNotFoundError,
+    EdgarRateLimitError,
+    EdgarTimeoutError,
+    EdgarTransportError,
+    EdgarValidationError,
+)
+
+DEFAULT_BASE_URL = "https://www.edgarparser.com"
+DEFAULT_TIMEOUT = 30.0
+_REDACTED = "<redacted>"
+_SECRET_FIELD_MARKERS = (
+    "authorization",
+    "api_key",
+    "apikey",
+    "cookie",
+    "password",
+    "token",
+    "secret",
+)
+
+
+class EdgarClient:
+    """Thin HTTP client for the hosted EdgarParser API."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        session: requests.Session | None = None,
+    ) -> None:
+        if not base_url or not base_url.strip():
+            raise ValueError("base_url must be a non-empty URL")
+        if timeout <= 0:
+            raise ValueError("timeout must be positive")
+
+        self.api_key = api_key if api_key is not None else os.getenv("EDGAR_API_KEY")
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = session if session is not None else requests.Session()
+        self._owns_session = session is None
+        self._closed = False
+
+    @property
+    def user_agent(self) -> str:
+        from . import __version__
+
+        return f"edgarparser-sdk/{__version__}"
+
+    def headers(self) -> dict[str, str]:
+        headers = {"User-Agent": self.user_agent}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def get_financials(
+        self,
+        ticker: str,
+        *,
+        year: int,
+        quarter: int,
+        full_year_mode: bool = False,
+        source: str = "auto",
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        return self._request(
+            "GET",
+            "/api/financials",
+            params={
+                "ticker": ticker,
+                "year": year,
+                "quarter": quarter,
+                "full_year_mode": full_year_mode,
+                "source": source,
+            },
+            timeout=timeout,
+        )
+
+    def get_metric(
+        self,
+        ticker: str,
+        metric_name: str,
+        *,
+        year: int,
+        quarter: int,
+        full_year_mode: bool = False,
+        source: str = "auto",
+        date_type: str | None = None,
+        role: str | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        return self._request(
+            "GET",
+            "/api/metric",
+            params=self._clean_params(
+                {
+                    "ticker": ticker,
+                    "year": year,
+                    "quarter": quarter,
+                    "metric_name": metric_name,
+                    "full_year_mode": full_year_mode,
+                    "source": source,
+                    "date_type": date_type,
+                    "role": role,
+                }
+            ),
+            timeout=timeout,
+        )
+
+    def get_metric_series(
+        self,
+        ticker: str,
+        metric_name: str,
+        *,
+        end_year: int,
+        end_quarter: int,
+        periods: int = 8,
+        full_year_mode: bool = False,
+        source: str = "auto",
+        date_type: str | None = None,
+        include_equivalents: bool = False,
+        cached_only: bool = False,
+        role: str | None = None,
+        axis_key: str | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        return self._request(
+            "GET",
+            "/api/metric/series",
+            params=self._clean_params(
+                {
+                    "ticker": ticker,
+                    "metric_name": metric_name,
+                    "end_year": end_year,
+                    "end_quarter": end_quarter,
+                    "periods": periods,
+                    "full_year_mode": full_year_mode,
+                    "source": source,
+                    "date_type": date_type,
+                    "include_equivalents": include_equivalents,
+                    "cached_only": cached_only,
+                    "role": role,
+                    "axis_key": axis_key,
+                }
+            ),
+            timeout=timeout,
+        )
+
+    def list_metrics(
+        self,
+        ticker: str,
+        *,
+        year: int,
+        quarter: int,
+        full_year_mode: bool = False,
+        source: str = "auto",
+        date_type: str | None = None,
+        limit: int = 200,
+        include_values: bool = True,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        return self._request(
+            "GET",
+            "/api/financials/list_metrics",
+            params=self._clean_params(
+                {
+                    "ticker": ticker,
+                    "year": year,
+                    "quarter": quarter,
+                    "full_year_mode": full_year_mode,
+                    "source": source,
+                    "date_type": date_type,
+                    "limit": limit,
+                    "include_values": include_values,
+                }
+            ),
+            timeout=timeout,
+        )
+
+    def search_metrics(
+        self,
+        ticker: str,
+        query: str,
+        *,
+        year: int,
+        quarter: int,
+        full_year_mode: bool = False,
+        source: str = "auto",
+        date_type: str | None = None,
+        role: str | Sequence[str] | None = None,
+        limit: int = 20,
+        include_values: bool = True,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        return self._request(
+            "GET",
+            "/api/financials/search_metrics",
+            params=self._clean_params(
+                {
+                    "ticker": ticker,
+                    "year": year,
+                    "quarter": quarter,
+                    "query": query,
+                    "full_year_mode": full_year_mode,
+                    "source": source,
+                    "date_type": date_type,
+                    "role": self._role_values(role),
+                    "limit": limit,
+                    "include_values": include_values,
+                }
+            ),
+            timeout=timeout,
+        )
+
+    def get_statement(
+        self,
+        ticker: str,
+        statement: str,
+        *,
+        year: int | None = None,
+        quarter: int | None = None,
+        full_year_mode: bool = False,
+        period_from: str | None = None,
+        period_to: str | None = None,
+        source: str = "auto",
+        date_type: str | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        return self._request(
+            "GET",
+            "/api/statement",
+            params=self._clean_params(
+                {
+                    "ticker": ticker,
+                    "statement": statement,
+                    "year": year,
+                    "quarter": quarter,
+                    "full_year_mode": full_year_mode,
+                    "period_from": period_from,
+                    "period_to": period_to,
+                    "source": source,
+                    "date_type": date_type,
+                }
+            ),
+            timeout=timeout,
+        )
+
+    def get_filings(
+        self,
+        ticker: str,
+        *,
+        year: int,
+        quarter: int,
+        source: str = "auto",
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        return self._request(
+            "GET",
+            "/api/filings",
+            params={
+                "ticker": ticker,
+                "year": year,
+                "quarter": quarter,
+                "source": source,
+            },
+            timeout=timeout,
+        )
+
+    def get_filing_document(
+        self,
+        *,
+        ticker: str | None = None,
+        year: int | None = None,
+        quarter: int | None = None,
+        source: str = "auto",
+        accession: str | None = None,
+        cik: str | None = None,
+        form_type: str | None = None,
+        primary_document: str | None = None,
+        sections: str | None = None,
+        char_start: int | None = None,
+        char_end: int | None = None,
+        max_chars: int = 200000,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        return self._request(
+            "GET",
+            "/api/filing/document",
+            params=self._clean_params(
+                {
+                    "ticker": ticker,
+                    "year": year,
+                    "quarter": quarter,
+                    "source": source,
+                    "accession": accession,
+                    "cik": cik,
+                    "form_type": form_type,
+                    "primary_document": primary_document,
+                    "sections": sections,
+                    "char_start": char_start,
+                    "char_end": char_end,
+                    "max_chars": max_chars,
+                }
+            ),
+            timeout=timeout,
+        )
+
+    def search_filing_text(
+        self,
+        ticker: str,
+        query: str,
+        *,
+        year: int,
+        quarter: int,
+        source: str = "auto",
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        return self._request(
+            "GET",
+            "/api/filing/text/search",
+            params={
+                "ticker": ticker,
+                "year": year,
+                "quarter": quarter,
+                "source": source,
+                "query": query,
+            },
+            timeout=timeout,
+        )
+
+    def warm_metric_cache(
+        self,
+        items: Sequence[Mapping[str, Any]] | None = None,
+        *,
+        ticker: str | None = None,
+        year: int | None = None,
+        quarter: int | None = None,
+        full_year_mode: bool = False,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        payload_items = self._warm_items(
+            items,
+            ticker=ticker,
+            year=year,
+            quarter=quarter,
+            full_year_mode=full_year_mode,
+        )
+        return self._request(
+            "POST",
+            "/api/warm",
+            json={"items": payload_items},
+            timeout=timeout,
+        )
+
+    def warm_metric_cache_status(
+        self,
+        job_id: str,
+        *,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        if not job_id or not job_id.strip():
+            raise ValueError("job_id must be non-empty")
+        encoded_job_id = quote(job_id.strip(), safe="")
+        return self._request("GET", f"/api/warm/{encoded_job_id}", timeout=timeout)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Mapping[str, Any] | None = None,
+        timeout: float | None = None,
+    ) -> Any:
+        if self._closed:
+            raise EdgarError("client is closed")
+        if timeout is not None and timeout <= 0:
+            raise ValueError("timeout must be positive")
+
+        normalized_method = method.upper()
+        url = self._url(path)
+        request_metadata = self._request_metadata(
+            normalized_method,
+            url,
+            params=params,
+            json=json,
+        )
+
+        try:
+            response = self._session.request(
+                normalized_method,
+                url,
+                headers=self.headers(),
+                params=dict(params or {}),
+                json=dict(json or {}) if json is not None else None,
+                timeout=timeout or self.timeout,
+            )
+        except requests.Timeout as exc:
+            raise EdgarTimeoutError(request=request_metadata) from exc
+        except requests.RequestException as exc:
+            message = self._redact_text(str(exc) or "Request failed")
+            raise EdgarTransportError(message, request=request_metadata) from exc
+
+        response_metadata = self._response_metadata(response)
+        if response.status_code >= 400:
+            raise self._api_error_from_response(
+                response,
+                request=request_metadata,
+                response_metadata=response_metadata,
+            )
+
+        try:
+            return response.json()
+        except ValueError as exc:
+            raise EdgarAPIError(
+                response.status_code,
+                "Response was not valid JSON",
+                error_type="invalid_json",
+                details=self._text_details(response.text),
+                request_id=response.headers.get("X-Request-ID"),
+                request=request_metadata,
+                response=response_metadata,
+            ) from exc
+
+    def close(self) -> None:
+        if self._closed:
+            return
+        if self._owns_session:
+            self._session.close()
+        self._closed = True
+
+    def __enter__(self) -> EdgarClient:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        del exc_type, exc, traceback
+        self.close()
+
+    def __repr__(self) -> str:
+        key_state = "set" if self.api_key else "unset"
+        return (
+            f"{self.__class__.__name__}("
+            f"base_url={self.base_url!r}, "
+            f"timeout={self.timeout!r}, "
+            f"api_key=<{key_state}>"
+            ")"
+        )
+
+    def _debug_state(self) -> dict[str, Any]:
+        """Return non-secret state for tests and diagnostics."""
+
+        return {
+            "base_url": self.base_url,
+            "timeout": self.timeout,
+            "api_key_set": bool(self.api_key),
+            "closed": self._closed,
+            "user_agent": self.user_agent,
+        }
+
+    def _url(self, path: str) -> str:
+        if not path or not path.strip():
+            raise ValueError("path must be a non-empty API path")
+        return f"{self.base_url}/{path.lstrip('/')}"
+
+    def _clean_params(self, params: Mapping[str, Any]) -> dict[str, Any]:
+        return {key: value for key, value in params.items() if value is not None}
+
+    def _warm_items(
+        self,
+        items: Sequence[Mapping[str, Any]] | None,
+        *,
+        ticker: str | None,
+        year: int | None,
+        quarter: int | None,
+        full_year_mode: bool,
+    ) -> list[dict[str, Any]]:
+        if items is not None:
+            if not items:
+                raise ValueError("items must contain at least one warm request")
+            return [dict(item) for item in items]
+        if ticker is None or year is None or quarter is None:
+            raise ValueError("provide items or ticker, year, and quarter")
+        return [
+            {
+                "ticker": ticker,
+                "year": year,
+                "quarter": quarter,
+                "full_year_mode": full_year_mode,
+            }
+        ]
+
+    def _role_values(self, role: str | Sequence[str] | None) -> str | list[str] | None:
+        if role is None:
+            return None
+        if isinstance(role, str):
+            return role
+        return list(role)
+
+    def _request_metadata(
+        self,
+        method: str,
+        url: str,
+        *,
+        params: Mapping[str, Any] | None,
+        json: Mapping[str, Any] | None,
+    ) -> dict[str, Any]:
+        return {
+            "method": method,
+            "url": url,
+            "headers": self._redact_mapping(self.headers()),
+            "params": self._redact_mapping(params or {}),
+            "json": self._redact_mapping(json or {}),
+        }
+
+    def _response_metadata(self, response: requests.Response) -> dict[str, Any]:
+        response_url = getattr(response, "url", None)
+        return {
+            "status_code": response.status_code,
+            "url": (
+                self._redact_text(response_url)
+                if isinstance(response_url, str)
+                else response_url
+            ),
+            "headers": self._redact_mapping(dict(response.headers)),
+        }
+
+    def _api_error_from_response(
+        self,
+        response: requests.Response,
+        *,
+        request: Mapping[str, Any],
+        response_metadata: Mapping[str, Any],
+    ) -> EdgarAPIError:
+        payload = self._response_json(response)
+        message = f"HTTP {response.status_code}"
+        error_type: str | None = self._default_error_type(response.status_code)
+        details: Any | None = None
+
+        if isinstance(payload, Mapping):
+            message = self._redact_text(
+                str(payload.get("message") or payload.get("error") or message)
+            )
+            error_type = (
+                str(payload["error_type"])
+                if payload.get("error_type") is not None
+                else error_type
+            )
+            details = self._redact_value(self._details_from_payload(payload))
+        else:
+            error_type = "non_json_error"
+            text = self._redact_text(response.text.strip())
+            if text:
+                message = text[:300]
+                details = self._text_details(text)
+
+        error_cls = self._error_class(response.status_code)
+        return error_cls(
+            response.status_code,
+            message,
+            error_type=error_type,
+            details=details,
+            request_id=response.headers.get("X-Request-ID"),
+            request=request,
+            response=response_metadata,
+        )
+
+    def _response_json(self, response: requests.Response) -> Any:
+        try:
+            return response.json()
+        except ValueError:
+            return None
+
+    def _details_from_payload(self, payload: Mapping[str, Any]) -> Any | None:
+        details = payload.get("details")
+        if details is None and "detail" in payload:
+            details = {"detail": payload["detail"]}
+        if "cta" not in payload:
+            return details
+        if details is None:
+            return {"cta": payload["cta"]}
+        if isinstance(details, dict):
+            return {**details, "cta": payload["cta"]}
+        return {"details": details, "cta": payload["cta"]}
+
+    def _default_error_type(self, status_code: int) -> str | None:
+        if status_code == 429:
+            return "rate_limit"
+        if status_code in {400, 422}:
+            return "validation_error"
+        if status_code in {401, 403}:
+            return "auth_error"
+        if status_code == 404:
+            return "not_found"
+        return None
+
+    def _error_class(self, status_code: int) -> type[EdgarAPIError]:
+        if status_code in {401, 403}:
+            return EdgarAuthError
+        if status_code == 429:
+            return EdgarRateLimitError
+        if status_code == 404:
+            return EdgarNotFoundError
+        if status_code in {400, 422}:
+            return EdgarValidationError
+        return EdgarAPIError
+
+    def _text_details(self, text: str) -> dict[str, str] | None:
+        if not text:
+            return None
+        return {"text": self._redact_text(text)[:500]}
+
+    def _redact_mapping(self, value: Mapping[str, Any]) -> dict[str, Any]:
+        redacted: dict[str, Any] = {}
+        for key, item in value.items():
+            if self._is_secret_key(key):
+                redacted[str(key)] = _REDACTED
+            else:
+                redacted[str(key)] = self._redact_value(item)
+        return redacted
+
+    def _redact_value(self, value: Any) -> Any:
+        if isinstance(value, Mapping):
+            return self._redact_mapping(value)
+        if isinstance(value, list):
+            return [self._redact_value(item) for item in value]
+        if isinstance(value, str):
+            return self._redact_text(value)
+        return value
+
+    def _is_secret_key(self, key: object) -> bool:
+        normalized = str(key).lower().replace("-", "_")
+        return (
+            normalized == "key"
+            or normalized.endswith("_key")
+            or any(marker in normalized for marker in _SECRET_FIELD_MARKERS)
+        )
+
+    def _redact_text(self, text: str) -> str:
+        if self.api_key and len(self.api_key) >= 4:
+            return text.replace(self.api_key, _REDACTED)
+        return text

edgarparser/errors.py

@@ -0,0 +1,77 @@
+"""Typed exceptions for the EdgarParser SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+
+class EdgarError(Exception):
+    """Base exception for all SDK errors."""
+
+
+class EdgarTimeoutError(EdgarError):
+    """Raised when an API request times out."""
+
+    def __init__(
+        self,
+        message: str = "Request timed out",
+        *,
+        request: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.request = dict(request or {})
+
+
+class EdgarTransportError(EdgarError):
+    """Raised when the HTTP transport fails before receiving a response."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        request: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.request = dict(request or {})
+
+
+class EdgarAPIError(EdgarError):
+    """Raised for API responses that are errors or cannot be parsed."""
+
+    def __init__(
+        self,
+        status_code: int,
+        message: str,
+        *,
+        error_type: str | None = None,
+        details: Any | None = None,
+        request_id: str | None = None,
+        request: Mapping[str, Any] | None = None,
+        response: Mapping[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.message = message
+        self.error_type = error_type
+        self.details = details
+        self.request_id = request_id
+        self.request = dict(request or {})
+        self.response = dict(response or {})
+
+
+class EdgarAuthError(EdgarAPIError):
+    """Raised for authentication and authorization errors."""
+
+
+class EdgarRateLimitError(EdgarAPIError):
+    """Raised for rate-limit errors."""
+
+
+class EdgarValidationError(EdgarAPIError):
+    """Raised for request validation errors."""
+
+
+class EdgarNotFoundError(EdgarAPIError):
+    """Raised when the requested API resource is not found."""

edgarparser/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561 typing support.

edgarparser_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: edgarparser-sdk
+Version: 0.1.0
+Summary: Python SDK for the hosted EdgarParser SEC filings API
+Project-URL: Homepage, https://www.edgarparser.com
+Project-URL: Documentation, https://docs.edgarparser.com
+Project-URL: Hosted API, https://www.edgarparser.com
+Project-URL: Tool Reference, https://docs.edgarparser.com/tools
+Project-URL: Source, https://github.com/henrysouchien/edgarparser-python
+Project-URL: Issues, https://github.com/henrysouchien/edgarparser-python/issues
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pyyaml; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# edgarparser-sdk
+
+Python SDK for the hosted EdgarParser API.
+
+```bash
+pip install edgarparser-sdk
+```
+
+```python
+from edgarparser import EdgarClient
+
+client = EdgarClient(api_key="...")
+print(client)
+```
+
+## Status
+
+This package is being implemented in the EdgarParser source repo and is not
+published yet. The current local package exports `EdgarClient`, typed SDK
+errors, and the first v1 hosted-API endpoint methods.
+
+## Package Boundary
+
+Install `edgarparser-sdk` and import `edgarparser` when you want the hosted
+EdgarParser API from Python.
+
+Use `edgar-parser` when you want the local parsing library.
+
+Use `edgar-mcp` when you want AI-agent tools over the hosted API.
+
+The SDK is intentionally a thin HTTP client. It should not parse filings
+locally, rank metric matches, resolve tag equivalence, or mutate server caches
+as a hidden side effect.
+
+## Configuration
+
+`EdgarClient` accepts an explicit API key:
+
+```python
+from edgarparser import EdgarClient
+
+client = EdgarClient(api_key="edgar_...")
+```
+
+It can also read `EDGAR_API_KEY`:
+
+```python
+from edgarparser import EdgarClient
+
+client = EdgarClient()
+```
+
+Use `base_url` for staging or local API testing:
+
+```python
+client = EdgarClient(api_key="edgar_...", base_url="http://127.0.0.1:8000")
+```
+
+## V1 Methods
+
+The current local SDK surface includes:
+
+- `get_financials`
+- `get_metric`
+- `get_metric_series`
+- `list_metrics`
+- `search_metrics`
+- `get_statement`
+- `get_filings`
+- `get_filing_document`
+- `search_filing_text`
+- `warm_metric_cache`
+- `warm_metric_cache_status`
+
+## Examples
+
+From `packages/edgarparser/` or the synced package repo, run examples with
+`EDGAR_API_KEY` set:
+
+```bash
+EDGAR_API_KEY=... python examples/financials.py
+EDGAR_API_KEY=... python examples/metric_series.py
+EDGAR_API_KEY=... python examples/filing_search.py
+```
+
+## Development
+
+From the repo root:
+
+```bash
+python -m pip install -e packages/edgarparser
+python -m pytest packages/edgarparser/tests -q
+```

edgarparser_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+edgarparser/__init__.py,sha256=VNp5Tyj4b5FJi73Hv85j1tXhnpWZsiPNSBdFLPHp170,636
+edgarparser/_manifest.py,sha256=cBvx3wQjJHPMvjoFa3DR6p2CDP33NrsS4SSbKDIDxP4,5816
+edgarparser/client.py,sha256=08RRM_tln9tGj7Y15obKA_Xnv6VuM9ypnBdh2vxQ9Dk,20408
+edgarparser/errors.py,sha256=DKq262VbNNzGwzHzHjiwZO5JzuHM0ZwUDkQ0H775--U,2007
+edgarparser/py.typed,sha256=0VrMqa_u6HfLYNPxflMqTVvjIovV_taKM7nltQcS1TA,42
+edgarparser_sdk-0.1.0.dist-info/METADATA,sha256=st83AW-9y-_G3Qu52mTIjnRmyyCzveIPhZUsu9nbLVA,2771
+edgarparser_sdk-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+edgarparser_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=3SuIgQXssHX7NSO3otrkAeSPGz59jsRzpHjumfn7Ajw,1073
+edgarparser_sdk-0.1.0.dist-info/RECORD,,

edgarparser_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

edgarparser_sdk-0.1.0.dist-info/licenses/LICENSE

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