# ferc_xbrl_extractor.arelle_interface

Abstract away interface to Arelle XBRL Library.

## Classes

| [`References`](#ferc_xbrl_extractor.arelle_interface.References)   | Pydantic model that defines XBRL references.                         |
|--------------------------------------------------------------------|----------------------------------------------------------------------|
| [`Calculation`](#ferc_xbrl_extractor.arelle_interface.Calculation) | Pydantic model that defines XBRL calculations.                       |
| [`Metadata`](#ferc_xbrl_extractor.arelle_interface.Metadata)       | Pydantic model that defines metadata extracted from XBRL taxonomies. |

## Functions

| [`_taxonomy_view`](#ferc_xbrl_extractor.arelle_interface._taxonomy_view)(→ tuple[arelle.ModelXbrl.ModelXbrl, ...)   | Use Arelle to load a taxonomy and build its parent-child relationship view.   |
|---------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------|
| [`load_taxonomy`](#ferc_xbrl_extractor.arelle_interface.load_taxonomy)(→ tuple[arelle.ModelXbrl.ModelXbrl, ...)     | Load XBRL taxonomy, and parse relationships.                                  |
| [`load_taxonomy_from_archive`](#ferc_xbrl_extractor.arelle_interface.load_taxonomy_from_archive)(...)               | Load an XBRL taxonomy from a zipfile archive.                                 |

## Module Contents

### ferc_xbrl_extractor.arelle_interface.\_taxonomy_view(taxonomy_source: str | arelle.FileSource.FileSource, max_retries: int = 7) → tuple[arelle.ModelXbrl.ModelXbrl, arelle.ViewFileRelationshipSet.ViewRelationshipSet]

Use Arelle to load a taxonomy and build its parent-child relationship view.

As it parses a taxonomy, Arelle downloads the schema/linkbase files it
references to a local on-disk cache (managed by Arelle’s own `webCache`),
then reads them back from there. When two or more callers load the *same*
taxonomy concurrently – e.g. multiple threads or processes each extracting
a different filing that shares one taxonomy version – their cache writes
can race, and Arelle raises `FileExistsError` when one caller tries to
create a cache file another is already writing.

This is a transient condition, not a real failure: by the time we retry,
the other caller has usually finished writing the file, so the retried
`ModelXbrl.load` call reads the now-complete cache entry instead of
trying to write it again. The loop therefore retries *only*
`FileExistsError`, with exponential backoff, up to `max_retries`
attempts before giving up and re-raising. Any other exception (a genuinely
missing taxonomy, malformed XBRL, an unrelated network error, …) is
allowed to propagate immediately on the first attempt, since retrying
those wouldn’t help – they aren’t the race this loop exists to work
around. See `test_concurrent_taxonomy_load` (integration) and
`test_taxonomy_view_retries_then_raises_after_max_retries` (unit) for
coverage of this behavior.

* **Parameters:**
  * **taxonomy_source** – URL, local path, or in-memory `FileSource` pointing
    at the taxonomy entry point.
  * **max_retries** – Maximum number of load attempts before giving up and
    re-raising the last `FileExistsError`.

### ferc_xbrl_extractor.arelle_interface.load_taxonomy(path: str | pathlib.Path) → tuple[arelle.ModelXbrl.ModelXbrl, arelle.ViewFileRelationshipSet.ViewRelationshipSet]

Load XBRL taxonomy, and parse relationships.

* **Parameters:**
  **path** – URL or local path pointing to an XBRL taxonomy.

### ferc_xbrl_extractor.arelle_interface.load_taxonomy_from_archive(taxonomy_archive: BinaryIO, entry_point: str | pathlib.Path) → tuple[arelle.ModelXbrl.ModelXbrl, arelle.ViewFileRelationshipSet.ViewRelationshipSet]

Load an XBRL taxonomy from a zipfile archive.

* **Parameters:**
  * **taxonomy_archive** – In memory taxonomy archive.
  * **entry_point** – Relative path to taxonomy entry point within archive.

### *class* ferc_xbrl_extractor.arelle_interface.References(/, \*\*data: Any)

Bases: `pydantic.BaseModel`

Pydantic model that defines XBRL references.

FERC uses XBRL references to link Concepts defined in its taxonomy to the physical
paper form. These are included in the output metadata and can be useful for linking
between XBRL and DBF data.

This model is not a generic representation of XBRL references, but specific to those
used by FERC.

#### account *: str | None* *= None*

#### form_location *: list[dict[str, str]]* *= None*

### *class* ferc_xbrl_extractor.arelle_interface.Calculation(/, \*\*data: Any)

Bases: `pydantic.BaseModel`

Pydantic model that defines XBRL calculations.

XBRL calculation relationships are also included in the metadata. Calculations are a
validation tool used to define relationships between facts using some mathematical
formula. For example, a calculation relationship might denote that one fact is equal
to the sum of 2 or more other facts, and this relationship can be used to validate a
filing.

#### name *: str*

#### weight *: float*

### *class* ferc_xbrl_extractor.arelle_interface.Metadata(/, \*\*data: Any)

Bases: `pydantic.BaseModel`

Pydantic model that defines metadata extracted from XBRL taxonomies.

Taxonomies contain various metadata which are useful for interpreting XBRL filings.
The metadata fields being extracted here include references, calculations, and balances.

#### name *: str*

#### references *: [References](#ferc_xbrl_extractor.arelle_interface.References)*

#### calculations *: list[[Calculation](#ferc_xbrl_extractor.arelle_interface.Calculation)]*

#### balance *: Literal['credit', 'debit'] | None* *= None*

#### *classmethod* from_concept(concept: arelle.ModelDtsObject.ModelConcept) → [Metadata](#ferc_xbrl_extractor.arelle_interface.Metadata)

Get metadata for a single XBRL Concept.

This function will create a Metadata object with metadata extracted for
a single Concept.

* **Parameters:**
  **concept** – Concept to extract metadata from.