Skip to content

API reference

Generated by scripts/api_reference.py from the package's public names; do not edit by hand.

AmbiguousEntityError (exception)

An identifier matches multiple issuers.

Subclass of ProviderError.

AuthenticationError (exception)

Credentials are absent or invalid.

Subclass of ProviderError.

Company (class)

  • close(self) -> 'None': Close the provider this Company created; a provider you passed in stays open.
  • entity: The source-resolved issuer, resolved on first use.
  • filings(self, *, form: 'str | None' = None, start: 'str | date | None' = None, end: 'str | date | None' = None, include_amendments: 'bool | None' = None, limit: 'int | None' = None) -> 'FilingCollection': Filings newest first in the source's order_basis.
  • get_filing(self, filing_id: 'str', *, start: 'str | date | None' = None, end: 'str | date | None' = None, max_scan: 'int' = 500) -> 'Filing': Find one exact source ID, using a native record route when available.
  • search_result: The originally selected source candidate, if one was provided.

CompanyMatch (class)

One search result: the market and the exact identifier to pass to Company.

Fields: name, market, identifier, source, tier, tickers, isins, lei, exchange, aliases, listed_by

  • company(self, **options: 'Any') -> 'Company': Open this match's route: Company(identifier, market=..., source=...).

DownloadError (exception)

A selected original document could not be retrieved.

Subclass of ProviderError.

Entity (class)

Fields: entity_id, name, jurisdiction, provider, source_url, identifiers, tickers, exchanges, provider_metadata, provenance, requires_resolution

EntityNotFoundError (exception)

No issuer matches the supplied identifier.

Subclass of ProviderError.

ExperimentalRouteWarning (exception)

A Company was opened on a route that has not been qualified for release.

Subclass of UserWarning.

Filing (class)

Fields: filing_id, entity_id, jurisdiction, provider, regulator, source_url, provenance, filing_type_raw, filing_type_normalized, title, filing_date, published_at, index_added_at, period_start, period_end, amendment, language, provider_metadata

  • documents: Every original source document listed for this filing, verified and bound.
  • download(self, path: 'str | Path | None' = None) -> 'bytes | Path': The primary document's original bytes, or the saved path when path is given.
  • facts: Raw structured fact occurrences from this filing's original, parsed once.
  • facts_to_pandas(self): Raw facts as a DataFrame, one row per occurrence; requires the optional pandas extra.
  • find_facts(self, *, concept_raw: 'str | None' = None, period_start: 'date | None' = None, period_end: 'date | None' = None, unit: 'str | None' = None, context_id: 'str | None' = None, taxonomy: 'str | None' = None, dimensions: 'Mapping[str, str] | None' = None, limit: 'int | None' = None) -> 'list[FilingFact]': Filter occurrences by exact raw fields; no concept normalization.
  • html(self, *, encoding: 'str | None' = None) -> 'str': The primary document's original HTML/XHTML as text.
  • markdown(self, *, encoding: 'str | None' = None) -> 'str': The primary document rendered as Markdown (optional markdown extra).
  • metadata: Source metadata as a dict, dates as date objects; see to_dict() for JSON.
  • primary_document: The filing's main document: one source-flagged file, else the report role, then format.
  • raw: The source's own record for this filing, unchanged.
  • section(self, item: 'str', *, part: 'str | None' = None) -> 'FilingSection': Select one verified Item span; 10-Q Item numbers may need a Part.
  • section_references(self, item: 'str') -> 'tuple[FilingSectionReference, ...]': Return as-filed SEC 10-K Item pointers without claiming referenced content.
  • sections(self) -> 'list[FilingSection]': Return verified source sections when the provider supports this filing.
  • select_document(self, *, document_id: 'str | None' = None, document_type: 'str | None' = None, filename: 'str | None' = None, media_type: 'str | None' = None, language: 'str | None' = None, description: 'str | None' = None) -> 'FilingDocument': Select one existing representation by exact source metadata.
  • tables(self, *, encoding: 'str | None' = None) -> 'list[FilingTable]': Literal HTML/XHTML tables of the primary document, cells as filed.
  • text(self) -> 'str': Extracted text of the primary document where its format supports it.
  • to_dict(self) -> 'dict[str, Any]': JSON-safe filing metadata with its source pointers; source values are not reinterpreted.

FILING_CATEGORIES

Constant: ANNUAL, CURRENT, INTERIM, OTHER, OWNERSHIP, PROSPECTUS, QUARTERLY

