### Install xbrl-core and dependencies

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Commands to install the core library via pip, including optional feature sets for analysis, display, and Excel export.

```shell
pip install xbrl-core
# Optional dependencies
pip install 'xbrl-core[analysis]'
pip install 'xbrl-core[display]'
pip install 'xbrl-core[excel]'
pip install 'xbrl-core[all]'
```

--------------------------------

### Parse Footnote Links in Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Explains how to parse footnote linkbase information to associate textual footnotes with specific facts. It shows how to retrieve footnotes for a given fact ID, access footnote text and language, and get counts of facts with footnotes.

```python
from xbrl_core import parse_footnote_links

footnote_map = parse_footnote_links(parsed.footnote_links)

notes = footnote_map.get("IdFact1234")
for n in notes:
    print(n.text, n.lang)

print(footnote_map.fact_ids)       # Fact IDs with footnotes
print(len(footnote_map))           # number of Facts with footnotes
```

--------------------------------

### Hierarchical XBRL Statement Display with Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Generates a hierarchical display of XBRL financial statements, suitable for indented views, using `DisplayHint` objects to guide the structure. It can output a `rich` table or raw `DisplayRow` objects. This function is useful for presenting financial statements in a structured, readable format.

```python
from xbrl_core import (
    build_display_rows,
    render_hierarchical_statement,
    DisplayHint,
)

hints = [
    DisplayHint(concept="AssetsAbstract", depth=0, is_abstract=True, label="Assets"),
    DisplayHint(concept="CashAndDeposits", depth=1),
    DisplayHint(concept="TotalAssets", depth=0, is_total=True),
]

# Rich Table
table = render_hierarchical_statement(items, hints=hints, title="BS")

# Or get raw DisplayRow objects
rows = build_display_rows(items, hints=hints)
```

--------------------------------

### Export XBRL DataFrame to Excel with Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Exports an XBRL line items DataFrame to an Excel file. This function requires the `xbrl-core[excel]` extra to be installed. It allows specifying the output filename and the sheet name within the Excel workbook.

```python
from xbrl_core import to_excel

to_excel(df, "output.xlsx", sheet_name="BalanceSheet")
```

--------------------------------

### Configure custom iXBRL formats

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Demonstrates how to register custom format functions for iXBRL parsing using the FormatRegistry.

```python
from xbrl_core import FormatRegistry, parse_ixbrl_facts

registry = FormatRegistry()
registry.register("dateyearmonthdaycjk", my_cjk_date_func)

parsed = parse_ixbrl_facts(ixbrl_bytes, format_registry=registry)
```

--------------------------------

### Build LineItems in Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Illustrates how to build fully typed LineItem objects by merging raw facts, structured contexts, and optional label resolvers. It shows how to access line item attributes like local name, value, period, entity ID, dimensions, and labels in different languages.

```python
from xbrl_core import build_line_items

items = build_line_items(parsed.facts, ctx_map, langs=("en", "ja"))

for item in items:
    print(item.local_name)    # "NetSales"
    print(item.value)         # Decimal('1234567890')
    print(item.period)        # InstantPeriod / DurationPeriod
    print(item.entity_id)     # "E00001"
    print(item.dimensions)    # tuple[DimensionMember, ...]
    print(item.label("en"))   # "Net sales"
    print(item.label("ja"))   # "売上高"
```

--------------------------------

### Parse Presentation Linkbase in Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Demonstrates parsing presentation linkbase XML into a tree structure. It shows how to flatten the tree to iterate through concepts, retrieve line-item subtrees, and merge multiple presentation linkbases.

```python
from xbrl_core import parse_presentation_linkbase, merge_presentation_trees

trees = parse_presentation_linkbase(pre_xml_bytes)

for role_uri, tree in trees.items():
    # Flatten the tree (depth-first)
    for node in tree.flatten(skip_abstract=True, skip_dimension=True):
        print("  " * node.depth + node.concept)

    # Get only the line-items subtree
    for node in tree.line_items_roots():
        print(node.concept, node.order)

# Merge multiple presentation linkbases
merged = merge_presentation_trees(trees_a, trees_b)
```

--------------------------------

### Parse and structure XBRL facts

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Demonstrates the basic workflow of parsing an XBRL instance document and structuring the resulting contexts and line items.

```python
from xbrl_core import parse_xbrl_facts, structure_contexts, build_line_items

with open("instance.xbrl", "rb") as f:
    parsed = parse_xbrl_facts(f.read(), source_path="instance.xbrl")

ctx_map = structure_contexts(parsed.contexts)
items = build_line_items(parsed.facts, ctx_map)

for item in items[:5]:
    print(item.local_name, item.value, item.period)
```

--------------------------------

### Parse Definition Linkbase in Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Demonstrates parsing definition linkbase XML to understand hierarchical relationships, particularly for hypercubes and their dimensions. It shows how to extract table concepts, axis concepts, and domain concepts, and query relationships using arcroles.

