eba-xbridge 2.2.0

Command-Line Interface

The CLI provides a quick way to convert files without writing code:

# Basic conversion (output to same directory as input)
xbridge instance.xbrl

# Specify output directory
xbridge instance.xbrl --output-path ./output

# Continue with warnings instead of errors
xbridge instance.xbrl --no-strict-validation

# Include headers as datapoints
xbridge instance.xbrl --headers-as-datapoints

# Validate before and after conversion
xbridge instance.xbrl --validate

# Validate with EBA-specific rules
xbridge instance.xbrl --validate --eba

CLI Options:

• --output-path PATH: Output directory (default: same as input file)

• --headers-as-datapoints: Treat headers as datapoints (default: False)

• --strict-validation: Raise errors on validation failures (default: True)

• --no-strict-validation: Emit warnings instead of errors

• --validate: Run validation before and after conversion (default: False)

• --eba: Enable EBA-specific validation rules (only applies with --validate)

For more CLI options, run xbridge --help.

Python API - Basic Conversion

Convert an XBRL-XML instance file to XBRL-CSV using the Python API:

from xbridge.api import convert_instance

# Basic conversion
input_path = "path/to/instance.xbrl"
output_path = "path/to/output"

convert_instance(input_path, output_path)

The converted XBRL-CSV files will be saved as a ZIP archive in the output directory.

Python API - Advanced Usage

Customize the conversion with additional parameters:

from xbridge.api import convert_instance

# Conversion with custom options
convert_instance(
    instance_path="path/to/instance.xbrl",
    output_path="path/to/output",
    headers_as_datapoints=True,  # Treat headers as datapoints
    validate_filing_indicators=True,  # Validate filing indicators
    strict_validation=False,  # Emit warnings instead of errors for orphaned facts
)

# Validate-convert-validate pipeline
from xbridge.exceptions import ValidationError

try:
    convert_instance(
        instance_path="path/to/instance.xbrl",
        output_path="path/to/output",
        validate=True,   # Enable pre/post-conversion validation
        eba=True,         # Include EBA-specific rules
    )
except ValidationError as e:
    print(f"Validation failed: {e}")
    if e.path:
        print(f"Output was written to: {e.path}")
    for section in e.results.values():
        for code, findings in section["errors"].items():
            for f in findings:
                print(f"  [{f['severity']}] {f['rule_id']}: {f['message']}")

Python API - Handling Warnings

XBridge emits structured warnings that can be filtered or turned into errors from your code. The most common ones are:

• IdentifierPrefixWarning: Unknown entity identifier prefix; XBridge falls back to rs.

• FilingIndicatorWarning: Filing indicator inconsistencies; some facts are excluded.

To capture these warnings when using convert_instance:

import warnings
from xbridge.api import convert_instance
from xbridge.exceptions import XbridgeWarning, FilingIndicatorWarning

input_path = "path/to/instance.xbrl"
output_path = "path/to/output"

with warnings.catch_warnings(record=True) as caught:
    # Ensure all xbridge warnings are captured
    warnings.simplefilter("always", XbridgeWarning)

    zip_path = convert_instance(
        instance_path=input_path,
        output_path=output_path,
        validate_filing_indicators=True,
        strict_validation=False,  # Warnings instead of errors for orphaned facts
    )

filing_warnings = [
    w for w in caught if issubclass(w.category, FilingIndicatorWarning)
]
for w in filing_warnings:
    print(f"Filing indicator warning: {w.message}")

To treat all XBridge warnings as errors:

import warnings
from xbridge.api import convert_instance
from xbridge.exceptions import XbridgeWarning

with warnings.catch_warnings():
    warnings.simplefilter("error", XbridgeWarning)
    convert_instance("path/to/instance.xbrl", "path/to/output")

Validation - Command-Line Interface

The validate subcommand checks XBRL instance files against structural and regulatory rules without performing conversion:

# Validate an XBRL-XML file
xbridge validate instance.xbrl

# Enable EBA-specific rules (entity, currency, decimals, etc.)
xbridge validate instance.xbrl --eba

# Validate an XBRL-CSV package
xbridge validate report.zip --eba

# Skip structural checks for xbridge-generated CSV output
xbridge validate output.zip --eba --post-conversion

# Get machine-readable JSON output
xbridge validate instance.xbrl --eba --json

Validate Options:

• --eba: Enable EBA-specific validation rules (default: False)

• --post-conversion: Skip structural checks guaranteed by xbridge’s converter (CSV only, default: False)

• --json: Output findings as JSON instead of human-readable text

The validate command exits with code 0 when no errors are found, and 1 when at least one ERROR-level finding is present.

For more options, run xbridge validate --help.

Validation - Python API

Validate XBRL files programmatically using the validate() function:

from xbridge.validation import validate

# Validate an XBRL-XML file
results = validate("path/to/instance.xbrl")

# Enable EBA-specific rules
results = validate("path/to/instance.xbrl", eba=True)

# Validate an XBRL-CSV package
results = validate("path/to/report.zip", eba=True)

The validate() function returns a dictionary keyed by validation scope ("XBRL" always present, "EBA" when eba=True). Each scope contains "errors" and "warnings" dicts keyed by rule code:

from xbridge.validation import validate

results = validate("path/to/instance.xbrl", eba=True)

for scope, section in results.items():
    for code, findings in section["errors"].items():
        for f in findings:
            print(f"[{scope}] [{f['severity']}] {f['rule_id']}: {f['message']}")
            print(f"  Location: {f['location']}")

error_count = sum(
    len(v) for section in results.values() for v in section["errors"].values()
)
warning_count = sum(
    len(v) for section in results.values() for v in section["warnings"].values()
)
print(f"Errors: {error_count}, Warnings: {warning_count}")

Loading an Instance

Load and inspect an XBRL-XML instance without converting:

from xbridge.api import load_instance

instance = load_instance("path/to/instance.xbrl")

# Access instance properties
print(f"Entity: {instance.entity}")
print(f"Period: {instance.period}")
print(f"Facts count: {len(instance.facts)}")

Output Structure

The output ZIP file contains:

• META-INF/: JSON report package metadata

• reports/: CSV files for each reported table

• filing-indicators.csv: Table reporting indicators

• parameters.csv: Report-level parameters