Metadata-Version: 2.4
Name: edgarparser-sdk
Version: 0.2.0
Summary: Typed EdgarParser SEC filings client with hosted HTTP and injected transports
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.33.1
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

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`

```bash
pip install edgarparser-sdk
```

```python
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 `TypedDict`s 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:

```python
from edgarparser import EdgarClient

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

It can also read `EDGAR_API_KEY`:

```python
from edgarparser import EdgarClient

client = EdgarClient()
```

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

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

### Injected transport

Applications can supply an independently structural synchronous transport:

```python
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. `TypedDict`s 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:

```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
```