```python
from xbrl_core import parse_definition_linkbase

def_lb = parse_definition_linkbase(def_xml_bytes)

for role_uri in def_lb.role_uris:
    tree = def_lb.get_tree(role_uri)
    for hc in tree.hypercubes:
        print(f"Table: {hc.table_concept}")
        for axis in hc.axes:
            print(f"  Axis: {axis.axis_concept}")
            if axis.domain:
                print(f"  Domain: {axis.domain.concept}")

def_lb.children_of("TableConcept", arcrole=ARCROLE_HYPERCUBE_DIMENSION)
def_lb.parent_of("MemberConcept", arcrole=ARCROLE_DOMAIN_MEMBER)
```

--------------------------------

### Parse XBRL and iXBRL documents

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Shows how to parse standard XBRL and Inline XBRL documents. Both methods return a ParsedXBRL object containing facts, contexts, and units.

```python
from xbrl_core import parse_xbrl_facts, parse_ixbrl_facts

# XBRL
parsed_xbrl = parse_xbrl_facts(xbrl_bytes, source_path="example.xbrl")

# iXBRL
parsed_ixbrl = parse_ixbrl_facts(ixbrl_bytes, source_path="report.htm")
```

--------------------------------

### Parse Calculation Linkbase in Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Explains how to parse calculation linkbase XML and query relationships between concepts. It shows how to iterate through arcs, determine signs and weights, and find children, parents, and ancestors of concepts within a specific role.

```python
from xbrl_core import parse_calculation_linkbase

calc_lb = parse_calculation_linkbase(cal_xml_bytes)

for role_uri in calc_lb.role_uris:
    tree = calc_lb.get_tree(role_uri)
    for arc in tree.arcs:
        sign = "+" if arc.weight == 1 else "-"
        print(f"  {arc.parent} {sign}-> {arc.child}")

# Query relationships
calc_lb.children_of("GrossProfit")        # child arcs
calc_lb.parent_of("NetSales")             # parent arcs
calc_lb.ancestors_of("NetSales", role_uri=role)  # root-ward chain
```

--------------------------------

### Merge Inline XBRL Document Sets

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Combines multiple iXBRL files from a single filing into a unified result set.

```python
from xbrl_core import parse_ixbrl_facts, merge_ixbrl_results

results = [parse_ixbrl_facts(f) for f in ixbrl_files]
merged = merge_ixbrl_results(results)
```

--------------------------------

### Parse XSD Elements in Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Demonstrates parsing XML Schema Definition (XSD) files to extract information about XBRL elements. It shows how to access element properties such as period type, balance, abstract status, type name, and substitution group.

```python
from xbrl_core import parse_xsd_elements

elements = parse_xsd_elements(xsd_bytes)

elem = elements["NetSales"]
print(elem.period_type)         # "duration"
print(elem.balance)             # "credit"
print(elem.abstract)            # False
print(elem.type_name)           # "xbrli:monetaryItemType"
print(elem.substitution_group)  # "xbrli:item"
```

--------------------------------

### Structure Units in Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Shows how to convert raw unit XML fragments into typed StructuredUnit objects using the structure_units function. It demonstrates accessing unit properties like currency code and checking if a unit is monetary, pure, or per-share.

```python
from xbrl_core import structure_units

unit_map = structure_units(parsed.units)

unit = unit_map["JPY"]
print(unit.is_monetary)     # True
print(unit.currency_code)   # "JPY"

unit = unit_map["pure"]
print(unit.is_pure)         # True

unit = unit_map["JPYPerShare"]
print(unit.is_per_share)    # True
```

--------------------------------

### Customize Error and Warning Classes in xbrl-core

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Demonstrates how to substitute default exception and warning types with domain-specific classes. This is achieved by passing custom classes to the error_class and warning_class parameters in linkbase parser functions.

```python
from xbrl_core import XbrlParseError, XbrlWarning, parse_calculation_linkbase

class EdinetParseError(XbrlParseError):
    """EDINET-specific parse error."""

class EdinetWarning(UserWarning):
    """EDINET-specific warning."""

lb = parse_calculation_linkbase(
    xml_bytes,
    error_class=EdinetParseError,
    warning_class=EdinetWarning,
)
```

--------------------------------

### XBRL Error Handling and Customization

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Illustrates how to catch specific XBRL-related errors (parsing, validation) and warnings. Also shows how to define custom error and warning classes for domain-specific packages, allowing substitution during parsing functions.

