Data Classes

Type stub file for edgar_data module.

class edgar_sec.edgar_data.Address(address_type, street1, street2, city, state_or_country, zipcode, state_or_country_description)

Bases: object

A class representing an address from SEC filing data.

address_type

The type of address (e.g., ‘mailing’, ‘business’).

Type:

str

street1

The primary street address line.

Type:

str

street2

The secondary street address line, if any.

Type:

str

city

The city name.

Type:

str

state_or_country

The state or country code.

Type:

str

zipcode

The postal code.

Type:

str

state_or_country_description

The full name of the state or country.

Type:

str

Returns:

An object containing formatted address information.

Return type:

Address

Note

The address_type is typically provided by the key name in the SEC API response and is passed separately to the from_dict method.

address_type: str

city: str

classmethod from_dict(address_type, data)

Parses a dictionary and returns an Address object.

Return type:

Address

state_or_country: str

state_or_country_description: str

street1: str

street2: str

zipcode: str

class edgar_sec.edgar_data.CompanyConcept(cik, taxonomy, tag, label, description, entity_name, units)

Bases: object

A class representing a specific financial concept for a company from SEC filings.

cik

Central Index Key (CIK) of the entity, a unique identifier assigned by the SEC.

Type:

str

taxonomy

The reporting taxonomy used (e.g., ‘us-gaap’, ‘dei’, ‘srt’).

Type:

str

tag

The specific concept tag or account name (e.g., ‘Assets’, ‘Revenue’, ‘EarningsPerShare’).

Type:

str

label

Human-readable label describing the financial concept.

Type:

str

description

Detailed explanation of what the financial concept represents.

Type:

str

entity_name

Legal name of the reporting entity.

Type:

str

units

Individual disclosure values across different time periods.

Type:

Union[UnitDisclosure, List[UnitDisclosure]]

Returns:

An object containing all instances of a specific financial concept reported by a company.

Return type:

CompanyConcept

Note

This class provides time-series data for a single financial concept across multiple reporting periods. The taxonomy and tag parameters define which specific financial data point is being represented. Common taxonomies include ‘us-gaap’ (US GAAP accounting standards), ‘ifrs’ (International standards), and ‘dei’ (Document and Entity Information).

cik: str

description: str

entity_name: str

classmethod from_api_response(response)

Parses EDGAR API response and returns a single CompanyConcept.

Return type:

CompanyConcept

label: str

tag: str

taxonomy: str

units: Union[UnitDisclosure, List[UnitDisclosure]]

class edgar_sec.edgar_data.CompanyFact(cik, entity_name, facts)

Bases: object

A class representing the complete collection of financial facts for a company from SEC filings.

cik

Central Index Key (CIK) of the entity, a unique identifier assigned by the SEC.

Type:

str

entity_name

Legal name of the reporting entity.

Type:

str

facts

A dictionary mapping taxonomy identifiers to their corresponding Fact objects.

Type:

Dict[str, Fact]

Returns:

An object containing all financial facts reported by a company across all taxonomies.

Return type:

CompanyFact

Note

This class represents the highest level container for all financial data for a company, organized hierarchically by taxonomy, concept, and unit. It provides access to the complete set of financial disclosures that an entity has filed with the SEC in machine-readable XBRL format, enabling time-series analysis of financial metrics.

cik: str

entity_name: str

facts: Dict[str, Fact]

classmethod from_api_response(response)

Parses EDGAR API response and returns a single CompanyFacts.

Return type:

CompanyFact

class edgar_sec.edgar_data.EntityDisclosure(name, label, description, units)

Bases: object

A class representing a specific financial concept disclosure for an entity.

name

The name of the concept tag (e.g., ‘Assets’, ‘Revenue’, ‘CommonStockSharesOutstanding’).

Type:

str

label

Human-readable label describing the financial concept.

Type:

str

description

Detailed explanation of what the financial concept represents.

Type:

str

units

A dictionary mapping unit types to lists of disclosure values across different reporting periods.

Type:

Dict[str, List[UnitDisclosure]]

Returns:

An object containing all disclosures of a specific financial concept, organized by unit type.

Return type:

EntityDisclosure

Note

