XBridge (eba-xbridge) #####################

.. image:: https://img.shields.io/pypi/v/eba-xbridge.svg :target: https://pypi.org/project/eba-xbridge/ :alt: PyPI version

.. image:: https://img.shields.io/pypi/pyversions/eba-xbridge.svg :target: https://pypi.org/project/eba-xbridge/ :alt: Python versions

.. image:: https://img.shields.io/github/license/Meaningful-Data/xbridge.svg :target: https://github.com/Meaningful-Data/xbridge/blob/main/LICENSE :alt: License

.. image:: https://img.shields.io/github/actions/workflow/status/Meaningful-Data/xbridge/testing.yml?branch=main :target: https://github.com/Meaningful-Data/xbridge/actions :alt: Build status

Overview

XBridge is a Python library for converting XBRL-XML files into XBRL-CSV files using the EBA (European Banking Authority) taxonomy. It provides a simple, reliable way to transform regulatory reporting data from XML format to CSV format.

The library supports EBA Taxonomy versions 4.2 and 4.2.1 and includes support for DORA (Digital Operational Resilience Act) CSV conversion. The library must be updated with each new EBA taxonomy version release.

Key Features

• XBRL-XML to XBRL-CSV Conversion: Seamlessly convert XBRL-XML instance files to XBRL-CSV format
• Command-Line Interface: Quick conversions without writing code using the xbridge CLI
• Python API: Programmatic conversion for integration with other tools and workflows
• EBA Taxonomy 4.2/4.2.1 Support: Built for the latest EBA taxonomy specification
• DORA CSV Conversion: Support for Digital Operational Resilience Act reporting
• Standalone Validation: Validate XBRL-XML and XBRL-CSV files against structural and EBA rules via CLI or Python API
• Configurable Validation: Flexible filing indicator validation with strict or warning modes
• Decimal Handling: Intelligent decimal precision handling with configurable options
• Type Safety: Fully typed codebase with MyPy strict mode compliance
• Python 3.9+: Supports Python 3.9 through 3.13

Prerequisites

• Python: 3.9 or higher

• 7z Command-Line Tool: Required for loading compressed taxonomy files (7z or ZIP format)

  • On Ubuntu/Debian: sudo apt-get install p7zip-full
  • On macOS: brew install p7zip
  • On Windows: Download from 7-zip.org <https://www.7-zip.org/>_

Installation

Install XBridge from PyPI using pip:

.. code-block:: bash

pip install eba-xbridge

For development installation, see CONTRIBUTING.md <CONTRIBUTING.md>_.

Quick Start

XBridge offers two ways to convert XBRL-XML files to XBRL-CSV: a command-line interface (CLI) for quick conversions, and a Python API for programmatic use.

Command-Line Interface

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

.. code-block:: bash

# 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:

.. code-block:: python

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:

.. code-block:: python

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:

.. code-block:: python

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:

.. code-block:: python

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:

.. code-block:: bash

# 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:

.. code-block:: python

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:

.. code-block:: python

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:

.. code-block:: python

from xbridge.api import load_instance

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

# Access in