```python
from xbrl_core import XbrlError, XbrlParseError, XbrlValidationError, XbrlWarning, parse_xbrl_facts, parse_calculation_linkbase
import warnings

# Assuming 'bad_bytes', 'xbrl_bytes', 'xml_bytes' are defined byte strings

# Catch parsing errors
# try:
#     parsed = parse_xbrl_facts(bad_bytes)
# except XbrlParseError as e:
#     print(f"Error code: {e.code}")      # "XBRL_PARSE_001"
#     print(f"Context: {e.context}")       # {"source_path": "..."}

# Capture warnings
# with warnings.catch_warnings(record=True) as w:
#     warnings.simplefilter("always")
#     parsed = parse_xbrl_facts(xbrl_bytes, strict=False)
#     for warning in w:
#         if issubclass(warning.category, XbrlWarning):
#             print(f"Warning: {warning.message}")

# Custom error/warning classes for domain-specific packages
# class EdinetParseError(XbrlParseError):
#     """EDINET-specific parse error."""
#
# class EdinetWarning(UserWarning):
#     """EDINET-specific warning."""
#
# lb = parse_calculation_linkbase(
#     xml_bytes,
#     error_class=EdinetParseError,
#     warning_class=EdinetWarning,
# )
```

--------------------------------

### Parse Reference Linkbase in Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Demonstrates parsing reference linkbase XML to extract authoritative references associated with XBRL concepts. It shows how to access the concept name, reference role, and individual parts of each reference, including their local names and values.

```python
from xbrl_core import parse_reference_linkbase

refs = parse_reference_linkbase(ref_xml_bytes)

for ref in refs:
    print(f"{ref.concept_name}: {ref.role}")
    for part in ref.parts:
        print(f"  {part.local_name} = {part.value}")
```

--------------------------------

### Filter ContextCollection in Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Demonstrates how to filter a ContextCollection object to select specific types of contexts, such as instant-only, duration-only, or contexts with specific dimensions. It also shows how to access the latest instant period or unique duration periods.

```python
from xbrl_core import ContextCollection

coll = ContextCollection(ctx_map)
col.filter_instant()                   # instant contexts only
col.filter_duration()                  # duration contexts only
col.filter_no_dimensions()             # no dimension members
col.filter_by_dimension(axis="{ns}ProductAxis", member="{ns}SegmentA")

col.latest_instant_period              # most recent InstantPeriod
col.unique_duration_periods            # unique DurationPeriods, sorted
```

--------------------------------

### Access structured context data

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Converts raw context fragments into StructuredContext objects to easily access period, entity, and dimension information.

```python
from xbrl_core import structure_contexts

ctx_map = structure_contexts(parsed.contexts)
ctx = ctx_map["CurrentYearInstant"]
print(ctx.period)
print(ctx.entity_id)
print(ctx.dimensions)
```

--------------------------------

### Generate HTML Tables for Jupyter Notebooks

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Creates HTML representations of financial statements, suitable for display within Jupyter notebooks. Supports hierarchical structures using 'DisplayHint' objects. Requires 'items' and 'DisplayHint' objects.

```python
from xbrl_core import to_html, DisplayHint
from IPython.display import HTML, display

# Assuming 'items' is a list of XBRL items
# hints = [
#     DisplayHint(concept="RevenueAbstract", depth=0, is_abstract=True, label="Revenue"),
#     DisplayHint(concept="NetSales", depth=1),
#     DisplayHint(concept="OtherRevenue", depth=1),
#     DisplayHint(concept="TotalRevenue", depth=0, is_total=True),
# ]
# 
# html = to_html(items, hints=hints, title="Income Statement")
# display(HTML(html))
```

--------------------------------

### Convert XBRL Items to HTML with Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Converts XBRL items into an HTML representation, optionally using display hints for structure. This is particularly useful for rendering financial statements within Jupyter notebooks or web applications. The output is an HTML string.

```python
from xbrl_core import to_html

html = to_html(items, hints=hints, title="Balance Sheet")
```

--------------------------------

### Parse XBRL Labels and Custom Concept Extraction

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Demonstrates how to iterate over parsed labels and implement a custom concept extractor function for jurisdiction-specific taxonomies using regex.

```python
for lab in labels:
    print(f"{lab.concept_name} [{lab.lang}] ({lab.role}): {lab.text}")

import re

def edinet_concept_extractor(href: str) -> str | None:
    if "#" not in href:
        return None
    fragment = href.rsplit("#", 1)[1]
    m = re.search(r"_([A-Z][A-Za-z0-9]*)$", fragment)
    return m.group(1) if m else fragment

labels = parse_label_linkbase(xml_bytes, concept_extractor=edinet_concept_extractor)
```

--------------------------------

### Structure XBRL Contexts with Python

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Converts raw XBRL context XML fragments into typed StructuredContext objects, providing period, entity, and dimension information. Offers a ContextCollection class for filtering and querying contexts. Requires lxml.

