# ferc_xbrl_extractor.taxonomy

XBRL prototype structures.

## Attributes

| [`ConceptDict`](#ferc_xbrl_extractor.taxonomy.ConceptDict)   |    |
|--------------------------------------------------------------|----|

## Classes

| [`XBRLType`](#ferc_xbrl_extractor.taxonomy.XBRLType)   | Pydantic model that defines the type of a Concept.     |
|--------------------------------------------------------|--------------------------------------------------------|
| [`Concept`](#ferc_xbrl_extractor.taxonomy.Concept)     | Pydantic model that defines an XBRL taxonomy Concept.  |
| [`LinkRole`](#ferc_xbrl_extractor.taxonomy.LinkRole)   | Pydantic model that defines an XBRL taxonomy linkrole. |
| [`Taxonomy`](#ferc_xbrl_extractor.taxonomy.Taxonomy)   | Pydantic model that defines an XBRL taxonomy.          |

## Functions

| [`get_metadata_from_taxonomies`](#ferc_xbrl_extractor.taxonomy.get_metadata_from_taxonomies)(→ dict)   | Get dictionary of taxonomy metadata.   |
|--------------------------------------------------------------------------------------------------------|----------------------------------------|

## Module Contents

### 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](#ferc_xbrl_extractor.taxonomy.XBRLType)

Construct XBRLType class from arelle ModelType.

#### 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](../../../glossary.md#term-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](#ferc_xbrl_extractor.taxonomy.XBRLType)* *= None*

#### period_type *: Literal['duration', 'instant']*

#### child_concepts *: list[[Concept](#ferc_xbrl_extractor.taxonomy.Concept)]*

#### metadata *: [ferc_xbrl_extractor.arelle_interface.Metadata](../arelle_interface/index.md#ferc_xbrl_extractor.arelle_interface.Metadata) | None* *= None*

#### *classmethod* from_list(concept_list: list, concept_dict: [ConceptDict](#ferc_xbrl_extractor.taxonomy.ConceptDict)) → [Concept](#ferc_xbrl_extractor.taxonomy.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](../../../glossary.md#term-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](#ferc_xbrl_extractor.taxonomy.Concept)*

#### *classmethod* from_list(linkrole_list: list, concept_dict: [ConceptDict](#ferc_xbrl_extractor.taxonomy.ConceptDict)) → [LinkRole](#ferc_xbrl_extractor.taxonomy.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](../../../glossary.md#term-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](../../../glossary.md#term-Taxonomy) 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](#ferc_xbrl_extractor.taxonomy.LinkRole)]*

#### *classmethod* from_source(taxonomy_source: pathlib.Path | BinaryIO, entry_point: str | pathlib.Path) → [Taxonomy](#ferc_xbrl_extractor.taxonomy.Taxonomy)

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.

### ferc_xbrl_extractor.taxonomy.get_metadata_from_taxonomies(taxonomies: dict[str, [Taxonomy](#ferc_xbrl_extractor.taxonomy.Taxonomy)]) → dict

Get dictionary of taxonomy metadata.

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