Openesef
Open-ESEF is a Python-based open-source project for handling XBRL filings that follow ESEF, the European Single Electronic Format.
Install / Use
/learn @reeyarn/OpenesefREADME
Open-ESEF is a Python-based, open-source project designed to handle XBRL (eXtensible Business Reporting Language) filings, specifically those adhering to the ESEF (European Single Electronic Format) standard.
ESEF is the mandated digital reporting format for annual financial reports of listed companies in the European Union, established by the European Securities and Markets Authority (ESMA). Open-ESEF provides a robust toolkit for parsing, validating, and analyzing these ESEF XBRL filings.
Funding Acknowledgment (DFG): Funded by the Deutsche Forschungsgemeinschaft (DFG, German Research Foundation) – Collaborative Research Center (SFB/TRR) Project-ID 403041268 – TRR 266 Accounting for Transparency.
Open-ESEF is under active development. Stay tuned for updates and new features as the project progresses!
Getting Started
Install the stable release using pip
To install the latest stable version:
pip install openesef
Alternatively: Installing the latest version with git
-
Clone the Repository:
git clone https://github.com/reeyarn/openesef.git cd openesef -
Install Dependencies and Build Package:
# Install Cython first pip install cython # Install the package in development mode with Cython compilation pip install -e .
Note: The package will automatically compile the Cython extensions during installation. If you modify any .pyx files, you'll need to reinstall the package using pip install -e . again.
- Verify Installation:
python -c "from openesef import base, taxonomy, instance; import openesef.engines.tax_pres as oetp; print('Open-ESEF installed successfully!')"
Usage Examples
Example 1: Loading SEC Filings (US-GAAP iXBRL)
Explore the Example and output with Notebooks: examples/apple_2020.ipynb
-
Load XBRL filing using ticker and year
from openesef.edgar.loader import load_xbrl_filing from openesef.engines.tax_pres import TaxonomyPresentation # Load XBRL filing using ticker and year xid, tax = load_xbrl_filing(ticker="AAPL", year=2020) # OR Load using filing URL: # xid, tax = load_xbrl_filing(filing_url="/Archives/edgar/data/320193/0000320193-20-000096.txt") -
Create presentation object to analyze statements and concepts
t_pres = TaxonomyPresentation(tax) # Print statement names print("\nFinancial Statements:") for statement in t_pres.statement_dimensions.keys(): print(f"- {statement}") -
Get concepts from Statement of Operations
print("\nConcepts in Statement of Operations:") statement_concepts = t_pres.statement_concepts.get('CONSOLIDATEDSTATEMENTSOFOPERATIONS', []) concepts_statement_of_operations = [] for concept in statement_concepts: concepts_statement_of_operations.append(concept['concept_qname']) print(f"Statement: {concept['statement_name']}") print(f"Concept: {concept['concept_qname']}") print(f"Label: {concept['label']}") -
Print fact values for Statement of Operations concepts
print("\nFact Values:") for key, fact in xid.xbrl.facts.items(): concept_qname = str(fact.qname) context = xid.xbrl.contexts[fact.context_ref] if concept_qname in concepts_statement_of_operations: print(f"{concept_qname:<90} Value: {fact.value:<15} ")
Example 2: Loading ESEF Filing (IFRS - Volkswagen 2020)
In this forked repository, I began by adapting the code from the fractalexperience/xbrl/ package to facilitate its compatibility with ESEF.
The issue in that repository was that, unlike US-SEC-EDGAR, ESEF files adhere to a folder structure. Consequently, the schema references in ESEF files are relative to the instance file rather than the taxonomy folder, and fractalexperience/xbrl/ package did not handle this out of the box. Using SAP SE 2022 ESEF filing as an example, the ESEF filing root folder contains the following folders and files:
📦 sap-2022-12-31-DE
├── 📦 META-INF
│ ├── 📄 catalog.xml
│ └── 📄 taxonomyPackage.xml
├── 📦 reports
│ └── 📄 sap-2022-12-31-DE.xhtml
└── 📦 www.sap.com
├── 📄 sap-2022-12-31.xsd
├── 📄 sap-2022-12-31_cal.xml
├── 📄 sap-2022-12-31_def.xml
├── 📄 sap-2022-12-31_lab-de.xml
├── 📄 sap-2022-12-31_lab-en.xml
└── 📄 sap-2022-12-31_pre.xml
I have tried to modify the code to handle ESEF by adding the esef_filing_root parameter and passing it around.
Explore the example with code: examples/try_vw2020.py
Attribution & Legal Notices
ESEF Standard Acknowledgment
This project supports the European Single Electronic Format (ESEF), established by the European Securities and Markets Authority (ESMA) as the mandated digital reporting standard for annual financial reports of listed companies in the European Union. The ESEF specifications and guidelines are sourced from ESMA’s official publications and are adhered to in this implementation. For more information, visit esma.europa.eu.
IFRS Taxonomy & ESEF Standards
This project supports the processing of filings based on the International Financial Reporting Standards (IFRS) and the European Single Electronic Format (ESEF).
IFRS Taxonomy The IFRS Taxonomy is developed and maintained by the IFRS Foundation. The taxonomy files included or referenced in this project are sourced from the IFRS Foundation’s official repository.
- Copyright: The IFRS Taxonomy is Copyright © IFRS Foundation. All rights reserved.
- Disclaimer: This project is an open-source tool and is not affiliated with, endorsed by, or commercially licensed by the IFRS Foundation. The files are used solely to facilitate the technical validation and creation of XBRL/iXBRL documents. For official standards, please visit ifrs.org.
ESEF Guidelines The ESEF reporting standard is established by the European Securities and Markets Authority (ESMA) for listed companies in the European Union.
- Source: ESEF specifications are sourced from ESMA’s official publications.
- Attribution: Adherence to ESEF guidelines in this project is based on public technical standards available at esma.europa.eu.
US GAAP Taxonomy Acknowledgment & License
This project includes copies of the US GAAP Financial Reporting Taxonomy (e.g., us-gaap-YYYY-MM-DD.xsd), sourced from official locations (e.g., fasb.org and xbrl.us). These files are Copyright © Financial Accounting Foundation (FAF) and, for certain prior versions, XBRL US, Inc.
The taxonomy files are redistributed within this project as a "Permitted Work" pursuant to the FAF's Copyright Notice and policies. They are provided for public use to assist in the implementation and processing of XBRL data.
Compliance Conditions:
- Non-Modification: All original copyright notices, XML comments, disclaimers, and license statements embedded in the taxonomy files have been preserved unchanged.
- No Ownership Claim: This project does not claim ownership of the taxonomy; rights remain exclusively with the FAF and XBRL US.
- Authorized Use: Use of these files is subject to the Notice of Authorized Uses maintained by the FAF.
For full license terms, please see the Official Terms and Conditions.
General Disclaimer & Takedown Notice
The use of the standards, taxonomies, and schemas listed above is intended to support educational and research purposes in alignment with the open-source goals of this project.
Rights Infringement Contact: If any use herein is found to infringe upon the rights of the FASB, XBRL US, ESMA, or the IFRS Foundation, please contact the author immediately:
Contact: reeyarn+github.openesef@gmail.com
Upon receipt of a valid notice, the author will promptly remove or adjust the offending content to address any concerns.
Based on Open Source Projects
Open-ESEF builds upon and extends the excellent work of these open-source projects:
- XBRL-Model (
fractalexperience/xbrl/): Provides the foundation for XBRL parsing, taxonomy handling, and data modeling. Open-ESEF adapts and extends this library to handle ESEF-specific requirements. - SEC EDGAR Financial Reports (
farhadab/sec-edgar-financials): Provides code for interacting with the SEC EDGAR system (modules are currently under review and being streamlined). - pyXBRL (
ifanchu/pyXBRL): (used the code for the DEI part, aka the document and entity information, such as the current fiscal period, fiscal year end, etc.). - ESEF.jl (Julia): (used their hint to use the filings.xbrl.org API to get the ESEF filings).