```python
from xbrl_core import structure_contexts, ContextCollection

# Structure contexts from parsed XBRL
ctx_map = structure_contexts(parsed.contexts)

# Access individual context
ctx = ctx_map["CurrentYearInstant"]
print(f"Period: {ctx.period}")           # InstantPeriod(instant=datetime.date(2024, 3, 31))
print(f"Entity: {ctx.entity_id}")         # "E00001"
print(f"Dimensions: {ctx.dimensions}")    # tuple[DimensionMember, ...]
print(f"Is instant: {ctx.is_instant}")    # True

# Use ContextCollection for filtering
coll = ContextCollection(ctx_map)

# Filter by period type
instant_contexts = coll.filter_instant()
duration_contexts = coll.filter_duration()

# Filter by dimensions
no_dim_contexts = coll.filter_no_dimensions()
segment_contexts = coll.filter_by_dimension(
    axis="{http://example.com/taxonomy}ProductAxis",
    member="{http://example.com/taxonomy}SegmentA"
)

# Get latest periods
print(f"Latest instant: {coll.latest_instant_period}")
print(f"Unique durations: {coll.unique_duration_periods}")

# Get contexts for latest period
latest_instant_ctxs = coll.latest_instant_contexts()
```

--------------------------------

### Render Financial Statements to Rich Terminal Tables

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Utilizes the 'rich' library to display financial statements in formatted tables directly in the terminal. Supports both simple flat tables and hierarchical displays with custom presentation hints. Requires 'items' and 'DisplayHint' objects.

```python
from rich.console import Console
from xbrl_core import render_statement, render_hierarchical_statement, DisplayHint, build_display_rows

console = Console()

# Simple flat table
# table = render_statement(items, title="Income Statement", label_lang="en")
# console.print(table)

# Hierarchical display with presentation hints
# hints = [
#     DisplayHint(concept="AssetsAbstract", depth=0, is_abstract=True, label="Assets"),
#     DisplayHint(concept="CashAndDeposits", depth=1),
#     DisplayHint(concept="AccountsReceivable", depth=1),
#     DisplayHint(concept="CurrentAssets", depth=1, is_total=True, label="Total Current Assets"),
#     DisplayHint(concept="TotalAssets", depth=0, is_total=True, label="Total Assets"),
# ]
# table = render_hierarchical_statement(items, hints=hints, title="Balance Sheet", label_lang="en")
# console.print(table)

# Get raw DisplayRow objects for custom rendering
# rows = build_display_rows(items, hints=hints, label_lang="en")
# for row in rows:
#     indent = "  " * row.depth
#     print(f"{indent}{row.label}: {row.value}")
```

--------------------------------

### Accessing XBRL Unit Information

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Demonstrates how to access and validate unit types such as pure numbers, currency per share, and share counts from a unit map.

```python
pure_unit = unit_map["pure"]
print(f"Is pure: {pure_unit.is_pure}")

per_share_unit = unit_map["JPYPerShare"]
print(f"Is per-share: {per_share_unit.is_per_share}")
print(f"Currency code: {per_share_unit.currency_code}")

shares_unit = unit_map["shares"]
print(f"Is shares: {shares_unit.is_shares}")
```

--------------------------------

### Building Typed LineItems

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Uses build_line_items to merge raw facts and structured contexts into typed objects, supporting multi-language label resolution.

```python
from xbrl_core import build_line_items, structure_contexts

ctx_map = structure_contexts(parsed.contexts)
items = build_line_items(parsed.facts, ctx_map, langs=("en", "ja"))

for item in items[:10]:
    print(f"Concept: {item.local_name}")
    print(f"Value: {item.value}")
    print(f"English label: {item.label('en')}")
```

--------------------------------

### Parsing Presentation Linkbase

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Extracts hierarchical concept relationships for financial statement ordering and supports merging multiple presentation trees.

```python
from xbrl_core import parse_presentation_linkbase, merge_presentation_trees

with open("taxonomy_pre.xml", "rb") as f:
    trees = parse_presentation_linkbase(f.read())

for role_uri, tree in trees.items():
    for node in tree.flatten(skip_abstract=True, skip_dimension=True):
        print(f"{node.concept} (order={node.order})")
```

--------------------------------

### Render XBRL Statements for Terminal Display with Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Renders XBRL financial statements into a format suitable for display in a terminal using the `rich` library. This requires the `xbrl-core[display]` extra. The function `render_statement` takes XBRL items and an optional title and label language.

```python
from rich.console import Console
from xbrl_core import render_statement

table = render_statement(items, title="Balance Sheet", label_lang="en")
Console().print(table)
```

--------------------------------

### Handle XBRL Errors with Python Exceptions

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Demonstrates error handling for XBRL parsing and validation using custom exception classes like `XbrlError`, `XbrlParseError`, and `XbrlValidationError`. These exceptions provide structured error codes and context, allowing for specific error management and debugging.

