ferc_xbrl_extractor.taxonomy

XBRL prototype structures.

Module Contents

Classes

XBRLType	Pydantic model that defines the type of a Concept.
Concept	Pydantic model that defines an XBRL taxonomy Concept.
LinkRole	Pydantic model that defines an XBRL taxonomy linkrole.
Taxonomy	Pydantic model that defines an XBRL taxonomy.

Attributes

ConceptDict

ferc_xbrl_extractor.taxonomy.ConceptDict

class ferc_xbrl_extractor.taxonomy.XBRLType(/, **data: Any)

Bases: pydantic.BaseModel

Pydantic model that defines the type of a Concept.

XBRL provides an inheritance model for defining types. There are a number of standardized types, as well as support for user defined types. For simplicity, this model stores just the name of the type, and the base type which it is derived from. The base type is then used for determining what type to use in the resulting database. The list of base types defined/dealt with here is not a comprehensive list of all types in the XBRL standard, but it does contain all types used in the FERC Form 1 taxonomy.

name: str = 'string'

base: Literal[string, decimal, gyear, integer, boolean, date, duration] = 'string'

classmethod from_arelle_type(arelle_type: arelle.ModelDtsObject.ModelType) → XBRLType

Construct XBRLType class from arelle ModelType.

get_pandas_type() → str | None

Return corresponding pandas type.

Gets a string representation of the pandas type best suited to represent the base type.

get_schema_type() → str

Return string specifying type for a frictionless table schema.

class ferc_xbrl_extractor.taxonomy.Concept(/, **data: Any)

Bases: pydantic.BaseModel

Pydantic model that defines an XBRL taxonomy Concept.

A Concept in the XBRL context can represent either a single fact or a ‘container’ for multiple facts. If child_concepts is empty, that indicates that the Concept is a single fact.

name: str

standard_label: str

documentation: str

type_: XBRLType

period_type: Literal[duration, instant]

child_concepts: list[Concept]

metadata: ferc_xbrl_extractor.arelle_interface.Metadata | None

classmethod from_list(concept_list: list, concept_dict: ConceptDict) → Concept

Construct a Concept from a list.

The way Arelle represents the structure of the of a taxonomy is a bit unintuitive. Each concept is represented as a list with the first element being the string ‘concept’, the next two are dictionaries containing metadata (the first of these two dictionaries has a ‘name’ field that is used to look up concepts in the ConceptDict. The remaining elements in the list are child concepts of the current concept. These child concepts are represented using the same list structure. These nested lists Directed Acyclic Graph (DAG) of concepts that defines a fact table.

Parameters:

• concept_list – List containing the Arelle representation of a concept.

• concept_dict – Dictionary mapping concept names to ModelConcept structures.

get_metadata(period_type: Literal[duration, instant]) → dict[str, dict[str, Any]]

Get metadata from all leaf nodes in Concept tree.

Leaf nodes in the Concept tree will become columns in output tables. This method will return the metadata only pertaining to these Concepts.

Parameters:

period_type – Return instant or duration concepts.

Returns:

A dictionary that maps Concept names to dictionaries of metadata.

class ferc_xbrl_extractor.taxonomy.LinkRole(/, **data: Any)

Bases: pydantic.BaseModel

Pydantic model that defines an XBRL taxonomy linkrole.

In XBRL taxonomies, Link Roles are used to group Concept together in a meaningful way. These groups are often referred to as “Fact Tables”. Link roles accomplish this by grouping Concepts into a Directed Acyclic Graph (DAG). In this graph, the leaf nodes in this graph represent individual facts, while other nodes represent containers of facts.

role: pydantic.AnyHttpUrl

definition: str

concepts: Concept

classmethod from_list(linkrole_list: list, concept_dict: ConceptDict) → LinkRole

Construct from list.

Arelle represents link roles in a similar structure to concepts. It uses a list where the first element is the string ‘linkRole’, and the second is a dictionary of metadata. This dictionary contains a field ‘role’ which is a URL pointing to where the link role is defined in the taxonomy. The second field in the dictionary is the ‘definition’, which is a string describing the linkrole. The final element in the list is a list which defines the root concept in the DAG.

Parameters:

• linkrole_list – List containing Arelle representation of linkrole.

• concept_dict – Dictionary mapping concept names to ModelConcept objects.

get_metadata(period_type: Literal[duration, instant]) → list[dict[str, Any]]

Get metadata from all leaf nodes in Concept tree.

The actual output file will contain a list of metadata objects. However, get_metadata implemented for the Concept class returns a dictionary to allow easily removing duplicate Concepts. This method will simply convert this dictionary to the list expected in the JSON file.

Parameters:

period_type – Return instant or duration concepts.

Returns:

A list of metadata objects.

class ferc_xbrl_extractor.taxonomy.Taxonomy(/, **data: Any)

Bases: pydantic.BaseModel

Pydantic model that defines an XBRL taxonomy.

XBRL Taxonomies are documents which are used to interpret facts reported in a filing. Taxonomies are composed of linkroles that group concepts into fact tables. This provides the structure and metadata that is used for extracting XBRL data into a SQLite database.

roles: list[LinkRole]

classmethod from_source(taxonomy_source: pathlib.Path | io.BytesIO, entry_point: pathlib.Path | None = None)

Construct taxonomy from taxonomy URL.

Use Arelle to parse a taxonomy from a URL or local file path. The structures Arelle uses to represent a taxonomy and its components are not well documented and unintuitive, so the structures defined here are instantiated and used instead.

Parameters:

• taxonomy_source – Path to taxonomy or in memory archive of taxonomy.

• entry_point – Path to taxonomy entry point within archive. If not None, then taxonomy should be a path to zipfile, not a URL.

save_metadata(filename: pathlib.Path)

Write taxonomy metadata to file.

XBRL taxonomies contain metadata that can be useful for interpreting reported data. This method will write some of this metadata to a json file for later use. For more information on the metadata being extracted, see Metadata.

Parameters:

filename – Path to output JSON file.