ixbrl-parse

A lightweight python module for getting useful data out of iXBRL™ and XBRL™ files. The library is at an early stage - feedback and improvements are very welcome.

Full documentation is available at ixbrl-parse.readthedocs.io

For more about the iXBRL™ and XBRL™ standards, see the specification site and XBRL International. This tool is not affiliated with XBRL International.

Changelog

Quickstart

If you use uv you can run the tool against an iXBRL™ file without installing it by running:

uvx ixbrlparse example_file.html

This will output a CSV file containing items from the account.

Requirements

The module requires BeautifulSoup and lxml to parse the documents.

If you're using Python 3.13 you may need to ensure that the libxml2-dev and libxslt-dev packages have been installed.

word2number is used to process the numeric items with the numsenwords format.

How to install

You can install from pypi using pip:

pip install ixbrlparse

How to use

You can run the module directly to extract data from an iXBRL™ file.

ixbrlparse example_file.html
# or
python -m ixbrlparse example_file.html

While primarily designed for iXBRL™ files, the parser should also work for XBRL™ files.

The various options for using this can be found through:

python -m ixbrlparse -h
# optional arguments:
#   -h, --help            show this help message and exit
#   --outfile OUTFILE     Where to output the file
#   --format {csv,json,jsonlines,jsonl}
#                         format of the output
#   --fields {numeric,nonnumeric,all}
#                         Which fields to output

You can also use as a python module (see the documentation for more details)

Development

The module is setup for development using hatch. It should be possible to run tests and linting without needed hatch, however.

Run tests

Tests can be run with pytest:

hatch run test

Without hatch, you'll need to run:

pip install -e .[test]
python -m pytest tests

Test coverage

Run tests then report on coverage

hatch run cov

Without hatch, you'll need to run:

pip install -e .[test]
coverage run -m pytest tests
coverage report

Run tests then run a server showing where coverage is missing

hatch run cov-html

Without hatch, you'll need to run:

pip install -e .[test]
coverage run -m pytest tests
coverage report
coverage html
python -m http.server -d htmlcov

Run typing checks

hatch run lint:typing

Without hatch, you'll need to run:

pip install -e .[lint]
mypy --install-types --non-interactive src/ixbrlparse tests

Linting

Ruff should be run before committing any changes.

To check for any changes needed:

hatch run lint:style

Without hatch, you'll need to run:

pip install -e .[lint]
ruff check .
ruff format --check --diff .

To run any autoformatting possible:

hatch run lint:fmt

Without hatch, you'll need to run:

pip install -e .[lint]
ruff format .
ruff check --fix .

Run all checks at once

hatch run lint:all

Without hatch, you'll need to run:

pip install -e .[lint]
ruff check .
ruff format --check --diff .
mypy --install-types --non-interactive src/ixbrlparse tests

Publish to pypi

hatch build
hatch publish
git tag v<VERSION_NUMBER>
git push origin v<VERSION_NUMBER>

Acknowledgements

Developed by David Kane of Kane Data Ltd

Originally developed for a project with Power to Change looking at how to extract data from financial documents of community businesses.

Thanks to the following users for their contributions:

• @avyfain
• @wcollinscw
• @ajmarks
• @adobrinevski
• @JWFB
• @vin0110
• @daizutabi

XBRL™ and iXBRL™ are trademarks of XBRL International, Inc. All rights reserved.

The XBRL™ standards are open and freely licensed by way of the XBRL International License Agreement. Our use of these trademarks is permitted by XBRL International in accordance with the XBRL International Trademark Policy.

AI Policy and provenance

This project does not contain any code independently generated by LLM-based agents. Limited in-editor autocomplete was used when authoring the code. No LLM generated text is used in documentation.