```python
from xbrl_core import XbrlError, XbrlParseError, XbrlValidationError

try:
    parsed = parse_xbrl_facts(bad_bytes)
except XbrlParseError as e:
    print(e.code)     # "XBRL_PARSE_001"
    print(e.context)  # {"source_path": "..."}
```

--------------------------------

### Parse Label Linkbase in Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Shows how to parse label linkbase XML to extract human-readable labels for XBRL concepts. It iterates through the parsed labels and prints the concept name, language, and the corresponding text label.

```python
from xbrl_core import parse_label_linkbase

labels = parse_label_linkbase(lab_xml_bytes)

for lab in labels:
    print(f"{lab.concept_name} [{lab.lang}] = {lab.text}")
```

--------------------------------

### Export Financial Data to Various Formats

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Demonstrates how to export a pandas DataFrame to CSV, Parquet, and Excel formats using the xbrl_core library. Assumes a DataFrame 'df' and a list of items are pre-defined.

```python
from xbrl_core import to_csv, to_parquet, to_excel

# Assuming 'df' is a pandas DataFrame and 'items' is a list of XBRL items
# to_csv(df, "financial_data.csv")
# to_parquet(df, "financial_data.parquet")
# to_excel(df, "financial_data.xlsx", sheet_name="BalanceSheet")
```

--------------------------------

### Custom XBRL Label Resolution with Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Implements a custom `LabelResolver` to inject taxonomy labels into XBRL data processing. By implementing the `resolve` and `resolve_batch` methods, users can provide their own label lookups, which are then used by functions like `build_line_items`. This allows for flexible label management.

```python
from xbrl_core import LabelResolver, LabelInfo, LabelSource

class MyResolver:
    def resolve(self, concept_qname, lang, role):
        # Look up label from your taxonomy data
        return LabelInfo(text="Net sales", role=role, lang=lang, source=LabelSource.STANDARD)

    def resolve_batch(self, concept_qnames, lang, role):
        return {qn: self.resolve(qn, lang, role) for qn in concept_qnames}

items = build_line_items(parsed.facts, ctx_map, resolver=MyResolver(), langs=("en",))
```

--------------------------------

### Add and Access Metadata for Line Items

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Shows how to attach metadata to line items when converting them to a pandas DataFrame and how to access this metadata. Requires pre-defined 'items' and 'metadata'.

```python
from xbrl_core import line_items_to_dataframe

# Assuming 'items' is a list of XBRL items
# df = line_items_to_dataframe(items, metadata={"source": "SEC Filing", "entity": "ACME Corp"})
# print(df.attrs)  # Expected output: {'source': 'SEC Filing', 'entity': 'ACME Corp'}
```

--------------------------------

### Parsing Label Linkbase

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Extracts human-readable labels for concepts, supporting multiple languages and roles defined in the taxonomy.

```python
from xbrl_core import parse_label_linkbase

with open("taxonomy_lab.xml", "rb") as f:
    labels = parse_label_linkbase(f.read())
```

--------------------------------

### Parsing Calculation Linkbase

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Extracts summation-item relationships with weights to validate financial calculations and query parent-child hierarchies.

```python
from xbrl_core import parse_calculation_linkbase

with open("taxonomy_cal.xml", "rb") as f:
    calc_lb = parse_calculation_linkbase(f.read())

children = calc_lb.children_of("GrossProfit")
for arc in children:
    print(f"Child: {arc.child} (weight={arc.weight})")
```

--------------------------------

### Parse XSD Schema Elements

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Extracts metadata definitions from taxonomy XSD files, including period type, balance, and substitution groups.

```python
from xbrl_core import parse_xsd_elements

with open("taxonomy.xsd", "rb") as f:
    elements = parse_xsd_elements(f.read())

elem = elements["NetSales"]
print(f"Period type: {elem.period_type}")
print(f"Balance: {elem.balance}")
print(f"Abstract: {elem.abstract}")
```

--------------------------------

### Parse XBRL 2.1 Instance Documents with Python

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Parses XBRL 2.1 instance documents from raw bytes, extracting facts, contexts, units, and schema references into a ParsedXBRL object. Supports strict and lenient parsing modes. Requires lxml.

```python
from xbrl_core import parse_xbrl_facts

# Parse XBRL instance document
with open("instance.xbrl", "rb") as f:
    parsed = parse_xbrl_facts(f.read(), source_path="instance.xbrl")

# Access parsed data
print(f"Total facts: {parsed.fact_count}")
print(f"Contexts: {len(parsed.contexts)}")
print(f"Units: {len(parsed.units)}")

# Iterate over facts
for fact in parsed.facts[:5]:
    print(f"{fact.local_name}: {fact.value_raw} (context={fact.context_ref})")

# Access schema references
for schema_ref in parsed.schema_refs:
    print(f"Schema: {schema_ref.href}")

# Lenient parsing mode for non-compliant documents
parsed_lenient = parse_xbrl_facts(xbrl_bytes, strict=False)
for elem in parsed_lenient.ignored_elements:
    print(f"Ignored: {elem.reason} at line {elem.source_line}")
```