This class organizes financial concept data by unit of measurement (like USD, shares, etc.) to accommodate concepts that might be reported in multiple units across different periods. The name parameter represents the specific XBRL tag or concept identifier.

description: str

classmethod from_dict(name, data)

Parses an entity disclosure from the API response.

Return type:

EntityDisclosure

label: str

name: str

units: Dict[str, List[UnitDisclosure]]

class edgar_sec.edgar_data.Fact(taxonomy, disclosures)

Bases: object

A class representing a collection of financial disclosures for a specific taxonomy.

taxonomy

The reporting taxonomy identifier (e.g., ‘us-gaap’, ‘dei’, ‘ifrs’).

Type:

str

disclosures

A dictionary mapping concept tag names to their corresponding disclosure objects.

Type:

Dict[str, EntityDisclosure]

Returns:

An object containing all disclosures within a specific taxonomy for an entity.

Return type:

Fact

Note

This class organizes financial data hierarchically by taxonomy, representing a collection of related financial concepts under a specific accounting standard or reporting framework. Common taxonomies include ‘us-gaap’ (US GAAP accounting standards), ‘ifrs’ (International standards), and ‘dei’ (Document and Entity Information).

disclosures: Dict[str, EntityDisclosure]

classmethod from_dict(taxonomy, data)

Parses a taxonomy fact from the API response.

Return type:

Fact

taxonomy: str

class edgar_sec.edgar_data.File(name, filing_count, filing_from, filing_to)

Bases: object

A class representing a file reference in SEC EDGAR submission history.

name

The filename of the additional submission history file.

Type:

str

filing_count

The number of filings contained in the referenced file.

Type:

int

filing_from

The earliest filing date covered in this file, in YYYY-MM-DD format.

Type:

str

filing_to

The latest filing date covered in this file, in YYYY-MM-DD format.

Type:

str

Returns:

An object containing information about a submission history file reference.

Return type:

File

Note

The SEC EDGAR API typically returns the most recent submissions directly in the response, with references to additional JSON files for older submissions. These file references can be used to retrieve the complete filing history for entities with extensive submissions.

filing_count: int

filing_from: str

filing_to: str

classmethod from_dict(data)

Parses a dictionary and returns a File object.

Return type:

File

name: str

class edgar_sec.edgar_data.Filing(accession_number, filing_date, report_date, acceptance_date_time, act, form, file_number, film_number, items, core_type, size, is_xbrl, is_inline_xbrl, primary_document, primary_doc_description)

Bases: object

A class representing an SEC filing document.

accession_number

Unique identifier for the filing in the format XXXXXXXXXX-XX-XXXXXX.

Type:

str

filing_date

The date when the filing was submitted to the SEC, in YYYY-MM-DD format.

Type:

str

report_date

The date of the reporting period covered by the filing, in YYYY-MM-DD format.

Type:

str

acceptance_date_time

The date and time when the filing was accepted by the SEC.

Type:

str

act

The securities act (e.g., ‘33’, ‘34’) under which the filing was submitted.

Type:

str

form

The form type (e.g., ‘10-K’, ‘10-Q’, ‘8-K’) of the filing.

Type:

str

file_number

SEC file number assigned to the registrant.

Type:

str

film_number

Film number assigned to the submission.

Type:

str

items

The specific items being reported in the filing.

Type:

Union[str, List[str]]

core_type

The core financial statement disclosure type.

Type:

str

size

The size of the filing document in bytes.

Type:

int

is_xbrl

Whether the filing includes XBRL data.

Type:

bool

is_inline_xbrl

Whether the filing uses inline XBRL format.

Type:

bool

primary_document

The filename of the primary document in the submission.

Type:

str

primary_doc_description

Description of the primary document.

Type:

str

Returns:

An object containing information about an SEC filing document.

Return type:

Filing

Note

Form types include annual reports (10-K), quarterly reports (10-Q), current reports (8-K), and various other registration and disclosure forms.

acceptance_date_time: str

accession_number: str

act: str

core_type: str

file_number: str

filing_date: str

film_number: str

form: str

classmethod from_dict(data)

Parses a dictionary and returns a Filing object.

Return type:

Filing

is_inline_xbrl: bool

is_xbrl: bool

items: Union[str, List[str]]

primary_doc_description: str

primary_document: str

