dpmxbrl¶

Read a report, detecting xBRL-CSV or XBRL-XML from the input.

The format is detected as by :func:detect_format; the input is then read by :func:read_xbrl_csv or :func:read_xbrl_xml.

Parameters:

• source (str | PathLike[str] | bytes) –

  Bytes, a file path, an xBRL-CSV package directory, or the path of a package's report.json.

• name (str | None, default: None ) –

  Label used in messages and fact locations, such as the file name of uploaded bytes; the EBA file-naming rule checks it.

• metadata_resolver (MetadataResolver | None, default: None ) –

  xBRL-CSV extends URL resolver; unused for XML.

• taxonomy_packages (str | PathLike[str] | Sequence[str | PathLike[str]], default: () ) –

  Local taxonomy package ZIPs, one path or a sequence: they resolve xBRL-CSV metadata and add the filing rules that need the taxonomy.

• limits (Limits, default: Limits() ) –

  Resource limits for untrusted input.

Returns:

• Report ( Report ) –

  The parsed report.

Raises:

• ReportError –

  If the input cannot be read safely.

Examples:

>>> from dpmxbrl import read_report
>>> report = read_report("instance.xbrl")
>>> report.format, report.reference_date.isoformat(), len(report.facts)
('xbrl-xml', '2025-12-31', 3)
>>> [(finding.rule, finding.code) for finding in report.filing]
[('File naming', 'invalidFileName')]

Read an xBRL-CSV report package from a ZIP or a directory.

Parameters:

• source (str | PathLike[str] | bytes) –

  ZIP bytes, a ZIP path, a package directory, or report.json.

• name (str | None, default: None ) –

  Label used in messages instead of the source path.

• metadata_resolver (MetadataResolver | None, default: None ) –

  Returns the bytes for an absolute extends URL, or None when unknown. It is consulted before taxonomy packages.

• taxonomy_packages (str | PathLike[str] | Sequence[str | PathLike[str]], default: () ) –

  Local taxonomy package ZIPs, one path or a sequence, whose META-INF/catalog.xml rewrites resolve extends URLs.

• limits (Limits, default: Limits() ) –

  Resource limits for untrusted input.

Returns:

• Report ( Report ) –

  Report with format == "xbrl-csv".

Raises:

• ReportError –

  If the package is invalid, unsafe or over a limit.

Examples:

>>> from dpmxbrl import read_xbrl_csv
>>> report = read_xbrl_csv("described.zip", taxonomy_packages=["taxonomy.zip"])
>>> fact = report.facts[0]
>>> fact.datapoint, fact.concept, fact.unit, fact.decimals
('dp84817', 'eba_met:mi53', 'iso4217:EUR', -3)

Read one XBRL 2.1 XML instance.

Parameters:

• source (str | PathLike[str] | bytes) –

  Instance bytes or a path to the instance document.

• name (str | None, default: None ) –

  Label used in messages and fact locations.

• taxonomy_packages (str | PathLike[str] | Sequence[str | PathLike[str]], default: () ) –

  Local taxonomy package ZIPs, one path or a sequence; with them the filing rules that need the taxonomy are checked too.

• limits (Limits, default: Limits() ) –

  Resource limits for untrusted input.

Returns:

• Report ( Report ) –

  Report with format == "xbrl-xml".

Raises:

• ReportError –

  If the instance is malformed, unsafe or over a limit.

Examples:

>>> from dpmxbrl import read_xbrl_xml
>>> fact = read_xbrl_xml("instance.xbrl").facts[2]
>>> fact.concept, dict(fact.dimensions), dict(fact.typed_dimensions)
('eba_met:qNCO', {'eba_dim:qNCO': 'eba_qCO:qx2000'}, {'eba_dim:qINC': 'CP0001'})

Detect whether input is an xBRL-CSV package or an XBRL-XML instance.

ZIP archives, directories and .json metadata paths are xBRL-CSV; anything else is read as XBRL-XML. A ZIP is recognized by its content, whatever its suffix.

Parameters:

• source (str | PathLike[str] | bytes) –

  Bytes, a file path, or an xBRL-CSV package directory.

• name (str | None, default: None ) –

  Label used in messages instead of the path, such as the file name of uploaded bytes.

Returns:

• ReportFormat ( ReportFormat ) –

  "xbrl-csv" or "xbrl-xml".

Raises:

• ReportError –

  If a path does not exist or cannot be read, or if a .zip file or one starting like a ZIP archive cannot be read as one (it is incomplete or damaged; reading it as XML would only report malformed XML).

Examples:

>>> from dpmxbrl import detect_format
>>> detect_format("report.zip"), detect_format("instance.xbrl")
('xbrl-csv', 'xbrl-xml')

Write an EBA xBRL-CSV report package ZIP.

The package holds META-INF/reportPackage.json, reports/report.json, parameters.csv, FilingIndicators.csv and one datapoint,factValue,<keys> table per template. Output is deterministic: templates are sorted, facts keep their order, and ZIP timestamps are fixed.

With taxonomy_packages, the module's JSON entry point (the entry point with .json for .xsd) gives the tables: each fact with a concept, such as one read from XML, goes in every table row whose data point has its concept and dimensions, with the module's table files, columns and prefixes. report.json extends the JSON entry point, and baseCurrency and the decimals* parameters come from the facts. Facts without a concept keep their template and datapoint.

