Metadata-Version: 2.4
Name: eba-xbridge
Version: 2.0.0rc7
Summary: XBRL-XML to XBRL-CSV converter for EBA Taxonomy (version 4.2)
License: Apache 2.0
License-File: LICENSE
Keywords: xbrl,eba,taxonomy,csv,xml
Author: MeaningfulData
Author-email: info@meaningfuldata.eu
Maintainer: Antonio Olleros
Maintainer-email: antonio.olleros@meaningfuldata.eu
Requires-Python: >=3.9
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Dist: lxml (>=5.2.1,<6.0)
Requires-Dist: numpy (>=1.23.2,<2) ; python_version < "3.13"
Requires-Dist: numpy (>=2.1.0) ; python_version >= "3.13"
Requires-Dist: pandas (>=2.1.4,<3.0)
Project-URL: Documentation, https://docs.xbridge.meaningfuldata.eu
Project-URL: IssueTracker, https://github.com/Meaningful-Data/xbridge/issues
Project-URL: MeaningfulData, https://www.meaningfuldata.eu/
Project-URL: Repository, https://github.com/Meaningful-Data/xbridge
Description-Content-Type: text/x-rst

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 code, findings in e.results["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 with two keys — ``"errors"`` and ``"warnings"`` — each containing a dict keyed by rule code with lists of finding dicts:

.. code-block:: python

    from xbridge.validation import validate

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

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

    error_count = sum(len(v) for v in results["errors"].values())
    warning_count = sum(len(v) for v in results["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 instance properties
    print(f"Entity: {instance.entity}")
    print(f"Period: {instance.period}")
    print(f"Facts count: {len(instance.facts)}")

How XBridge Works
=================

XBridge performs the conversion in several steps:

1. **Load the XBRL-XML instance**: Parse and extract facts, contexts, scenarios, and filing indicators
2. **Load the EBA taxonomy**: Access pre-processed taxonomy modules containing tables and variables
3. **Match and validate**: Join instance facts with taxonomy definitions
4. **Generate CSV files**: Create XBRL-CSV files including:

   * Data tables with facts and dimensions
   * Filing indicators showing reported tables
   * Parameters (entity, period, base currency, decimals)

5. **Package output**: Bundle all CSV files into a ZIP archive

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

Documentation
=============

Comprehensive documentation is available at `docs.xbridge.meaningfuldata.eu <https://docs.xbridge.meaningfuldata.eu>`_.

The documentation includes:

* **API Reference**: Complete API documentation
* **Quickstart Guide**: Step-by-step tutorials
* **Technical Notes**: Architecture and design details
* **FAQ**: Frequently asked questions

Taxonomy Loading
================

If you need to work with the EBA taxonomy directly, you can load it using:

.. code-block:: bash

    python -m xbridge.taxonomy_loader --input_path path/to/FullTaxonomy.7z

This generates an ``index.json`` file containing module references and pre-processed taxonomy data.

.. warning::
    Loading the taxonomy from a 7z package may take several minutes. Ensure the ``7z`` command is available on your system.

Configuration Options
=====================

convert_instance Parameters
----------------------------

* **instance_path** (str | Path): Path to the XBRL-XML instance file
* **output_path** (str | Path | None): Output directory for CSV files (default: current directory)
* **headers_as_datapoints** (bool): Treat table headers as datapoints (default: False)
* **validate_filing_indicators** (bool): Validate that facts belong to reported tables (default: True)
* **strict_validation** (bool): Raise errors on validation failures; if False, emit warnings (default: True)
* **validate** (bool): Run validation before and after conversion; raises ``ValidationError`` on errors (default: False)
* **eba** (bool): Enable EBA-specific validation rules; only used when *validate* is True (default: False)

Troubleshooting
===============

Common Issues
-------------

**7z command not found**
    Install the 7z command-line tool using your system's package manager (see Prerequisites).

**Taxonomy version mismatch**
    Ensure you're using the correct version of XBridge for your taxonomy version. XBridge 1.5.x supports EBA Taxonomy 4.2.

**Orphaned facts warning/error**
    Facts that don't belong to any reported table. Set ``strict_validation=False`` to continue with warnings instead of errors.

**Decimal precision issues**
    XBridge automatically handles decimal precision from the taxonomy. Check the parameters.csv file for applied decimal settings.

For more issues, see our `FAQ <https://docs.xbridge.meaningfuldata.eu/faq.html>`_ or `open an issue <https://github.com/Meaningful-Data/xbridge/issues>`_.

Contributing
============

We welcome contributions! Please see `CONTRIBUTING.md <CONTRIBUTING.md>`_ for:

* Development setup instructions
* Code style guidelines
* Testing requirements
* Pull request process

Before contributing, please read our `Code of Conduct <CODE_OF_CONDUCT.md>`_.

Changelog
=========

See `CHANGELOG.md <CHANGELOG.md>`_ for a detailed history of changes.

Support
=======

* **Documentation**: https://docs.xbridge.meaningfuldata.eu
* **Issue Tracker**: https://github.com/Meaningful-Data/xbridge/issues
* **Email**: info@meaningfuldata.eu
* **Company**: https://www.meaningfuldata.eu/

Security
========

For security issues, please see our `Security Policy <SECURITY.md>`_.

License
=======

This project is licensed under the Apache License 2.0 - see the `LICENSE <LICENSE>`_ file for details.

Authors & Maintainers
=====================

**MeaningfulData** - https://www.meaningfuldata.eu/

Maintainers:

* Antonio Olleros (antonio.olleros@meaningfuldata.eu)
* Jesus Simon (jesus.simon@meaningfuldata.eu)
* Francisco Javier Hernandez del Caño (javier.hernandez@meaningfuldata.eu)
* Guillermo Garcia Martin (guillermo.garcia@meaningfuldata.eu)

Acknowledgments
===============

This project is designed to work with the European Banking Authority (EBA) taxonomy for regulatory reporting

