edgarparser-sdk

Typed Python SDK for EdgarParser over hosted HTTP or an injected operation transport.

Status: Living reference
Current authority: packages/edgarparser/src/edgarparser/ (client.py, models.py, transport.py, _manifest.py) and packages/edgarparser/pyproject.toml

pip install edgarparser-sdk

from edgarparser import EdgarClient

client = EdgarClient(api_key="...")
print(client)

Status

edgarparser-sdk is published on PyPI as the first-party Python client for the hosted EdgarParser API. The package exports EdgarClient, the structural EdgarTransport protocol, producer-owned result TypedDicts in edgarparser.models, and typed SDK errors. Publication of a new version is separate from building this checkout's wheel; the version string alone does not establish published bytes.

The metric-series producer operation's contract is 2.1.0: the existing SDK include_equivalents option is supported on both HTTP and injected operation paths, and injected role strings are serialized as the producer's role list.

The checkout's transport/discovery API is version 0.2.0. Hatch derives the wheel version from edgarparser.__version__; no remote publication is implied.

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 performs transport and argument serialization only. It does not parse filings locally, rank metric matches, resolve tag equivalence, reinterpret numeric units, or mutate server caches as a hidden side effect. It imports no parser, API server, FastMCP, or gateway implementation.

Configuration

EdgarClient accepts an explicit API key:

from edgarparser import EdgarClient

client = EdgarClient(api_key="edgar_...")

It can also read EDGAR_API_KEY:

from edgarparser import EdgarClient

client = EdgarClient()

Default base_url is https://www.edgarparser.com. Override it for staging or local API testing:

client = EdgarClient(api_key="edgar_...", base_url="http://127.0.0.1:8000")

Injected transport

Applications can supply an independently structural synchronous transport:

from collections.abc import Mapping
from edgarparser import EdgarClient, EdgarTransport

# application_transport implements the protocol below and owns its current catalog.
client = EdgarClient(transport=application_transport)
filings = client.get_filings("AAPL", year=2024, quarter=4)
metric = client.get_metric("AAPL", "Revenue", year=2024, quarter=4)

The transport contract is:

• call(operation: str, arguments: Mapping[str, object]) -> object
• search(query: str) -> list[dict[str, object]]
• describe(operation: str) -> dict[str, object]

Operations are the producer names in _manifest.py, not HTTP paths. For example, get_metric sends ticker, metric_name, year, and quarter; a string role becomes the MCP operation's role list without changing direct HTTP serialization. Filing-facts operations use accession; native HTTP nests it under filing. Extraction class/attribute filters retain their operation shape on the injected path and become class/attr.<name> query parameters on HTTP.

Injected construction does not read EDGAR_API_KEY, retain even an explicitly supplied API key, create a session, validate HTTP configuration, or contact a service. HTTP-only constructor settings and per-call timeout overrides are not passed to operation transports. The transport is borrowed: close() and context exit mark this client closed, never close the transport or an injected session. Host errors propagate unchanged, with no HTTP fallback.

search() and describe() delegate on every call to the injected transport's current effective catalog, including newly offered operations. The client does not cache grants or apply its own authority filter. Invocation permission remains the transport/catalog owner's responsibility; a method existing on the package does not grant access. Native HTTP discovery describes the installed SDK contract, not the service's current grants; API authorization remains server-owned.

Read methods return complete decoded result dictionaries unchanged, including unknown fields, nested citation/source identities, coverage, quantity/display semantics, and calculation-readiness metadata. TypedDicts document stable fields and partial-response variants; they do not validate, project, or rebuild results at runtime.

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
• get_filing_facts
• get_concept
• compare_concept
• concept_trend
• cite_concept
• get_event_filings
• describe_filing
• get_filing_sections (inline reads; no file/artifact extraction mode)
• get_filing_cover_facts
• get_filing_tables
• search_filing_tables (no index-rebuild request)
• compare_filing_tables (no index-rebuild request)
• search_extractions (existing cached spans)
• get_extraction_series (existing cached spans)
• list_extraction_schemas
• get_operational_kpi_driver_rows (versioned producer rows, not the research tool)
• warm_metric_cache
• warm_metric_cache_status

The two warming methods remain for existing HTTP users. This package does not make them code-callable in an application's catalog. New extraction/LLM, ingestion, administration, webhook, internal-restatement, and mutation operations are not added to the SDK read surface.

get_issuer_submissions_meta is currently MCP-only and is unavailable as an SDK method until it has a supported transport-neutral contract. The API-only get_tag_equivalence_registry is likewise not advertised as an injected operation. No native unsupported-method stubs or server imports stand in for either contract.

Arguments follow the producer contract: get_filings requires ticker/year/quarter (not a CIK/limit shortcut); concept/extraction ranges use fiscal period strings such as 2023-FY or 2024-Q1. Use search_metrics/list_metrics to discover exact metric names, and statement/concept output for registry concept names. Cache and tier behavior remain producer-owned; cache-only reads do not silently warm missing data.

Examples

From packages/edgarparser/ or the synced package repo, run examples with EDGAR_API_KEY set:

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:

python -m pip install -e packages/edgarparser
python -m pytest packages/edgarparser/tests -q