Parameters:

• report (Report) –

  Report to write; without taxonomy packages every fact needs a template and datapoint.

• target (str | Path | IO[bytes]) –

  Destination path or writable binary stream.

• root (str | None, default: None ) –

  Top-level folder name; defaults to the target's file name without .zip, as the EBA filing rules ask, or to default_package_root for a stream.

• taxonomy_packages (str | PathLike[str] | Sequence[str | PathLike[str]], default: () ) –

  Local taxonomy package ZIPs, one path or a sequence, holding the module's xBRL-CSV metadata, used to place facts by concept.

• strict (bool, default: True ) –

  With taxonomy packages, whether a fact that cannot be placed exactly raises ReportError; when False it is left out and returned.

• limits (Limits, default: Limits() ) –

  Resource limits for reading the taxonomy packages.

Returns:

• SkippedFacts ( SkippedFacts ) –

  The facts left out, each a :class:SkippedFact with

• SkippedFacts –

  the reason and its code; always empty when strict is true.

Warns:

• DecimalsWarning –

  If a decimals* parameter is lower than the decimals of some of its facts, naming them.

Raises:

• ReportError –

  If a fact lacks a template or datapoint (without taxonomy packages) or cannot be placed (with them, in strict mode), the module metadata is missing, or a template or root name is not a safe file name.

Examples:

>>> from dpmxbrl import read_report, write_xbrl_csv
>>> report = read_report("report.zip")
>>> write_xbrl_csv(report, "copy.zip")  # root folder "copy"
()
>>> read_report("copy.zip").facts == report.facts
True

Write an XBRL 2.1 XML instance.

Contexts are deduplicated per dimension combination (ids c1, c2 in first-use order) and use the report entity and an instant at the reference date; dimensions are written in the scenario. Facts with a unit are numeric and get decimals (INF when unset) unless nil; a fact with decimals but no unit, as xBRL-CSV metadata gives pure facts, gets xbrli:pure. A fact repeated with the same concept, dimensions, unit, value and decimals, as in several xBRL-CSV tables, is written once. The schemaRef names the module's XSD entry point: a JSON entry point, as xBRL-CSV reports extend, is mapped to the XSD that the taxonomy packages list for it, or else named by the EBA's convention.

Parameters:

• report (Report) –

  Report to write; every fact needs a concept.

• target (str | Path | IO[bytes]) –

  Destination path or writable binary stream.

• typed_domains (Mapping[str, str] | None, default: None ) –

  Typed dimension qname to the qname of its typed domain element, with a prefix the report declares or in Clark notation ({namespace}local, declared under a new prefix if needed); required for each typed dimension used by a fact unless the taxonomy packages give it.

• taxonomy_packages (str | PathLike[str] | Sequence[str | PathLike[str]], default: () ) –

  Local taxonomy package ZIPs, one path or a sequence, whose dimension schemas give the typed domain (xbrldt:typedDomainRef) of each typed dimension not in typed_domains, declared with the prefix its schema uses.

• limits (Limits, default: Limits() ) –

  Resource limits for reading the taxonomy packages.

Raises:

• ReportError –

  If a fact lacks a concept, the entity or reference date is missing, a prefix is undeclared or invalid, a qname has an invalid local name, a typed domain is unknown, or a value holds a character XML cannot represent.

Warns:

• EntryPointWarning –

  If the XSD entry point for a JSON one comes from the EBA's naming convention rather than the taxonomy packages.

Examples:

>>> from dpmxbrl import read_report, write_xbrl_xml
>>> report = read_report("described.zip", taxonomy_packages=["taxonomy.zip"])
>>> write_xbrl_xml(report, "described.xbrl", taxonomy_packages=["taxonomy.zip"])
>>> instance = read_report("described.xbrl")
>>> len(instance.facts), instance.entry_point.rsplit("/", 1)[1]
(6, 'corep_of.xsd')

Return the default top-level folder name of a written report package.

Parameters:

• report (Report) –

  Report whose entity and reference date name the folder.

Returns:

• str ( str ) –

  <entity id>_<reference date> made path-safe, or report.

Examples:

>>> from dpmxbrl import default_package_root, read_report
>>> default_package_root(read_report("report.zip"))
'SYNTHETICDPMXL000002.CON_2025-12-31'

Return the local part of a prefixed or Clark-notation qname.

Parameters:

• qname (str) –

  A qname such as eba_met:mi53 or {namespace}mi53.

Returns:

• str ( str ) –

  Text after the last } or the first :; a name without

• str –

  either is returned as is.

Examples:

>>> from dpmxbrl import local_name
>>> local_name("eba_met:mi53"), local_name("{http://example.com/met}mi53")
('mi53', 'mi53')

Return the filing indicator code of an xBRL-CSV table template.

Single-letter parts are dropped: c_07.00.a is filed as c_07.00, f_18.00.a.dp as f_18.00.dp. Filing indicators compare case-insensitively.

Parameters:

• template (str) –

  Table template id, such as a table file's stem.

Returns:

• str ( str ) –

  The template id without single-letter parts.

Examples:

>>> from dpmxbrl import filing_indicator_code
>>> filing_indicator_code("c_07.00.a"), filing_indicator_code("F_18.00.a.dp")
('c_07.00', 'F_18.00.dp')