FilingArchiveMember (class)

One file inside an original source ZIP; provenance stays with its package.

Fields: entry_path, source_url, provenance, size

  • download(self, path: 'str | Path | None' = None, *, max_bytes: 'int | None' = 100000000) -> 'bytes | Path': Extract one entry, limited to 100 MB by default; override explicitly.
  • filename: The member's file name inside its package.
  • html(self, *, encoding: 'str | None' = None) -> 'str': Decode one selected HTML/XHTML entry inside its original package.
  • markdown(self, *, encoding: 'str | None' = None) -> 'str': Render one selected HTML/XHTML ZIP member as Markdown.
  • members: Inspect a nested ZIP (or gzip-wrapped ZIP) without altering source bytes.
  • source_location: Package URL plus the member's path chain, for provenance.
  • tables(self, *, encoding: 'str | None' = None) -> 'list[FilingTable]': Inspect literal table tags in one selected HTML/XHTML ZIP member.
  • text(self, *, encoding: 'str | None' = None) -> 'str': Read visible HTML/XHTML text without retaining a large member buffer.

FilingCollection (class)

  • download(self, directory: 'str | Path', *, documents: 'str | tuple[str, ...]' = 'primary', file_types: 'tuple[str, ...] | None' = None, all_history: 'bool' = False) -> 'dict[str, Any]': Save this company's selected filings into directory with a resumable manifest.
  • get(self, filing_id: 'str', *, max_scan: 'int' = 500) -> 'Filing': Find an exact source ID, scanning only for bounded or non-direct sources.
  • head(self, n: 'int') -> 'list[Filing]': The first n filings in source order, read with a bounded listing.
  • latest(self, n: 'int | None' = None) -> 'Filing | list[Filing]': The newest filing in order_basis, or the newest n as a list.
  • to_pandas(self, n: 'int'): The first n filings as a DataFrame; requires the optional pandas extra.

FilingDocument (class)

Fields: document_id, filing_id, filename, source_url, provenance, media_type, document_type, language, is_primary, provider_metadata, description, role

  • download(self, path: 'str | Path | None' = None) -> 'bytes | Path': Original bytes, or stream them to path and return it; verified against the source.
  • html(self, *, encoding: 'str | None' = None) -> 'str': Decode the selected original HTML/XHTML.
  • markdown(self, *, encoding: 'str | None' = None) -> 'str': Render one selected HTML/XHTML original as Markdown on demand.
  • members: List files inside one selected original ZIP package on demand.
  • page(self, number: 'int') -> 'FilingPage': Extract one original PDF page by its one-based number.
  • pages: Every PDF page with its original page number (optional pdf extra).
  • printed_page(self, label: 'str') -> 'FilingPrintedPage': Read one SEC HTML page verified by consecutive printed footers.
  • sha256(self) -> 'str': Hash the selected original bytes, reusing a verified saved copy.
  • tables(self, *, encoding: 'str | None' = None) -> 'list[FilingTable]': Inspect literal table tags in one HTML/XHTML document.
  • text(self) -> 'str': Extracted text where the format supports it; PDFs without a text layer give empty text.
  • to_dict(self) -> 'dict[str, Any]': One JSON-safe row describing the source document, without its content.

FilingFact (class)

Fields: concept_raw, value, unit, period_start, period_end, context_id, dimensions, taxonomy, source_location, provenance, provider_metadata

  • to_dict(self) -> 'dict[str, Any]': One JSON-safe row; value stays the filed string, never a converted number.

FilingNotFoundError (exception)

No filing matches the request.

Subclass of ProviderError.

FilingPage (class)

Text from one original PDF page, retaining its document source.

Fields: number, text, document_id, source_url, provenance

  • source_location: Document URL with the page anchor, for citation.

FilingPrintedPage (class)

A verified HTML printed page, retaining its original text-line span.

Fields: label, text, document_id, source_url, start_line, end_line, provenance

FilingProvider (class)