report_date: str

size: int

class edgar_sec.edgar_data.FormerName(name, from_date, to_date)

Bases: object

A class representing a former name of an SEC filing entity.

name

The previous company name.

Type:

str

from_date

The date when the company began using this name, in YYYY-MM-DD format.

Type:

str

to_date

The date when the company stopped using this name, in YYYY-MM-DD format. May be empty if still in use.

Type:

str

Returns:

An object containing information about a company’s previous name.

Return type:

FormerName

Note

This class is typically used when parsing company submission history where entities may have changed their names over time. The from_dict method handles the API’s naming convention where the start date is called ‘from’.

from_date: str

classmethod from_dict(data)

Parses a dictionary and returns a FormerName object.

Return type:

FormerName

name: str

to_date: str

class edgar_sec.edgar_data.Frame(taxonomy, tag, ccp, uom, label, description, pts, frames)

Bases: object

A class representing a collection of financial disclosures across multiple companies for a specific concept and time period.

taxonomy

The reporting taxonomy identifier (e.g., ‘us-gaap’, ‘dei’, ‘ifrs’).

Type:

str

tag

The specific concept tag or account name (e.g., ‘Assets’, ‘Revenue’, ‘EarningsPerShare’).

Type:

str

ccp

The calculation context parameter defining the reporting context.

Type:

str

uom

The unit of measurement (e.g., ‘USD’, ‘shares’, ‘USD/shares’).

Type:

str

label

Human-readable label describing the financial concept.

Type:

str

description

Detailed explanation of what the financial concept represents.

Type:

str

pts

The number of reporting entities (points) included in the frame.

Type:

int

frames

A list of individual company disclosures for the concept and time period.

Type:

List[FrameDisclosure]

Returns:

An object containing comparable financial disclosures across multiple companies.

Return type:

Frame

Note

Frames are particularly useful for cross-sectional analysis, benchmarking, and comparative studies as they provide standardized financial data for multiple companies at the same point in time. The frame identifier (ccp) typically includes the calendar year, quarter, and whether the value is instantaneous (I) or for a duration (D).

ccp: str

description: str

frames: List[FrameDisclosure]

classmethod from_api_response(response)

Parses a dictionary and returns a Frame object.

Return type:

Frame

label: str

pts: int

tag: str

taxonomy: str

uom: str

class edgar_sec.edgar_data.FrameDisclosure(accn, cik, entity_name, loc, end, val)

Bases: object

A class representing a single financial disclosure from an SEC reporting frame.

accn

Accession number of the filing containing this disclosure.

Type:

str

cik

Central Index Key (CIK) of the entity making the disclosure.

Type:

str

entity_name

Legal name of the reporting entity.

Type:

str

loc

Location identifier for the disclosure within the filing document.

Type:

str

end

The end date of the reporting period, in YYYY-MM-DD format.

Type:

str

val

The numerical value of the disclosure.

Type:

int

Returns:

An object containing a single financial disclosure value and its metadata.

Return type:

FrameDisclosure

Note

Frame disclosures represent point-in-time snapshots of financial data that allow for comparison across multiple companies for the same time period and concept. Unlike CompanyConcept objects which show time-series data for a single company, frames provide cross-sectional data across multiple companies at a specific point in time.

accn: str

cik: str

end: str

entity_name: str

classmethod from_dict(data)

Parses a frame disclosure from the API response.

Return type:

FrameDisclosure

loc: str

val: int

class edgar_sec.edgar_data.SubmissionHistory(cik, entity_type, sic, sic_description, owner_org, insider_transaction_for_owner_exists, insider_transaction_for_issuer_exists, name, tickers, exchanges, ein, description, website, investor_website, category, fiscal_year_end, state_of_incorporation, state_of_incorporation_description, addresses, phone, flags, former_names, filings, files)

Bases: object

A class representing the complete submission history of an SEC filing entity.

cik

Central Index Key (CIK) of the entity, a unique identifier assigned by the SEC.

Type:

str

entity_type

The type of entity (e.g., ‘operating’, ‘investment-company’, ‘private’).

Type:

str

sic

Standard Industrial Classification (SIC) code.

Type:

str

sic_description

Text description of the SIC code.

Type:

str

owner_org

