Quickstart Guide

This guide will help you get started with XBridge quickly. By the end of this tutorial, you’ll be able to convert XBRL-XML files to XBRL-CSV format.

Prerequisites

Before you begin, ensure you have:

  1. Python 3.9 or higher installed

    Check your Python version:

    python --version

  2. 7z command-line tool (required for taxonomy loading)

    • Ubuntu/Debian:

      sudo apt-get install p7zip-full

    • macOS:

      brew install p7zip

    • Windows: Download from 7-zip.org

Installation

Install XBridge using pip:

pip install eba-xbridge

Verify the installation:

python -c "import xbridge; print(xbridge.__version__)"

Your First Conversion

XBridge offers two ways to convert files: using the command-line interface (CLI) or the Python API. Choose the method that best fits your workflow.

Step 3: Extract and Examine the Output

Extract the ZIP file:

unzip output/instance.zip -d output/extracted

Examine the structure:

tree output/extracted

You’ll see:

output/extracted/
├── META-INF/
│   └── reports.json
├── reports/
│   ├── table_1.csv
│   ├── table_2.csv
│   └── ...
├── filing-indicators.csv
└── parameters.csv

Common Use Cases

Use Case 1: Convert with Validation

Enable filing indicator validation to ensure data integrity:

from xbridge.api import convert_instance

output = convert_instance(
    instance_path="instance.xbrl",
    output_path="output",
    validate_filing_indicators=True,  # Enable validation
    strict_validation=True  # Raise errors on issues
)

Use Case 2: Handle Validation Warnings

If you want to continue despite validation issues:

import logging
from xbridge.api import convert_instance

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

output = convert_instance(
    instance_path="instance.xbrl",
    output_path="output",
    validate_filing_indicators=True,
    strict_validation=False  # Emit warnings instead of errors
)

Use Case 3: Inspect Instance Before Converting

Load and inspect an instance to understand its contents:

from xbridge.api import load_instance, convert_instance

# Load the instance
instance = load_instance("instance.xbrl")

# Inspect
print(f"Entity: {instance.entity}")
print(f"Period: {instance.period}")
print(f"Total facts: {len(instance.facts)}")
print(f"Total contexts: {len(instance.contexts)}")

# If everything looks good, convert
if len(instance.facts) > 0:
    output = convert_instance("instance.xbrl", "output")
    print(f"Converted: {output}")
else:
    print("No facts found, skipping conversion")

Use Case 4: Batch Processing

Convert multiple XBRL files at once:

from pathlib import Path
from xbridge.api import convert_instance

# Set up directories
input_dir = Path("instances")
output_dir = Path("converted")
output_dir.mkdir(exist_ok=True)

# Process all XBRL files
xbrl_files = list(input_dir.glob("*.xbrl"))
print(f"Found {len(xbrl_files)} files to convert")

for xbrl_file in xbrl_files:
    print(f"\nConverting: {xbrl_file.name}")
    try:
        output = convert_instance(
            instance_path=xbrl_file,
            output_path=output_dir / xbrl_file.stem,
            strict_validation=False  # Continue on errors
        )
        print(f"  ✓ Success: {output}")
    except Exception as e:
        print(f"  ✗ Failed: {e}")

print("\nBatch conversion complete!")

Use Case 5: Custom Output Handling

Process the output programmatically:

import zipfile
import csv
from pathlib import Path
from xbridge.api import convert_instance

# Convert
output_zip = convert_instance(
    instance_path="instance.xbrl",
    output_path="output"
)

# Extract and process
with zipfile.ZipFile(output_zip, 'r') as zf:
    # List all files
    print("Files in archive:")
    for name in zf.namelist():
        print(f"  - {name}")

    # Read parameters
    with zf.open('parameters.csv') as f:
        reader = csv.DictReader(f.read().decode('utf-8').splitlines())
        for row in reader:
            print(f"\nParameters:")
            for key, value in row.items():
                print(f"  {key}: {value}")

Advanced Configuration

Headers as Datapoints

Include table headers as datapoints in the output:

from xbridge.api import convert_instance

output = convert_instance(
    instance_path="instance.xbrl",
    output_path="output",
    headers_as_datapoints=True  # Include headers
)

Error Handling

Robust error handling for production use:

from xbridge.api import convert_instance
from pathlib import Path
import sys

def safe_convert(instance_path, output_path):
    """Safely convert with comprehensive error handling."""
    try:
        # Validate inputs
        instance = Path(instance_path)
        if not instance.exists():
            raise FileNotFoundError(f"Instance not found: {instance}")

        if not instance.suffix == ".xbrl":
            raise ValueError(f"Expected .xbrl file, got {instance.suffix}")

        # Convert
        output = convert_instance(
            instance_path=instance,
            output_path=output_path,
            validate_filing_indicators=True,
            strict_validation=False
        )

        return output, None

    except FileNotFoundError as e:
        return None, f"File error: {e}"
    except ValueError as e:
        return None, f"Validation error: {e}"
    except Exception as e:
        return None, f"Unexpected error: {e}"

# Use the safe function
result, error = safe_convert("instance.xbrl", "output")

if error:
    print(f"✗ Conversion failed: {error}", file=sys.stderr)
    sys.exit(1)
else:
    print(f"✓ Conversion succeeded: {result}")

Next Steps

Now that you’ve completed the quickstart:

  1. Explore the Documentation: Check the Command-Line Interface and API Reference references

  2. Understand the Architecture: Learn how XBridge works internally in Technical notes

  3. Check the FAQ: Find answers to common questions in Frequently Asked Questions (FAQ)

  4. Explore Examples: See more examples in the GitHub repository

Troubleshooting

ImportError: No module named ‘xbridge’

XBridge is not installed. Run pip install eba-xbridge

FileNotFoundError: instance.xbrl not found

Check the file path is correct and the file exists

7z command not found

Install the 7z tool (see Prerequisites section)

Orphaned facts error/warning

Some facts don’t belong to any reported table. Use strict_validation=False to continue with warnings

Very large file processing slowly

This is normal for large XBRL files. Consider processing in smaller batches

Getting Help

If you encounter issues: