eba-xbridge 1.5.0rc2__tar.gz → 1.5.0rc4__tar.gz

eba_xbridge-1.5.0rc4/PKG-INFO

@@ -0,0 +1,308 @@
+Metadata-Version: 2.4
+Name: eba-xbridge
+Version: 1.5.0rc4
+Summary: XBRL-XML to XBRL-CSV converter for EBA Taxonomy (version 4.1)
+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 currently supports **EBA Taxonomy version 4.2** 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 Support**: Built for the latest EBA taxonomy specification
+* **DORA CSV Conversion**: Support for Digital Operational Resilience Act reporting
+* **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
+
+**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
+
+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
+    )
+
+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)
+
+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.1.
+
+**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
+

eba_xbridge-1.5.0rc4/README.rst

@@ -0,0 +1,279 @@
+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 currently supports **EBA Taxonomy version 4.2** 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 Support**: Built for the latest EBA taxonomy specification
+* **DORA CSV Conversion**: Support for Digital Operational Resilience Act reporting
+* **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
+
+**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
+
+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
+    )
+
+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)
+
+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.1.
+
+**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

{eba_xbridge-1.5.0rc2 → eba_xbridge-1.5.0rc4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "eba-xbridge"
-version = "1.5.0rc2"
+version = "1.5.0rc4"
 description = "XBRL-XML to XBRL-CSV converter for EBA Taxonomy (version 4.1)"
 license = 'Apache 2.0'
 readme = "README.rst"
@@ -37,6 +37,9 @@ Documentation = 'https://docs.xbridge.meaningfuldata.eu'
 MeaningfulData = 'https://www.meaningfuldata.eu/'
 IssueTracker = 'https://github.com/Meaningful-Data/xbridge/issues'
 
+[project.scripts]
+xbridge = "xbridge.__main__:main"
+
 [tool.poetry]
 packages = [{ include = "xbridge", from = "src" }]
 

{eba_xbridge-1.5.0rc2 → eba_xbridge-1.5.0rc4}/src/xbridge/__init__.py

@@ -2,4 +2,4 @@
 Init file for eba-xbridge library
 """
 
-__version__ = "1.5.0rc2"
+__version__ = "1.5.0rc4"

eba_xbridge-1.5.0rc4/src/xbridge/__main__.py

@@ -0,0 +1,82 @@
+"""Command-line interface for xbridge."""
+
+import argparse
+import sys
+from pathlib import Path
+
+from xbridge.api import convert_instance
+
+
+def main() -> None:
+    """Main CLI entry point for xbridge converter."""
+    parser = argparse.ArgumentParser(
+        description="Convert XBRL-XML instances to XBRL-CSV format",
+        prog="xbridge",
+    )
+
+    parser.add_argument(
+        "input_file",
+        type=str,
+        help="Path to the input XBRL-XML file",
+    )
+
+    parser.add_argument(
+        "--output-path",
+        type=str,
+        default=None,
+        help="Output directory path (default: same folder as input file)",
+    )
+
+    parser.add_argument(
+        "--headers-as-datapoints",
+        action="store_true",
+        default=False,
+        help="Treat headers as datapoints (default: False)",
+    )
+
+    parser.add_argument(
+        "--strict-validation",
+        action="store_true",
+        default=True,
+        help="Raise errors on validation failures (default: True)",
+    )
+
+    parser.add_argument(
+        "--no-strict-validation",
+        action="store_false",
+        dest="strict_validation",
+        help="Emit warnings instead of errors for validation failures",
+    )
+
+    args = parser.parse_args()
+
+    # Determine output path
+    input_path = Path(args.input_file)
+    if not input_path.exists():
+        print(f"Error: Input file not found: {args.input_file}", file=sys.stderr)
+        sys.exit(1)
+
+    if args.output_path is None:
+        output_path = input_path.parent
+    else:
+        output_path = Path(args.output_path)
+        if not output_path.exists():
+            print(f"Error: Output path does not exist: {args.output_path}", file=sys.stderr)
+            sys.exit(1)
+
+    try:
+        result_path = convert_instance(
+            instance_path=input_path,
+            output_path=output_path,
+            headers_as_datapoints=args.headers_as_datapoints,
+            validate_filing_indicators=True,
+            strict_validation=args.strict_validation,
+        )
+        print(f"Conversion successful: {result_path}")
+    except Exception as e:
+        print(f"Conversion failed: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()