Filing¶

class xbrl_filings_api.Filing¶

Bases: APIResource

XBRL filing in the database based on a report package file.

A filing object has data attributes originating directly from the API database as well as some derived attributes (e.g. language and reporting_date).

All datetime attributes whose name ends "_time" have an additional attribute ending "_time_str" for the original string received from the API.

Every data attribute has a similarly named upper-case class constant which states the dot access-based location of the value origin in the JSON object fragment of the original API response. E.g. the accessor string for attribute filing_index can be read from attribute FILING_INDEX.

Methods

`download`(files[, to_dir, stem_pattern, ...])	Download file(s) according to parameter `files`.
`download_aiter`(files[, to_dir, ...])	Download file(s) and yield `DownloadResult` object(s).
`get_data_attributes`([flags, filings])	Return data attributes for an `APIResource`.
`open`([new, autoraise])	Open the filing on web browser.
`__hash__`()	Return hash of `('APIResource', cls.TYPE, self.api_id)`.
`__repr__`()	Return repr of `api_id` and other properties.
`__str__`()	Return "[entity.name/filing_index] [reporting_date] [language]".

Attributes

`country`	The country where the filing was reported.
`filing_index`	Database identifier for the filing.
`language`	Derived two-letter lower-case language identifier defining the language of the filing.
`last_end_date`	The end date of the last period in the marked-up report contents.
`reporting_date`	Derived end date of the reporting period.
`error_count`	The count of validation errors listed in `validation_messages`.
`inconsistency_count`	The count of validation inconsistencies listed in `validation_messages`.
`warning_count`	The count of validation warnings listed in `validation_messages`.
`added_time`	Timezone-aware datetime when the filing was added to the database.
`added_time_str`	Original timestamp when the filing was added to the database.
`processed_time`	Timezone-aware datetime when the filing was processed for the database.
`processed_time_str`	Original timestamp when the filing was processed for the database.
`entity_api_id`	`api_id` of `entity` object.
`entity`	The entity object of this filing.
`validation_messages`	The set of validation message objects of this filing.
`json_url`	Download URL for a derived xBRL-JSON document.
`package_url`	Download URL for the report package file.
`viewer_url`	URL to a website with an inline XBRL viewer for this report.
`xhtml_url`	Download URL for the inline XBRL report.
`json_download_path`	Local path where `json_url` was downloaded.
`package_download_path`	Local path where `package_url` was downloaded.
`xhtml_download_path`	Local path where `xhtml_url` was downloaded.
`package_sha256`	The SHA-256 checksum of the report package file.
`api_id`	JSON-API resource `id` of `APIResource`.
`query_time`	Time when the query function was called for an `APIObject`.
`request_url`	HTTP request URL for an `APIObject`.

TYPE: str = 'filing'¶: JSON-API resource type of APIResource subclass.

country: str | None¶

The country where the filing was reported.

In case of ESEF this is the country where the filer has issued securities on EU regulated markets. The securities are usually shares but could be other securities as well such as bonds.

filing_index: str | None¶

Database identifier for the filing.

The index is structured as:

Company identifier such as LEI code
Reporting date
Filing system
Country
Entry number (0-based)

For a correctly submitted filing, the entry number separates the different language versions from each other. Sometimes the filer also issues the same report more than once to correct the mistakes left in the first published version. The greatest entry number is the latest published filing.

The parts are separated by a hyphen. Please note that the ISO-style reporting date is also delimited by hyphens.

The original field name in the API is fxo_id.

last_end_date: date | None¶

The end date of the last period in the marked-up report contents.

This is not always the end date of the primary reporting period of the report. The derived field reporting_date is more reliable for this use case.

The original field name in the API is period_end.

error_count: str | None¶: The count of validation errors listed in validation_messages.

inconsistency_count: str | None¶: The count of validation inconsistencies listed in validation_messages.

warning_count: str | None¶: The count of validation warnings listed in validation_messages.

added_time: datetime | None¶

Timezone-aware datetime when the filing was added to the database.

Has an arbitrary delay after the issuer actually filed the report at the OAM.

The original field name in the API is date_added.

added_time_str: str | None¶

Original timestamp when the filing was added to the database.

Has an arbitrary delay after the issuer actually filed the report at the OAM.

The original field name in the API is date_added.

processed_time: datetime | None¶

Timezone-aware datetime when the filing was processed for the database.

The original field name in the API is processed.

processed_time_str: str | None¶

Original timestamp when the filing was processed for the database.

The original field name in the API is processed.

entity_api_id: str | None¶: api_id of entity object.

json_url: str | None¶

Download URL for a derived xBRL-JSON document.

The document is programmatically reserialized version of the Inline XBRL report. The conversion was carried by Arelle XBRL processor. The format of the JSON follows the Open Information Model which includes for example declaration of XML-like namespaces inside the JSON file.

package_url: str | None¶

Download URL for the report package file.