--------------------------------

### Parsing XSD Schema Elements

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

The `parse_xsd_elements()` function extracts element definitions from taxonomy XSD files, including period type, balance, abstract flag, and substitution group.

```APIDOC
## Parsing XSD Schema Elements

The `parse_xsd_elements()` function extracts element definitions from taxonomy XSD files, including period type, balance, abstract flag, and substitution group.

```python
from xbrl_core import parse_xsd_elements

with open("taxonomy.xsd", "rb") as f:
    elements = parse_xsd_elements(f.read())

elem = elements["NetSales"]
print(f"Period type: {elem.period_type}")           # "duration"
print(f"Balance: {elem.balance}")                    # "credit"
print(f"Abstract: {elem.abstract}")                  # False
print(f"Type: {elem.type_name}")                     # "xbrli:monetaryItemType"
print(f"Substitution group: {elem.substitution_group}") # "xbrli:item"
```
```

--------------------------------

### Extract and Clean Text Blocks

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Extracts textBlockItemType facts from filings and converts embedded HTML content into plain text.

```python
from xbrl_core import extract_text_blocks, clean_html, structure_contexts

ctx_map = structure_contexts(parsed.contexts)
blocks = extract_text_blocks(parsed.facts, ctx_map)

for block in blocks:
    plain_text = clean_html(block.html)
    print(f"Content preview: {plain_text[:500]}...")
```

--------------------------------

### Structure XBRL Units with Python

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Converts raw XBRL unit XML fragments into typed StructuredUnit objects, supporting simple measures and divide measures (e.g., per-share units). Requires lxml.

```python
from xbrl_core import structure_units

# Structure units from parsed XBRL
unit_map = structure_units(parsed.units)

# Access monetary unit
jpy_unit = unit_map["JPY"]
print(f"Is monetary: {jpy_unit.is_monetary}")   # True
print(f"Currency code: {jpy_unit.currency_code}") # "JPY"
```

--------------------------------

### Convert XBRL Line Items to DataFrame and Export with Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Converts XBRL line items into a pandas DataFrame for analysis and provides functions to export the DataFrame to CSV or Parquet formats. Requires the `xbrl-core[analysis]` extra. The DataFrame includes columns like 'local_name', 'label', 'value', and 'period_end'.

```python
from xbrl_core import line_items_to_dataframe, to_csv, to_parquet

df = line_items_to_dataframe(items, label_lang="en")
print(df[["local_name", "label", "value", "period_end"]].head())

# Export
to_csv(df, "output.csv")
to_parquet(df, "output.parquet")
```

--------------------------------

### Parse Footnotes

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Extracts footnote links from XBRL instance documents and maps them to specific fact IDs for retrieval.

```python
from xbrl_core import parse_footnote_links

footnote_map = parse_footnote_links(parsed.footnote_links)

fact_id = "IdFact1234"
notes = footnote_map.get(fact_id)
if notes:
    for note in notes:
        print(f"Footnote: {note.text} (lang={note.lang})")

print(f"Facts with footnotes: {footnote_map.fact_ids}")
```

--------------------------------

### Convert LineItems to DataFrame

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Converts parsed XBRL line items into a pandas DataFrame for analysis and provides export utilities for various file formats.

```python
from xbrl_core import line_items_to_dataframe, to_csv, to_parquet, to_excel

df = line_items_to_dataframe(items, label_lang="en")
print(df[["local_name", "label", "value", "period_end", "unit_ref"]].head(20))

by_period = df.groupby("period_end")["value"].sum()
```

--------------------------------

### Parse iXBRL (Inline XBRL) Documents with Python

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Parses iXBRL documents embedded in XHTML, returning a ParsedXBRL structure. Handles format attributes, scale/sign transformations, and continuation elements. Supports custom format registries and merging multiple iXBRL files. Requires lxml.

```python
from xbrl_core import parse_ixbrl_facts, merge_ixbrl_results, FormatRegistry

# Parse single iXBRL document
with open("report.htm", "rb") as f:
    parsed = parse_ixbrl_facts(f.read(), source_path="report.htm")

for fact in parsed.facts[:5]:
    print(f"{fact.local_name}: {fact.value_raw}")

# Custom format registry for locale-specific formats
registry = FormatRegistry()
registry.register("dateyearmonthdaycjk", lambda s: s.replace("年", "-").replace("月", "-").replace("日", ""))
parsed = parse_ixbrl_facts(ixbrl_bytes, format_registry=registry)

# Merge multiple iXBRL files (IXDS - Inline XBRL Document Set)
ixbrl_files = [open(f, "rb").read() for f in ["part1.htm", "part2.htm", "part3.htm"]]
results = [parse_ixbrl_facts(f) for f in ixbrl_files]
merged = merge_ixbrl_results(results)
print(f"Merged facts: {merged.fact_count}")
```