Name of the organization if this entity is an owner.

Type:

str

insider_transaction_for_owner_exists

Whether insider transactions exist for this entity as an owner.

Type:

bool

insider_transaction_for_issuer_exists

Whether insider transactions exist for this entity as an issuer.

Type:

bool

name

Legal name of the entity.

Type:

str

tickers

Stock ticker symbol(s) for the entity.

Type:

Union[str, List[str]]

exchanges

Stock exchange(s) where the entity is listed.

Type:

Union[str, List[str]]

ein

Employer Identification Number, a tax ID number.

Type:

str

description

Business description of the entity.

Type:

str

website

The entity’s primary website.

Type:

str

investor_website

The entity’s investor relations website.

Type:

str

category

SEC category classification.

Type:

str

fiscal_year_end

Month and day of the entity’s fiscal year end (MM-DD format).

Type:

str

state_of_incorporation

State or country code where the entity is incorporated.

Type:

str

state_of_incorporation_description

Full name of the state or country of incorporation.

Type:

str

addresses

Mailing and business addresses for the entity.

Type:

Union[Address, List[Address]]

phone

Contact phone number.

Type:

str

flags

Special flags or indicators about the entity.

Type:

Union[str, List[str]]

former_names

Previous names of the entity.

Type:

Union[FormerName, List[FormerName]]

filings

Recent SEC filings by the entity.

Type:

Union[Filing, List[Filing]]

files

References to additional files containing older filings.

Type:

Union[File, List[File]]

Returns:

An object containing comprehensive information about an entity’s filing history and profile.

Return type:

SubmissionHistory

Note

This class provides a comprehensive view of an entity’s profile and filing history as maintained by the SEC. It includes both the entity’s current information and a record of its historical filings and name changes.

addresses: Union[Address, List[Address]]

category: str

cik: str

description: str

ein: str

entity_type: str

exchanges: Union[str, List[str]]

files: Union[File, List[File]]

filings: Union[Filing, List[Filing]]

fiscal_year_end: str

flags: Union[str, List[str]]

former_names: Union[FormerName, List[FormerName]]

classmethod from_api_response(response)

Parses EDGAR API response and returns a single SubmissionHistory.

Return type:

SubmissionHistory

insider_transaction_for_issuer_exists: bool

insider_transaction_for_owner_exists: bool

investor_website: str

name: str

owner_org: str

phone: str

sic: str

sic_description: str

state_of_incorporation: str

state_of_incorporation_description: str

tickers: Union[str, List[str]]

website: str

class edgar_sec.edgar_data.UnitDisclosure(unit, end, val, accn, fy, fp, form, filed, frame, start='')

Bases: object

A class representing a specific financial disclosure for a single unit of measurement.

unit

The unit of measurement for the disclosed value (e.g., ‘USD’, ‘shares’, ‘USD-per-shares’).

Type:

str

end

The end date of the reporting period, in YYYY-MM-DD format.

Type:

str

val

The numerical value of the disclosure.

Type:

int

accn

The accession number of the filing containing this disclosure.

Type:

str

fy

The fiscal year of the disclosure in the format YYYY.

Type:

str

fp

The fiscal period code (e.g., ‘Q1’, ‘Q2’, ‘Q3’, ‘FY’ for annual).

Type:

str

form

The SEC form type containing this disclosure (e.g., ‘10-K’, ‘10-Q’).

Type:

str

filed

The date the filing was submitted to the SEC, in YYYY-MM-DD format.

Type:

str

frame

The financial reporting framework reference (e.g., ‘CY2022Q1I’).

Type:

str

start

The start date of the reporting period, in YYYY-MM-DD format. Empty for point-in-time disclosures.

Type:

str

Returns:

An object containing a single financial disclosure value and its metadata.

Return type:

UnitDisclosure

Note

SEC data often includes both instantaneous values (like assets at a point in time) and period values (like revenue for a quarter). When the disclosure represents a period, both start and end dates will be populated. For point-in-time disclosures, start will be empty.

accn: str

end: str

filed: str

form: str

fp: str

frame: str

classmethod from_dict(data)

Parses a dictionary and returns a UnitDisclosure object.

Return type:

UnitDisclosure

fy: str

start: str = ''

unit: str

val: int