instance

The Instance Document uses the concepts created in the taxonomy to tag the numbers to be reported, giving them meaning and structure. Thus, the instance document embodies the actual business report, for example, the annual financial statement.

There are two different types of instance documents: the classic XBRL instance document (XML) and the iXBRL instance document (HTML). Both types are based on the same elements but are written in different file types.

The core elements of every Instance document are the Facts. A fact is a number (150000) combined with a context (from Jan-Dec 2020 for company xyz), a unit (USD) and tagged with a concept from the taxonomy (us-gaap_Revenue). The Context defines the time frame and the company to which the fact belongs.

Parse functions

This module contains all classes and functions necessary for parsing a Instance file.

This module will also access other Modules i.e TaxonomySchema.py to parse the Instance file as well as the taxonomies and linkbases used by the instance files

instance.parse_xbrl_url(cache)

Parses a instance file with it’s taxonomy. This function will check, if the instance file is already in the cache and load it from there based on the instance_url. For EDGAR submissions: Before calling this method; extract the enclosure and copy the files to the cache. i.e. Use CacheHelper.extract_edgar_enclosure()

Parameters

  • instance_url (str) – url to the instance file (on the internet)

  • cache (HttpCache) – HttpCache instance

Return type

XbrlInstance

Returns

parsed XbrlInstance object containing all facts with additional information

instance.parse_xbrl(cache, instance_url=None)

Parses a instance file with it’s taxonomy

Parameters

  • instance_path (str) – url to the instance file (on the internet)

  • cache (HttpCache) – HttpCache instance

  • instance_url (Optional[str]) – optional url to the instance file. Is sometimes necessary if the xbrl filings have their own extension taxonomy. If i.e. a submission from the sec is parsed, the instance file might reference the taxonomy schema with a relative path (since it is in the same directory as the instance file) schemaRef=”./aapl-20211231.xsd”

Return type

XbrlInstance

Returns

parsed XbrlInstance object containing all facts with additional information

instance.parse_ixbrl_url(cache, encoding=None)

Parses a inline XBRL (iXBRL) instance file.

Parameters

  • cache (HttpCache) – HttpCache instance

  • instance_url (str) – url to the instance file(on the internet)

  • encoding (Optional[str]) – specifies the encoding of the file

Return type

XbrlInstance

Returns

parsed XbrlInstance object containing all facts with additional information

instance.parse_ixbrl(cache, instance_url=None, encoding=None, schema_root=None)

Parses a inline XBRL (iXBRL) instance file.

Parameters

  • instance_path (str) – path to the submission you want to parse

  • cache (HttpCache) – HttpCache instance

  • instance_url (Optional[str]) – url to the instance file(on the internet)

  • encoding – optionally specify a file encoding

  • schema_root – path to the directory where the taxonomy schema is stored (Only works for relative imports)

Return type

XbrlInstance

Returns

parsed XbrlInstance object containing all facts with additional information

Classes

class xbrl.instance.XbrlParser(cache)

XbrlParser to make interaction easier.

__init__(cache)
parse_instance(uri, instance_url=None, encoding=None)

Parses a xbrl instance (either xbrl or ixbrl)

Warning

If the instance document or extension taxonomy have relative imports the parser will also search for those files locally!

Parameters

  • uri (str) – url to the instance file. i.e: https://www.sec.gov/Archives/edgar/data/320193/000032019320000096/aapl-20200926.

  • instance_url (Optional[str]) – this parameter overrides the above described behaviour. If you also provide the url where the instance document was downloaded, the parser can fetch relative imports using this base url

  • encoding (Optional[str]) – specifies the encoding of the file

Return type

XbrlInstance

Returns

class xbrl.instance.XbrlInstance(url, taxonomy, facts, context_map, unit_map)

Class representing a xbrl instance file

__init__(url, taxonomy, facts, context_map, unit_map)
Parameters

  • taxonomy (TaxonomySchema) – taxonomy file that the instance file references (via link:schemaRef)

  • facts (List[AbstractFact]) – array of all facts that the instance contains

json(file_path=None, override_fact_ids=True, **kwargs)

Converts the instance document into json format :type file_path: Optional[str] :param file_path: if a path is given the function will store the json there :type override_fact_ids: bool :param override_fact_ids: :param kwargs: additional arguments for the json parser :rtype: str :return: string (serialized json) or None (if file_path was given)

https://www.xbrl.org/Specification/xbrl-json/REC-2021-10-13/xbrl-json-REC-2021-10-13.html