--------------------------------

### Parse Reference Linkbase

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Extracts authoritative references such as accounting standards or regulations from a reference linkbase file.

```python
from xbrl_core import parse_reference_linkbase

with open("taxonomy_ref.xml", "rb") as f:
    refs = parse_reference_linkbase(f.read())

for ref in refs:
    print(f"Concept: {ref.concept_name}")
    print(f"Role: {ref.role}")
    for part in ref.parts:
        print(f"  {part.local_name}: {part.value}")
    print("---")
```

--------------------------------

### Parsing Definition Linkbase

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Extracts dimensional relationships including hypercubes, axes, and domain members to understand the structure of XBRL tables.

```python
from xbrl_core import parse_definition_linkbase, ARCROLE_HYPERCUBE_DIMENSION

with open("taxonomy_def.xml", "rb") as f:
    def_lb = parse_definition_linkbase(f.read())

for role_uri in def_lb.role_uris:
    tree = def_lb.get_tree(role_uri)
    for hc in tree.hypercubes:
        print(f"Table: {hc.table_concept}")
```

--------------------------------

### Parsing Reference Linkbase

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

The `parse_reference_linkbase()` function extracts authoritative references (accounting standards, regulations) associated with concepts from XBRL taxonomy files.

```APIDOC
## Parsing Reference Linkbase

The `parse_reference_linkbase()` function extracts authoritative references (accounting standards, regulations) associated with concepts.

```python
from xbrl_core import parse_reference_linkbase

with open("taxonomy_ref.xml", "rb") as f:
    refs = parse_reference_linkbase(f.read())

for ref in refs:
    print(f"Concept: {ref.concept_name}")
    print(f"Role: {ref.role}")
    for part in ref.parts:
        print(f"  {part.local_name}: {part.value}")
    print("---")
```
```

--------------------------------

### Extract Text Blocks from XBRL Facts with Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Extracts facts of type `textBlockItemType` (e.g., Management Discussion & Analysis, risk factors) from XBRL filings. It utilizes `xbrl_core.extract_text_blocks` and `xbrl_core.clean_html` to process and clean HTML content into plain text, suitable for LLM/RAG pipelines. Inputs are XBRL facts and a context map.

```python
from xbrl_core import extract_text_blocks, clean_html

blocks = extract_text_blocks(parsed.facts, ctx_map)

for block in blocks:
    print(block.concept)         # "BusinessRisksTextBlock"
    print(block.period)          # DurationPeriod(...)
    plain = clean_html(block.html)
    print(plain[:200])
```

--------------------------------

### Parsing Footnotes

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

The `parse_footnote_links()` function extracts footnotes from XBRL instance documents and maps them to their associated facts.

```APIDOC
## Parsing Footnotes

The `parse_footnote_links()` function extracts footnotes from XBRL instance documents and maps them to their associated facts.

```python
from xbrl_core import parse_footnote_links

# Parse footnotes from parsed XBRL
footnote_map = parse_footnote_links(parsed.footnote_links)

# Get footnotes for a specific fact
fact_id = "IdFact1234"
notes = footnote_map.get(fact_id)
if notes:
    for note in notes:
        print(f"Footnote: {note.text} (lang={note.lang})")

# List all fact IDs with footnotes
print(f"Facts with footnotes: {footnote_map.fact_ids}")
print(f"Total facts with footnotes: {len(footnote_map)}")
```
```

--------------------------------

### Validate XBRL Calculations with Python

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Validates summation-item relationships in XBRL 2.1 documents using a specified calculation linkbase and items. It returns a validation result object indicating pass/fail status and details of any issues found. Dependencies include 'xbrl_core.validate_calculations' and 'xbrl_core.parse_calculation_linkbase'.

```python
from xbrl_core import validate_calculations, parse_calculation_linkbase

calc_lb = parse_calculation_linkbase(cal_xml_bytes)
result = validate_calculations(items, calc_lb)

print(result)           # "Calculation validation: PASS (checked=42, passed=42, errors=0, skipped=3)"
print(result.is_valid)  # True

for issue in result.issues:
    print(issue.parent_concept, issue.expected, issue.actual, issue.severity)
```

--------------------------------

### Override Concept Extraction Logic

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Shows how to provide a custom callable to the concept_extractor parameter to handle non-standard taxonomy naming conventions. The extractor function receives the xlink:href string and returns the extracted local name or None.

