Python API (Beta)

Warning

The Arelle Python Beta API (located in arelle.api module) is an in-progress API module. A roadmap for this API is in development.

Users of this API should expect changes in future releases.

Session

The Arelle Python API provides Session to run Arelle and access output. You can import it with:

from arelle.api.Session import Session
from arelle.logging.handlers.StructuredMessageLogHandler import StructuredMessageLogHandler

From there you can configure the session, run Arelle, and retrieve the generated models and logs (see examples below).

Examples

Creating an iXBRL Viewer

with open(samples_zip_path, 'rb') as stream:
    options = RuntimeOptions(
        entrypointFile=str(target_path),
        internetConnectivity='offline' if arelle_offline else 'online',
        keepOpen=True,
        logFormat="[%(messageCode)s] %(message)s - %(file)s",
        logPropagate=False,
        pluginOptions={
            'saveViewerDest': str(viewer_path),
            'viewer_feature_review': True,
        },
        plugins='ixbrl-viewer',
    )
    # Plugin default options haven't been applied yet.
    assert not hasattr(options, 'viewerURL')
    with Session() as session:
        session.run(
            options,
            sourceZipStream=stream,
            logHandler=log_handler,
            logFilters=[log_filter],
        )
        # Plugin default options were applied.
        assert hasattr(options, "viewerURL")
        assert options.viewerURL.endswith("ixbrlviewer.js")
        log_xml = session.get_logs('xml')

Querying a Model

options = RuntimeOptions(
    entrypointFile=str(report_zip_path),
    disclosureSystemName='esef',
    internetConnectivity='offline',
    keepOpen=True,
    logFile=str(arelle_log_file),
    logFormat="[%(messageCode)s] %(message)s - %(file)s",
    packages=package_paths,
    plugins='validate/ESEF',
    validate=True,
)
target_qname = qname('https://xbrl.ifrs.org/taxonomy/2022-03-24/ifrs-full', 'Equity')
with Session() as session:
    session.run(options)
    model_xbrls = session.get_models()
    for model_xbrl in model_xbrls:
        equity_facts: set[ModelFact] = model_xbrl.factsByQname.get(target_qname, set())
        for equity_fact in equity_facts:
            print(f'Found Equity fact with value: {equity_fact.xValue}')
    log_xml = session.get_logs('xml')

Using a Validation Plugin

options = RuntimeOptions(
    entrypointFile=str(report_zip_path),
    disclosureSystemName='esef',
    internetConnectivity='offline',
    logFile=str(arelle_log_file),
    logFormat="[%(messageCode)s] %(message)s - %(file)s",
    packages=package_paths,
    plugins='validate/ESEF',
    validate=True,
)
with Session() as session:
    session.run(options)
    log_xml = session.get_logs('xml')