API Reference

This is the API module of XBridge, providing the main interface for converting XBRL-XML files to XBRL-CSV format.

Python API

Convert XBRL Instance to CSV

xbridge.api.convert_instance(instance_path: str | Path, output_path: str | Path | None = None, headers_as_datapoints: bool = False, validate_filing_indicators: bool = True, strict_validation: bool = True, validate: bool = False, eba: bool = False) → Path

Convert one single instance of XBRL-XML file to a CSV file

Parameters:

instance_path – Path to the XBRL-XML instance
output_path – Path to the output CSV file
headers_as_datapoints – If True, the headers will be treated as datapoints.
validate_filing_indicators – If True, validate that no facts are orphaned (belong only to non-reported tables). Default is True.
strict_validation – If True (default), raise an error when facts are lost — orphaned facts (FilingIndicatorValueError) and, from the fact reconciliation census, facts matching no table or elements not recognised as facts (FactReconciliationError). If False, emit warnings instead and continue. The census is stored on Converter.reconciliation regardless of this flag.
validate – If True, run validation before and after conversion. Pre-conversion errors stop the pipeline; post-conversion errors are reported after the output file has been written. Default is False.
eba – If True, enable EBA-specific validation rules. Only used when validate is True. Default is False.

Returns:

Converted CSV file.

Raises:

ValidationError – When validate is True and validation finds errors.

Basic Usage

Convert an XBRL-XML instance file with default settings:

from xbridge.api import convert_instance

# Simple conversion
result = convert_instance(
    instance_path="data/instance.xbrl",
    output_path="data/output"
)
print(f"Conversion complete: {result}")

Advanced Usage Examples

Convert with Custom Options

Use all available parameters for fine-grained control:

from xbridge.api import convert_instance
from pathlib import Path

# Advanced conversion with all options
output_file = convert_instance(
    instance_path=Path("data/regulatory_report.xbrl"),
    output_path=Path("data/converted"),
    headers_as_datapoints=True,  # Include headers as datapoints
    validate_filing_indicators=True,  # Validate orphaned facts + reconcile facts
    strict_validation=False  # Emit warnings instead of raising errors
)

print(f"Conversion saved to: {output_file}")

Handle Validation Warnings

Use non-strict validation to continue despite orphaned facts:

import logging
from xbridge.api import convert_instance

# Configure logging to see warnings
logging.basicConfig(level=logging.WARNING)

# Convert with warnings instead of errors
try:
    result = convert_instance(
        instance_path="data/instance_with_issues.xbrl",
        output_path="data/output",
        validate_filing_indicators=True,
        strict_validation=False  # Continue despite validation issues
    )
    print(f"Conversion completed with warnings: {result}")
except Exception as e:
    print(f"Conversion failed: {e}")

Batch Conversion

Convert multiple files in a directory:

from pathlib import Path
from xbridge.api import convert_instance

input_dir = Path("data/instances")
output_dir = Path("data/converted")
output_dir.mkdir(exist_ok=True)

# Convert all XBRL files
for xbrl_file in input_dir.glob("*.xbrl"):
    print(f"Converting {xbrl_file.name}...")
    try:
        output_file = convert_instance(
            instance_path=xbrl_file,
            output_path=output_dir / xbrl_file.stem
        )
        print(f"  ✓ Success: {output_file}")
    except Exception as e:
        print(f"  ✗ Failed: {e}")

Parameters

param instance_path:: Path to the XBRL-XML instance file. Accepts str or pathlib.Path.
param output_path:: Directory where the converted CSV files will be saved. If None, uses the current directory. Accepts str, pathlib.Path, or None.
param headers_as_datapoints:: If True, table headers are treated as datapoints in the output. Default is False.
param validate_filing_indicators:: If True, validates that all facts belong to reported tables (no orphaned facts). Default is True.
param strict_validation:: If True, raises an error when facts are lost — orphaned facts (FilingIndicatorValueError) or, from the fact reconciliation census, facts matching no table / elements not recognised as facts (FactReconciliationError). If False, emits a warning and continues. Only relevant when validate_filing_indicators=True. Default is True.
return:: pathlib.Path object pointing to the generated ZIP file containing XBRL-CSV output.
raises FileNotFoundError:: If the instance file doesn’t exist.
raises ValueError:: If validation fails and strict_validation=True (FilingIndicatorValueError and FactReconciliationError are ValueError subclasses).
raises Exception:: For other conversion errors (malformed XML, taxonomy issues, etc.).

Note

After conversion, Converter.reconciliation holds a FactReconciliation accounting for every source fact (converted / excluded_non_reported / unmatched / unrecognized_elements). Inspect has_silent_loss to detect whether any facts were dropped without an explicit filing-indicator reason.

Load an XBRL-XML Instance

xbridge.api.load_instance(instance_path: str | Path) → Instance

Load an XBRL XML instance file

Parameters:: instance_path – Path to the instance XBRL file
Returns:: An instance object may be return

Usage Examples

Basic Instance Loading

Load and inspect an XBRL-XML instance:

from xbridge.api import load_instance

# Load instance
instance = load_instance("data/instance.xbrl")

# Access instance properties
print(f"Entity: {instance.entity}")
print(f"Period: {instance.period}")
print(f"Number of facts: {len(instance.facts)}")
print(f"Number of contexts: {len(instance.contexts)}")

Inspect Instance Details

Examine facts and contexts in detail:

from xbridge.api import load_instance

instance = load_instance("data/regulatory_report.xbrl")

# Inspect facts
print(f"Total facts: {len(instance.facts)}")
for i, fact in enumerate(instance.facts[:5]):  # First 5 facts
    print(f"Fact {i+1}:")
    print(f"  Concept: {fact.concept}")
    print(f"  Value: {fact.value}")
    print(f"  Context: {fact.context_ref}")
    print(f"  Decimals: {fact.decimals}")

# Inspect contexts
print(f"\nTotal contexts: {len(instance.contexts)}")
for context_id, context in list(instance.contexts.items())[:3]:
    print(f"Context {context_id}:")
    print(f"  Entity: {context.entity}")
    print(f"  Period: {context.period}")

Validate Before Conversion

Load an instance to validate it before conversion:

from xbridge.api import load_instance, convert_instance
from pathlib import Path

instance_path = Path("data/report.xbrl")

# Load and validate
try:
    instance = load_instance(instance_path)

    # Check basic requirements
    if not instance.facts:
        raise ValueError("Instance has no facts")

    if not instance.entity:
        raise ValueError("Instance has no entity information")

    print(f"✓ Validation passed")
    print(f"  Entity: {instance.entity}")
    print(f"  Facts: {len(instance.facts)}")

    # Proceed with conversion
    output = convert_instance(instance_path, "data/output")
    print(f"✓ Conversion successful: {output}")

except Exception as e:
    print(f"✗ Validation or conversion failed: {e}")

load_instance() Parameters

param instance_path:: Path to the XBRL-XML instance file. Accepts str or pathlib.Path.
return:: Instance object containing parsed XBRL data.
raises FileNotFoundError:: If the instance file doesn’t exist.
raises Exception:: If the XML is malformed or cannot be parsed.

Return Value

Returns an Instance object with the following main attributes:

facts: List of all facts in the instance
contexts: Dictionary of contexts (key: context ID)
entity: Entity identifier
period: Reporting period
filing_indicators: List of filing indicators
base_currency: Base currency code

See XML Instance for complete Instance class documentation