eba-xbridge 1.5.0rc3__py3-none-any.whl → 1.5.0rc4__py3-none-any.whl

eba_xbridge-1.5.0rc4.dist-info/METADATA

@@ -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.0rc3.dist-info → eba_xbridge-1.5.0rc4.dist-info}/RECORD

@@ -1,7 +1,8 @@
-xbridge/__init__.py,sha256=H66PeuXAnonjcj2yXO8Tis9cgDs-cTh3i3vXOYpDnFw,68
+xbridge/__init__.py,sha256=joASbfhYee_2irYZhRCZ6J4oTn6u1fjt6ilQbXwL4M4,68
+xbridge/__main__.py,sha256=trtFEv7TRJgrLL84leIapPvgC_iVTj05qLHRRS1Olts,2219
 xbridge/api.py,sha256=NCBz7VRJWE3gID6ndgL4Awoxw0w1yMIIf_OTLRuZyyQ,1559
-xbridge/converter.py,sha256=Xft2lc5R1MMDNftlKRj7NuLTGhDHej-T4xc-z_roIeM,24433
-xbridge/instance.py,sha256=_UNB2j6ykHeOPb18TuDGw8qMq0ER-bV6FYTz7tSmDxc,29709
+xbridge/converter.py,sha256=uu6djzgGZcmq0nibrkmg5lW-npcolB4XtQoNWu1p_3o,23498
+xbridge/instance.py,sha256=KQpXhsZIM9oTYJf2hyrzc9pqFY2-1JBF5y1xbnLbqk8,29991
 xbridge/modules/ae_ae_4.2.json,sha256=AdFvwZqX0KVP3jF1iHeQc5QSnSMvvT3GvoA2G1AgXis,460165
 xbridge/modules/ae_con_cir-680-2014_2017-04-04.json,sha256=4n0t9dKJNU8Nb5QHpssrDs8ZLwzI-Mw75ax-ar9pLu0,363273
 xbridge/modules/ae_con_cir-680-2014_2018-03-31.json,sha256=aVWeLLs20p39kQQUthUzqrxBGKTycqhgX9WLk1rVlNw,363538
@@ -379,10 +380,11 @@ xbridge/modules/sbpimv_ind_its-2016-svbxx_2016-02-01.json,sha256=SED-dW--UKxhHNY
 xbridge/modules/sbpimv_sbp_4.2.json,sha256=Bj4z7zofZngG9EJ7-q74F-JF41O1FK_mX8RTfYdLP9I,7023
 xbridge/modules/sepa_ipr_pay_4.1.json,sha256=awsJeBUDhMIFs5so6CWUQmlcHSDcGMd8fnLy_r_iMik,27054
 xbridge/modules/sepa_ipr_pay_4.2.json,sha256=JLJvR02LOAJy6SWPRuhV1TT02oXQhsG83FBn176KWsA,27742
-xbridge/modules.py,sha256=8TheJY7oZIy_n-doALa_9AYwwZFu284jaBWt-aol0MA,22292
+xbridge/modules.py,sha256=bTvBXtp3w4Gad2DpEQE7Hb-UfuUQLlRl8gywRstQtpU,22399
 xbridge/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 xbridge/taxonomy_loader.py,sha256=K0lnJVryvkKsaoK3fMis-L2JpmwLO6z3Ruq3yj9FxDY,9317
-eba_xbridge-1.5.0rc3.dist-info/METADATA,sha256=ahBEnyB5K2mskMtLQw7LwqVUnRIPZY8TbzUZ3wd2XeA,2088
-eba_xbridge-1.5.0rc3.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-eba_xbridge-1.5.0rc3.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-eba_xbridge-1.5.0rc3.dist-info/RECORD,,
+eba_xbridge-1.5.0rc4.dist-info/METADATA,sha256=5BAX_xFnRrIxcQiJbNi3y68A_42F8dR-qpL6Z-bBT0U,10430
+eba_xbridge-1.5.0rc4.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+eba_xbridge-1.5.0rc4.dist-info/entry_points.txt,sha256=FATct4icSewM04cegjhybtm7xcQWhaSahL-DTtuFdZw,49
+eba_xbridge-1.5.0rc4.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+eba_xbridge-1.5.0rc4.dist-info/RECORD,,

eba_xbridge-1.5.0rc4.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+xbridge=xbridge.__main__:main
+

xbridge/__init__.py

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

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()

xbridge/converter.py

@@ -77,7 +77,7 @@ class Converter:
         output_path: Union[str, Path],
         headers_as_datapoints: bool = False,
         validate_filing_indicators: bool = True,
-        strict_validation: bool = True,
+        strict_validation: bool = False,
     ) -> Path:
         """Convert the ``XML Instance`` to a CSV file or between CSV formats"""
         if not output_path:
@@ -312,17 +312,6 @@ class Converter:
             [key for key in open_keys if key in datapoint_df.columns and key in instance_df.columns]
         )
 
-        def _strip_prefix(val: Any) -> Any:
-            if isinstance(val, str) and ":" in val:
-                return val.split(":", 1)[1]
-            return val
-
-        for col in merge_cols:
-            if col in datapoint_df.columns:
-                datapoint_df[col] = datapoint_df[col].map(_strip_prefix)
-            if col in instance_df.columns:
-                instance_df[col] = instance_df[col].map(_strip_prefix)
-
         instance_df = instance_df.copy()
         instance_df["_idx"] = instance_df.index
 
@@ -367,18 +356,6 @@ class Converter:
         # Join the dataframes on the datapoint_columns
         merge_cols = list(variable_columns & instance_columns)
 
-        def _strip_prefix(val: Any) -> Any:
-            if isinstance(val, str) and ":" in val:
-                return val.split(":", 1)[1]
-            return val
-
-        # Align merge columns by stripping any namespace prefixes from both sides
-        for col in merge_cols:
-            if col in datapoint_df.columns:
-                datapoint_df[col] = datapoint_df[col].map(_strip_prefix)
-            if col in instance_df.columns:
-                instance_df[col] = instance_df[col].map(_strip_prefix)
-
         table_df = pd.merge(datapoint_df, instance_df, on=merge_cols, how="inner")
 
         if "data_type" in table_df.columns and "decimals" in table_df.columns:

xbridge/instance.py

@@ -728,7 +728,11 @@ class Fact:
     def __dict__(self) -> Dict[str, Any]:  # type: ignore[override]
         metric_clean = ""
         if self.metric:
-            metric_clean = self.metric.split("}")[1] if "}" in self.metric else self.metric
+            # Normalize metric to use consistent eba_* prefix like other dimensions
+            metric_clean = _normalize_namespaced_value(self.metric, self.fact_xml.nsmap) or ""
+            # If still in Clark notation, extract the local name
+            if metric_clean.startswith("{") and "}" in metric_clean:
+                metric_clean = metric_clean.split("}", 1)[1]
 
         return {
             "metric": metric_clean,

xbridge/modules.py

@@ -306,9 +306,9 @@ class Table:
                 variable_info: dict[str, Any] = {}
                 for dim_k, dim_v in variable.dimensions.items():
                     if dim_k not in ("unit", "decimals"):
-                        variable_info[dim_k] = dim_v.split(":")[1]
+                        variable_info[dim_k] = dim_v
                 if "concept" in variable.dimensions:
-                    variable_info["metric"] = variable.dimensions["concept"].split(":")[1]
+                    variable_info["metric"] = variable.dimensions["concept"]
                     del variable_info["concept"]
 
                 if variable.code is None:
@@ -324,9 +324,11 @@ class Table:
                 if "dimensions" in column:
                     for dim_k, dim_v in column["dimensions"].items():
                         if dim_k == "concept":
-                            variable_info["metric"] = dim_v.split(":")[1]
+                            variable_info["metric"] = dim_v
                         elif dim_k not in ("unit", "decimals"):
-                            variable_info[dim_k.split(":")[1]] = dim_v.split(":")[1]
+                            # Keep the full dimension key and value with prefixes
+                            dim_k_clean = dim_k.split(":")[1] if ":" in dim_k else dim_k
+                            variable_info[dim_k_clean] = dim_v
 
                 if "decimals" in column:
                     variable_info["data_type"] = column["decimals"]

eba_xbridge-1.5.0rc3.dist-info/METADATA

@@ -1,62 +0,0 @@
-Metadata-Version: 2.4
-Name: eba-xbridge
-Version: 1.5.0rc3
-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
-
-Overview
-============
-XBridge is a Python library which main function is to convert XBRL-XML files into XBRL-CSV files by using EBA's taxonomy.
-It works with EBA Taxonomy latest published version (4.1). Library must be updated on each new EBA taxonomy version.
-
-Installation
-============
-
-To install the library, run the following command:
-
-.. code:: bash
-
-    pip install eba-xbridge
-
-
-How XBridge works:
-=========================
-
-Firstly, an XBRL-XML file has to be selected to convert it. Then, that XBRL-XML file is input in the following function contained in the ``API`` package:
-
-.. code:: python
-
-  >>> from xbridge.api import convert_instance
-
-  >>> input_path = "data/input"
-
-  >>> output_path = "data/output"
-
-  >>> convert_instance(input_path, output_path)
-
-The sources to do this process are two: The XML-instances and EBA´s taxonomy.
-
-The output is the converted XBRL-CSV file placed in the output_path, as zip format
-