Base class for one market's source route.

  • close(self) -> 'None': Release any provider-owned HTTP connection.
  • download_document(self, document: 'FilingDocument') -> 'bytes': Return the original bytes of exactly one selected source document.
  • extract_sections(self, filing: 'Filing') -> 'list[FilingSection]': Verified source sections for one filing, where the adapter supports them.
  • extract_text(self, document: 'FilingDocument') -> 'str': Text of one document, where its format supports it.
  • filing_date_for_filter(self, filing: 'Filing') -> 'date | None': Return the source date used by start/end filters.
  • filing_matches_form(self, filing: 'Filing', requested: 'str') -> 'bool': Match a common category or one exact native source form.
  • get_filing(self, entity: 'Entity', filing_id: 'str') -> 'Filing': Retrieve one source record directly when a verified native route exists.
  • get_primary_document(self, filing: 'Filing') -> 'FilingDocument | None': Use an already source-listed primary file when full enumeration is unnecessary.
  • info(cls, market: 'str | None' = None) -> 'ProviderInfo': This route's declared profile: tier, identifiers, forms, filters, auth.
  • iter_filings(self, entity: 'Entity', *, form: 'str | None' = None, start: 'date | None' = None, end: 'date | None' = None, include_amendments: 'bool' = True, limit: 'int | None' = None) -> 'Iterator[Filing]': Yield newest first in the documented order_basis.
  • list_documents(self, filing: 'Filing') -> 'list[FilingDocument]': List original source documents or packages for one filing.
  • raw_facts(self, filing: 'Filing') -> 'list[FilingFact]': Raw structured facts of one filing, where its original carries them.
  • resolve_entity(self, identifier: 'str') -> 'Entity': Resolve a market-scoped identifier to one regulator issuer.
  • resolve_search_result(self, candidate: 'Entity') -> 'Entity': Prepare a selected candidate whose source ID is not filing-ready.
  • save_document(self, document: 'FilingDocument', path: 'Path') -> 'Path': Stream one original document to disk when the provider supports it.
  • search_entities(self, query: 'str', *, limit: 'int' = 10) -> 'list[Entity]': Return source-listed issuer candidates without resolving each profile.
  • supports(self, capability: 'str') -> 'bool': True when the route declares the named capability.

FilingSection (class)

Source-linked Item span; items names every Item in a shared heading.

Fields: item, title, text, document_id, source_url, start_line, end_line, provenance, part, references, items

FilingSectionReference (class)

As-filed pointer near a section heading; the target is not parsed content.

Fields: kind, target, source_text, document_id, source_url, source_line, provenance

  • resolve(self, filing: 'Filing') -> 'FilingDocument | FilingPrintedPage | tuple[FilingPrintedPage, ...]': Follow a verified source pointer without merging it into section text.

FilingTable (class)

One HTML table tag in document order, without inferred column alignment.

Fields: index, caption, rows, source_url, source_location, provenance

FilingTableCell (class)

One literal HTML cell; spans are source attribute strings.

Fields: text, tag, rowspan, colspan

find_company(query: 'str', *, markets: 'Iterable[str] | None' = None, limit: 'int' = 10, live: 'bool' = True, refresh: 'bool' = False, cache_dir: 'str | Path | None' = None) -> 'list[CompanyMatch]'

Search every market for a name, ticker, securities code, ISIN or LEI.

Identifier (class)

Fields: kind, value, source_url

OpenCorpFilingsError (exception)

Base public error.

ParseError (exception)

A source document could not be parsed.

Subclass of ProviderError.

Provenance (class)

Fields: provider, regulator, jurisdiction, source_url, source_id, retrieved_at, raw

provider_info(market: 'str', *, source: 'str | None' = None) -> 'ProviderInfo'

Inspect a route's declared capabilities without credentials or network access.

ProviderError (exception)

A source rejected or could not complete an operation.

Subclass of OpenCorpFilingsError.

ProviderInfo (class)

Declared market route; individual records may have fewer usable formats.

Fields: market, provider, regulator, capabilities, tier, identifiers, forms, native_forms, date_filters, amendment_filter, order_basis, auth, coverage_note

RateLimitError (exception)

The source has limited requests.

Subclass of ProviderError.

search_companies(query: 'str', *, market: 'str', limit: 'int' = 10, provider: 'FilingProvider | None' = None, cache_dir: 'str | Path | None' = None, **provider_options: 'object') -> 'list[Entity]'

Find issuer candidates within one market, retaining source identifiers.

SourceUnavailableError (exception)

A source is temporarily unavailable after bounded retries.

Subclass of ProviderError.

supported_markets() -> 'tuple[str, ...]'

Markets with at least one implemented source route, including ESEF-only routes.

UnsupportedCapabilityError (exception)

The selected source or format cannot provide an operation.

Subclass of OpenCorpFilingsError.

UnsupportedMarketError (exception)

No source route exists for the requested market code.

Subclass of OpenCorpFilingsError, ValueError.