```python
import re
from xbrl_core import ConceptExtractor, parse_label_linkbase

def edinet_concept_extractor(href: str) -> str | None:
    """EDINET Strategy 2: extract local name by backward _[A-Z] scan."""
    if "#" not in href:
        return None
    fragment = href.rsplit("#", 1)[1]
    m = re.search(r"_([A-Z][A-Za-z0-9]*)$", fragment)
    return m.group(1) if m else fragment

labels = parse_label_linkbase(xml_bytes, concept_extractor=edinet_concept_extractor)
```

--------------------------------

### Handle parsing errors with lenient mode

Source: https://github.com/youseiushida/xbrl-core/blob/main/README.md

Configures the parser to ignore spec violations by setting strict=False, allowing access to ignored elements via the parsed object.

```python
parsed = parse_xbrl_facts(xbrl_bytes, strict=False)
for elem in parsed.ignored_elements:
    print(elem.reason, elem.source_line)
```

--------------------------------

### DataFrame Conversion

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

The `line_items_to_dataframe()` function converts LineItems to pandas DataFrame. Export functions support CSV, Parquet, and Excel formats.

```APIDOC
## DataFrame Conversion

The `line_items_to_dataframe()` function converts LineItems to pandas DataFrame. Export functions support CSV, Parquet, and Excel formats.

```python
from xbrl_core import line_items_to_dataframe, to_csv, to_parquet, to_excel

# Convert to DataFrame
df = line_items_to_dataframe(items, label_lang="en")

# View data
print(df[["local_name", "label", "value", "period_end", "unit_ref"]].head(20))

# Filter numeric facts
numeric_df = df[df["unit_ref"].notna()]

# Group by period
by_period = df.groupby("period_end")["value"].sum()
```
```

--------------------------------

### Validate XBRL Calculations

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

Performs summation-item relationship validation based on XBRL 2.1 standards, supporting rounding tolerance and specific role filtering.

```python
from xbrl_core import validate_calculations, parse_calculation_linkbase, build_line_items, structure_contexts

ctx_map = structure_contexts(parsed.contexts)
items = build_line_items(parsed.facts, ctx_map)

with open("taxonomy_cal.xml", "rb") as f:
    calc_lb = parse_calculation_linkbase(f.read())

result = validate_calculations(items, calc_lb)
print(result)
for issue in result.issues:
    print(f"Concept: {issue.parent_concept}, Severity: {issue.severity}")
```

--------------------------------

### Text Block Extraction

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

The `extract_text_blocks()` function extracts textBlockItemType facts (MD&A, risk factors, notes) from filings. The `clean_html()` function converts HTML to plain text.

```APIDOC
## Text Block Extraction

The `extract_text_blocks()` function extracts textBlockItemType facts (MD&A, risk factors, notes) from filings. The `clean_html()` function converts HTML to plain text.

```python
from xbrl_core import extract_text_blocks, clean_html, structure_contexts

ctx_map = structure_contexts(parsed.contexts)
blocks = extract_text_blocks(parsed.facts, ctx_map)

for block in blocks:
    print(f"Concept: {block.concept}")          # "BusinessRisksTextBlock"
    print(f"Period: {block.period}")            # DurationPeriod(...)
    print(f"Context: {block.context_ref}")

    # Convert HTML to plain text (preserves table structure)
    plain_text = clean_html(block.html)
    print(f"Content preview: {plain_text[:500]}...")
    print("---")
```
```

--------------------------------

### Calculation Validation

Source: https://context7.com/youseiushida/xbrl-core/llms.txt

The `validate_calculations()` function validates summation-item relationships per XBRL 2.1 section 5.2.5.2, with decimals-based rounding tolerance.

```APIDOC
## Calculation Validation

The `validate_calculations()` function validates summation-item relationships per XBRL 2.1 section 5.2.5.2, with decimals-based rounding tolerance.

```python
from xbrl_core import validate_calculations, parse_calculation_linkbase, build_line_items, structure_contexts

# Build LineItems
ctx_map = structure_contexts(parsed.contexts)
items = build_line_items(parsed.facts, ctx_map)

# Parse calculation linkbase
with open("taxonomy_cal.xml", "rb") as f:
    calc_lb = parse_calculation_linkbase(f.read())

# Validate calculations
result = validate_calculations(items, calc_lb)

print(result)  # "Calculation validation: PASS (checked=42, passed=42, errors=0, skipped=3)"
print(f"Valid: {result.is_valid}")
print(f"Errors: {result.error_count}")
print(f"Warnings: {result.warning_count}")

# Examine individual issues
for issue in result.issues:
    print(f"Concept: {issue.parent_concept}")
    print(f"Expected: {issue.expected}, Actual: {issue.actual}")
    print(f"Difference: {issue.difference}, Tolerance: {issue.tolerance}")
    print(f"Severity: {issue.severity}")
    print(f"Message: {issue.message}")

# Validate specific role only
result = validate_calculations(items, calc_lb, role_uri="http://example.com/role/BalanceSheet")
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.