edgarparser-sdk 0.1.0__tar.gz

edgarparser_sdk-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+*.py[cod]
+.DS_Store

edgarparser_sdk-0.1.0/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.

edgarparser_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,93 @@
+# 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/examples/filing_search.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from edgarparser import EdgarClient
+
+
+def main() -> None:
+    client = EdgarClient()
+    payload = client.search_filing_text("AAPL", "risk", year=2025, quarter=1)
+    for hit in payload.get("hits", [])[:3]:
+        section = hit.get("section_header") or hit.get("section_key")
+        print(section, hit.get("snippet"))
+
+
+if __name__ == "__main__":
+    main()

edgarparser_sdk-0.1.0/examples/financials.py

@@ -0,0 +1,14 @@
+from __future__ import annotations
+
+from edgarparser import EdgarClient
+
+
+def main() -> None:
+    client = EdgarClient()
+    payload = client.get_financials("AAPL", year=2025, quarter=1)
+    print(payload["status"])
+    print(len(payload.get("facts", [])))
+
+
+if __name__ == "__main__":
+    main()

edgarparser_sdk-0.1.0/examples/metric_series.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from edgarparser import EdgarClient
+
+
+def main() -> None:
+    client = EdgarClient()
+    payload = client.get_metric_series(
+        "AAPL",
+        "Revenue",
+        end_year=2025,
+        end_quarter=1,
+        periods=4,
+        date_type="Q",
+    )
+    for point in payload.get("series", []):
+        print(point.get("period"), point.get("value"))
+
+
+if __name__ == "__main__":
+    main()

edgarparser_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "edgarparser-sdk"
+dynamic = ["version"]
+description = "Python SDK for the hosted EdgarParser SEC filings API"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "requests>=2.31.0",
+]
+
+[project.urls]
+Homepage = "https://www.edgarparser.com"
+Documentation = "https://docs.edgarparser.com"
+"Hosted API" = "https://www.edgarparser.com"
+"Tool Reference" = "https://docs.edgarparser.com/tools"
+Source = "https://github.com/henrysouchien/edgarparser-python"
+Issues = "https://github.com/henrysouchien/edgarparser-python/issues"
+
+[project.optional-dependencies]
+dev = [
+    "build",
+    "pytest",
+    "PyYAML",
+    "twine",
+]
+
+[tool.hatch.version]
+path = "src/edgarparser/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/edgarparser"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/edgarparser/",
+    "examples/",
+    "pyproject.toml",
+    "README.md",
+    "LICENSE",
+    "tests/",
+]

edgarparser_sdk-0.1.0/src/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_sdk-0.1.0/src/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}