In the case of ESEF filings, this is the official report file published to the index of the OAM in the country where the entity has issued securities.

The report package is a ZIP archive which follows a predefined format. It consists of an inline XBRL report (iXBRL) and the extension taxonomy. The graphical iXBRL report can be found from ‘reports’ directory inside the root folder and due to its visual elements (notably embedded image files) it is typically the largest file in the ZIP archive.

viewer_url: str | None¶

URL to a website with an inline XBRL viewer for this report.

The website features the original XHTML report with ability to examine the marked up Inline XBRL facts one at a time. The underlying software is called The Open Source Inline XBRL Viewer and it is developed by Workiva.

This file cannot be downloaded.

xhtml_url: str | None¶

Download URL for the inline XBRL report.

Contains the actual data of the filing and its visual, PDF-like representation. In the case of ESEF filings, the document has been extracted from the ‘reports’ folder of the package_url file. The report is an XHTML document with embedded inline XBRL markup.

As this file is not compressed, it might have larger download size than the actual report package file.

The original field name in the API is report_url despite the fact that this file is not the official report for many filings such as ESEF.

json_download_path: str | None¶: Local path where json_url was downloaded.

package_download_path: str | None¶: Local path where package_url was downloaded.

xhtml_download_path: str | None¶: Local path where xhtml_url was downloaded.

package_sha256: str | None¶

The SHA-256 checksum of the report package file.

Used for checking that the download of package_url was successful and the report is genuine.

The original field name in the API is sha256.

entity: Entity | None¶

The entity object of this filing.

The object is available when flag GET_ENTITY is set in query function parameter flags.

validation_messages: set[ValidationMessage] | None¶

The set of validation message objects of this filing.

The object is available when flag GET_VALIDATION_MESSAGES is set in query function parameter flags. If filing has no validation messages, the value is an empty set.

When flag is not set, this attribute is None.

language: str | None¶

Derived two-letter lower-case language identifier defining the language of the filing.

This code is based primarily on the file name in attribute package_url and secondarily on xhtml_url.

Three-letter language identifiers are transformed into two-letter identifiers for official EU languages.

reporting_date: date | None¶

Derived end date of the reporting period.

This date is based on file name in the attribute package_url and if it cannot be derived, value in the attribute last_end_date will be used.

As last_end_date regards only the absolute last recorded fact in the report (even if there is only one fact reported for this date), it is unreliable regarding filing mistakes and and future-bound facts.

Extracts a valid YYYY-MM-DD date in package_url URL stem (filename). If multiple dates exist in stem, selects the last one.

download(files, to_dir=None, *, stem_pattern=None, check_corruption=True, max_concurrent=None)¶

Download file(s) according to parameter files.

The files parameter accepts three formats:

filing.download('json', to_dir='dir/path')
filing.download(['json', 'package'], to_dir='dir/path')
filing.download(
    {'json': DownloadItem(filename='save.json')},
    to_dir='dir/path')

The filesystem path of the downloaded file will be saved in the Filing object attributes <file>_download_path such as json_download_path for the downloaded JSON file.

If package file is requested to be downloaded and parameter check_corruption is True, the downloaded package files will be checked through the package_sha256 attribute. If this hash attribute does not match the one calculated from the downloaded file, an exception CorruptDownloadError is raised after all downloads have finished. The downloaded files will not be deleted but the filename will be appended with ending ".corrupt". However, attribute package_download_path will not store this corrupt paths.

The directories in the path of parameter to_dir will be created if they do not exist. By default, filename is derived from download URL. If the file already exists, it will be overwritten.

If download is interrupted, the files will be left with ending ".unfinished".

If no name could be derived from the url attribute, the file will be named file0001, file0002, etc. In this case a new file is always created.

Parameter stem_pattern requires a placeholder "/name/". For example pattern /name/_second_try will change original filename 743700XJC24THUPK0S03-2022-12-31-fi.xhtml into 743700XJC24THUPK0S03-2022-12-31-fi_second_try.xhtml. Not recommended for packages as their names should not be changed.

HTTP request timeout is defined in options.timeout_sec.

Parameters:

files (str or iterable of str or mapping of {str: DownloadItem}) – All of the str values in annotation are FileStringType literals. DownloadItem attributes override method arguments for the file.
to_dir (path-like, optional) – Directory to save the files. Defaults to working directory.
stem_pattern (str, optional) – Pattern to add to the filename stems. Placeholder "/name/" is always required.
check_corruption (bool, default True) – Raise CorruptDownloadError for a corrupt 'package' file.
max_concurrent (int or None, default None) – Maximum number of simultaneous downloads allowed. Value None means unlimited.

Raises:

CorruptDownloadError – When attribute Filing.package_sha256 does not match the calculated hash of 'package' file and check_corruption is True.
requests.HTTPError – When HTTP status error occurs.
requests.ConnectionError – When connection fails.

Return type:

None