ferc_xbrl_extractor.instance ============================ .. py:module:: ferc_xbrl_extractor.instance .. autoapi-nested-parse:: Parse a single instance. Attributes ---------- .. autoapisummary:: ferc_xbrl_extractor.instance.XBRL_INSTANCE ferc_xbrl_extractor.instance.XBRL_LINK Classes ------- .. autoapisummary:: ferc_xbrl_extractor.instance.Period ferc_xbrl_extractor.instance.DimensionType ferc_xbrl_extractor.instance.Axis ferc_xbrl_extractor.instance.Entity ferc_xbrl_extractor.instance.Context ferc_xbrl_extractor.instance.Fact ferc_xbrl_extractor.instance.Instance ferc_xbrl_extractor.instance.InstanceBuilder Functions --------- .. autoapisummary:: ferc_xbrl_extractor.instance.instances_from_zip ferc_xbrl_extractor.instance.get_instances Module Contents --------------- .. py:data:: XBRL_INSTANCE :value: 'http://www.xbrl.org/2003/instance' .. py:data:: XBRL_LINK :value: 'http://www.xbrl.org/2003/linkbase' .. py:class:: Period(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` Pydantic model that defines an XBRL period. A period can be instantaneous or a duration of time. Instantaneous periods will only have the end_date field, while duration periods will have start_date, and end_date. .. py:attribute:: instant :type: bool .. py:attribute:: start_date :type: str | None :value: None .. py:attribute:: end_date :type: str .. py:method:: from_xml(elem: lxml.etree._Element) -> Period :classmethod: Construct Period from XML element. .. py:class:: DimensionType Bases: :py:obj:`enum.Enum` Indicate dimension type. XBRL contains explicit (all allowable values defined in taxonomy) and typed (dimension with dynamic values) dimensions. .. py:attribute:: EXPLICIT .. py:attribute:: TYPED .. py:class:: Axis(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` Pydantic model that defines an XBRL Axis. Axes (or dimensions, terms are interchangeable in XBRL) are used for identifying individual facts when the entity id, and period are insufficient. All axes will be turned into columns, and be a part of the primary key for the table they belong to. .. py:attribute:: name :type: str .. py:attribute:: value :type: str :value: '' .. py:attribute:: dimension_type :type: DimensionType .. py:method:: strip_prefix(name: str) -> str :classmethod: Strip XML prefix from name. .. py:method:: from_xml(elem: lxml.etree._Element) -> Axis :classmethod: Construct Axis from XML element. .. py:class:: Entity(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` Pydantic model that defines an XBRL Entity. Entities are used to identify individual XBRL facts. An Entity should contain a unique identifier, as well as any dimensions defined for a table. .. py:attribute:: identifier :type: str .. py:attribute:: dimensions :type: list[Axis] .. py:method:: from_xml(elem: lxml.etree._Element) -> Entity :classmethod: Construct Entity from XML element. .. py:property:: snakecase_dimensions :type: list[str] Return list of dimension names in snakecase. .. py:method:: check_dimensions(primary_key: list[str]) -> bool Check if Context has extra axes not defined in primary key. .. py:class:: Context(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` Pydantic model that defines an XBRL Context. Contexts are used to provide useful background information for facts. The context indicates the entity, time period, and any other dimensions which apply to the fact. .. py:attribute:: c_id :type: str .. py:attribute:: entity :type: Entity .. py:attribute:: period :type: Period .. py:method:: from_xml(elem: lxml.etree._Element) -> Context :classmethod: Construct Context from XML element. .. py:method:: check_dimensions(primary_key: list[str]) -> bool Check if Context has extra axes not defined in primary key. Facts missing axes from primary key can be treated as totals across that axis, but facts with extra axes would not fit in table. :param primary_key: Primary key of table. .. py:method:: as_primary_key(filing_name: str, axes: list[str]) -> dict[str, str] Return a dictionary that represents the context as composite primary key. .. py:method:: __hash__() Just hash Context ID as it uniquely identifies contexts for an instance. .. py:class:: Fact(/, **data: Any) Bases: :py:obj:`pydantic.BaseModel` Pydantic model that defines an XBRL Fact. A fact is a single "data point", which contains a name, value, and a Context to give background information. .. py:attribute:: name :type: str .. py:attribute:: c_id :type: str .. py:attribute:: value :type: str | None :value: None .. py:method:: from_xml(elem: lxml.etree._Element) -> Fact :classmethod: Construct Fact from XML element. .. py:method:: f_id() -> str A unique identifier for the Fact. There is an `id` attribute on most fact entries, but there are some facts without an `id` attribute, so we can't use that. Instead we assume that each fact is uniquely identified by its context ID and the concept name. NB, this is a function, not a property. This would be a property, but a property is not pickleable within Pydantic 1.x .. py:class:: Instance(contexts: dict[str, Context], instant_facts: dict[str, list[Fact]], duration_facts: dict[str, list[Fact]], filing_name: str, publication_time: datetime.datetime, taxonomy_version: str) Class to encapsulate a parsed instance. This class should be constructed using the InstanceBuilder class. Instance wraps the contexts and facts parsed by the InstanceBuilder, and is used to construct dataframes from fact tables. .. py:attribute:: logger .. py:attribute:: taxonomy_version .. py:attribute:: instant_facts .. py:attribute:: duration_facts .. py:attribute:: fact_id_counts .. py:attribute:: total_facts .. py:attribute:: duplicated_fact_ids .. py:attribute:: used_fact_ids :type: set[str] .. py:attribute:: filing_name .. py:attribute:: contexts .. py:attribute:: publication_time .. py:method:: get_facts(instant: bool, concept_names: list[str], primary_key: list[str]) -> dict[str, list[Fact]] Return a dictionary that maps Context ID's to a list of facts for each context. :param instant: Get facts with instant or duration period. :param concept_names: Name of concepts which map to a column name and name of facts. :param primary_key: Name of columns in primary_key used to filter facts. .. py:class:: InstanceBuilder(file_info: str | BinaryIO, name: str, publication_time: datetime.datetime, taxonomy_version: str) Class to manage parsing XBRL filings. .. py:attribute:: name .. py:attribute:: file .. py:attribute:: publication_time .. py:attribute:: taxonomy_version .. py:method:: parse(fact_prefix: str = 'ferc') -> Instance Parse a single XBRL instance using XML library directly. This will return an Instance class which wraps the data parsed from the filing in question. :param fact_prefix: Prefix to identify facts in filing (defaults to 'ferc'). :returns: Dictionary of contexts in filing. fact_dict: Dictionary of facts in filing. filing_name: Name of filing. :rtype: context_dict .. py:function:: instances_from_zip(instance_path: pathlib.Path | io.BytesIO) -> list[InstanceBuilder] Get list of instances from specified path to zipfile. :param instance_path: Path to zipfile containing XBRL filings. .. py:function:: get_instances(instance_path: pathlib.Path | io.BytesIO) -> list[InstanceBuilder] Get list of instances from specified path. :param instance_path: Path to one or more XBRL filings.