### Running with uv (No Installation) Source: https://ixbrl-parse.readthedocs.io/en/latest/command-line If you have 'uv' installed, you can run the iXBRL parser without a full installation using the 'uvx' command. ```bash uvx ixbrlparse example_file.html ``` -------------------------------- ### Install ixbrlparse using pip Source: https://ixbrl-parse.readthedocs.io/en/latest Install the ixbrlparse Python module from PyPI using pip. This is the standard method for adding the library to your project. ```bash pip install ixbrlparse ``` -------------------------------- ### Run ixbrlParse with uvx Source: https://ixbrl-parse.readthedocs.io/en/latest Execute the ixbrlparse tool against an iXBRL file without installing it locally using uvx. This command generates a CSV file with extracted account items. ```bash uvx ixbrlparse example_file.html ``` -------------------------------- ### ixbrlContext Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Represents an ixbrl context, which must include either an instant date or a start and end date. It holds information about the context's ID, entity, and segments. ```APIDOC ## ixbrlContext ### Description Class to represent an ixbrl context. The context should either have an instant date or a start and end date. ### Attributes - **id** (string) - The id of the context. - **entity** (dict) - A dictionary of the entity information. - **segments** (list[dict] | None) - A list of dictionaries of the segment information. - **instant** (date | None) - The instant date of the context. - **startdate** (date | None) - The start date of the context. - **enddate** (date | None) - The end date of the context. ### Initialization ```python ixbrlContext( _id: str, entity: dict[str, str | None], segments: list[dict] | None, instant: str | None, startdate: str | None, enddate: str | None, ) ``` ### Methods #### to_json() Converts the ixbrlContext object to a JSON serialisable dictionary. Dates are converted to string format. ``` -------------------------------- ### Configure Plugin Entrypoint in setup.py Source: https://ixbrl-parse.readthedocs.io/en/latest/plugins Define an entry point for your plugin in the `setup.py` file under the `entry_points` dictionary, specifying the plugin name and its module. ```python from setuptools import setup setup( name="ixbrlparse-dateplugin", install_requires="ixbrlparse", entry_points={"ixbrlparse": ["dateplugin = ixbrlparse_dateplugin"]}, py_modules=["ixbrlparse_dateplugin"], ) ``` -------------------------------- ### Displaying Help and Options Source: https://ixbrl-parse.readthedocs.io/en/latest/command-line View the available command-line options for the iXBRL parser by running the help command. This displays options for output file, format, and fields. ```bash python -m ixbrlparse -h ``` -------------------------------- ### Configure Plugin Entrypoint in pyproject.toml Source: https://ixbrl-parse.readthedocs.io/en/latest/plugins Alternatively, configure the plugin entry point in the `pyproject.toml` file under the `[project.entry-points.ixbrlparse]` section. ```toml [project.entry-points.ixbrlparse] dateplugin = "ixbrlparse_dateplugin" ``` -------------------------------- ### Build and Publish Package Source: https://ixbrl-parse.readthedocs.io/en/latest/development Build the package, publish it to PyPI, and create a Git tag. This sequence of commands is used for releasing new versions. ```bash hatch build hatch publish git tag v git push origin v ``` -------------------------------- ### ixbrlNonNumeric.__init__() Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Initializes a new instance of the ixbrlNonNumeric class. It parses the name, sets context, format, and value, and attempts to parse the value based on the provided format. ```APIDOC ## ixbrlNonNumeric.__init__() ### Description Initializes a new instance of the ixbrlNonNumeric class. It parses the name, sets context, format, and value, and attempts to parse the value based on the provided format. ### Method ```python def __init__( self, context: ixbrlContext | str | None = None, name: str | None = None, format_: str | None = None, value: str | None = None, soup_tag: Tag | None = None, ) -> None: # ... implementation details ... ``` ### Parameters #### Parameters - **context** (`ixbrlContext` | `str` | `None`): The context of the non-numeric element. Defaults to `None`. - **name** (`str` | `None`): The name of the non-numeric element. Defaults to `None`. - **format_** (`str` | `None`): The format of the non-numeric element. Defaults to `None`. - **value** (`str` | `None`): The value of the non-numeric element. Defaults to `None`. - **soup_tag** (`Tag` | `None`): The source tag in beautiful soup. Defaults to `None`. ``` -------------------------------- ### __init__ Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Initializes the ixbrl format object with specified format details, including decimal places, scale, and sign. This is used to configure how numeric and other types of iXBRL values are interpreted. ```APIDOC ## __init__ `(format_, decimals=None, scale=0, sign=None)` ### Description Initialise the ixbrl format object. ### Parameters #### Path Parameters - **format_** (str) - Required - The name of the format. - **decimals** (int | str | None) - Optional - The number of decimal places (only used for numeric formats). Default: `None` - **scale** (int | str) - Optional - The scale of the format (only for numeric formats). If more than 0 this value is used as the exponent for a value, so for example with a scale of 4 and a value of 20, the parsed value is 20 * (10 ^ 4) == 200000. Default: `0` - **sign** (str | None) - Optional - The sign of the format (only for numeric formats). The sign given is usually "-" or empty. Default: `None` ``` -------------------------------- ### Initialize ixbrl Format Object Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Use this to create a new ixbrl format object. It accepts the format name, optional decimal places, scale, and sign. ```python def __init__( self, format_: str, decimals: int | str | None = None, scale: int | str = 0, sign: str | None = None, ) -> None: """Initialise the ixbrl format object. Parameters: format_: The name of the format. decimals: The number of decimal places (only used for numeric formats). scale: The scale of the format (only for numeric formats). If more than 0 this value is used as the exponent for a value, so for example with a scale of 4 and a value of 20, the parsed value is 20 * (10 ^ 4) == 200000. sign: The sign of the format (only for numeric formats). The sign given is usually "-" or empty. """ if isinstance(decimals, str): if decimals.lower() == "inf": self.decimals = None else: self.decimals = int(decimals) self.format: str | None = None self.namespace: str | None = None if format_: format_array: list[str] = format_.split(":") if len(format_array) > 1: self.format = ":".join(format_array[1:]) self.namespace = format_array[0] else: self.format = ":".join(format_array) self.namespace = None self.scale = int(scale) self.sign = sign ``` -------------------------------- ### __init__(f, raise_on_error=True) Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Constructor for the IXBRL class. Initializes the parser with a file-like object and an option to control error raising. ```APIDOC ## __init__ __init__(f, raise_on_error=True) ### Description Constructor for the IXBRL class. ### Parameters #### Parameters - **f** (IO) - Required - File-like object to parse. - **raise_on_error** (bool) - Optional - Whether to raise an exception on error. Default: True ``` -------------------------------- ### open(filename, raise_on_error=True) Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Class method to open and parse an iXBRL file from a given filename. ```APIDOC ## open open(filename, raise_on_error=True) ### Description Open an iXBRL file. ### Parameters #### Parameters - **filename** (str | Path) - Required - Path to file to parse. - **raise_on_error** (bool) - Optional - Whether to raise an exception on error. Default: True ``` -------------------------------- ### Basic Command Line Usage Source: https://ixbrl-parse.readthedocs.io/en/latest/command-line Run the iXBRL parser module directly from the command line to extract data from an iXBRL file. This can be done using the 'ixbrlparse' command or by invoking the module with 'python -m ixbrlparse'. ```bash ixbrlparse example_file.html ``` ```bash python -m ixbrlparse example_file.html ``` -------------------------------- ### Initialize IXBRL Parser Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Constructs an IXBRL parser instance from a file-like object. It reads the file content, parses it using BeautifulSoup, and initializes internal parser components like schema, contexts, units, and numeric/non-numeric data. ```python def __init__(self, f: IO, raise_on_error: bool = True) -> None: # noqa: FBT001, FBT002 """Constructor for the IXBRL class. Parameters: f: File-like object to parse. raise_on_error: Whether to raise an exception on error """ self.soup = BeautifulSoup(f.read(), "xml", multi_valued_attributes=None) self.raise_on_error = raise_on_error self._get_parser() self.parser._get_schema() self.parser._get_contexts() self.parser._get_units() self.parser._get_nonnumeric() self.parser._get_numeric() ``` -------------------------------- ### Open IXBRL File from Path Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Class method to open and parse an iXBRL file directly from a filename. It handles file opening and passes the file object to the constructor. ```python @classmethod def open(cls, filename: str | Path, raise_on_error: bool = True): """Open an iXBRL file. Parameters: filename: Path to file to parse. raise_on_error: Whether to raise an exception on error """ with open(filename, "rb") as a: return cls(a, raise_on_error=raise_on_error) ``` -------------------------------- ### Initialize ixbrlContext object Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Initializes an ixbrlContext object, parsing date strings into datetime.date objects. It handles instant, startdate, and enddate fields, and optionally segments. ```python class ixbrlContext: """Class to represent an ixbrl context. The context should either have an instant date or a start and end date. Attributes: id: The id of the context. entity: A dictionary of the entity information. segments: A list of dictionaries of the segment information. instant: The instant date of the context. startdate: The start date of the context. enddate: The end date of the context.""" def __init__( self, _id: str, entity: dict[str, str | None], segments: list[dict] | None, instant: str | None, startdate: str | None, enddate: str | None, ): self.id = _id self.entity = entity self.segments = segments self.instant: datetime.date | None = None self.startdate: datetime.date | None = None self.enddate: datetime.date | None = None date_fields = { "instant": instant, "startdate": startdate, "enddate": enddate, } for field, value in date_fields.items(): if value: datevalue = ( datetime.datetime.strptime(value.strip(), "%Y-%m-%d") .astimezone() .date() ) setattr(self, field, datevalue) ``` -------------------------------- ### Initialize IXBRL Parser Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Constructor for the IXBRL class. Initializes the parser with a file-like object and an option to raise exceptions on errors. ```python class IXBRL: """ Parse an iXBRL file. """ def __init__(self, f: IO, raise_on_error: bool = True) -> None: # noqa: FBT001, FBT002 """Constructor for the IXBRL class. Parameters: f: File-like object to parse. raise_on_error: Whether to raise an exception on error """ self.soup = BeautifulSoup(f.read(), "xml", multi_valued_attributes=None) self.raise_on_error = raise_on_error self._get_parser() self.parser._get_schema() self.parser._get_contexts() self.parser._get_units() self.parser._get_nonnumeric() self.parser._get_numeric() ``` -------------------------------- ### Run All Linting Checks Source: https://ixbrl-parse.readthedocs.io/en/latest/development Execute all available linting checks at once. This is a comprehensive check for code style and formatting. ```bash hatch run lint:all ``` -------------------------------- ### Import IXBRL Class Source: https://ixbrl-parse.readthedocs.io/en/latest/python-module Import the main IXBRL class from the ixbrlparse library to begin parsing. ```python from ixbrlparse import IXBRL ``` -------------------------------- ### Initialize ixbrlNumeric Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Constructor for the ixbrlNumeric class. It parses the name, validates the value, and initializes context, unit, and format. Attempts to parse the numeric value using the specified format. ```python class ixbrlNumeric: """Models a numeric element in an iXBRL document""" def __init__( self, name: str | None = None, unit: str | None = None, value: str | int | float | None = None, text: str | int | float | None = None, context: ixbrlContext | str | None = None, soup_tag: Tag | None = None, **attrs, ) -> None: """Constructor for the ixbrlNumeric class. Parameters: name (str): The name of the numeric element unit (str): The unit of the numeric element value (float): The value of the numeric element text (str): The text of the numeric element context (ixbrlContext): The context of the numeric element soup_tag (Tag): The source tag in beautiful soup """ self.name: str | None = name self.schema: str = "unknown" if isinstance(name, str): name_value = name.split(":", maxsplit=1) if len(name_value) == NAME_SPLIT_EXPECTED: self.schema = name_value[0] self.name = name_value[1] else: self.schema = "unknown" self.name = name_value[0] if not isinstance(value, str | int | float): value = text if not isinstance(value, str | int | float): msg = "Must provide either value or text" raise ValueError(msg) self.text: str | int | float = value self.context: ixbrlContext | str | None = context self.unit: str | None = unit self.value: int | float | None = None self.soup_tag = soup_tag format_ = { "format_": attrs.get("format"), "decimals": attrs.get("decimals", "0"), "scale": attrs.get("scale", 0), "sign": attrs.get("sign", ""), } self.format: ixbrlFormat | None = get_format(format_["format_"])(**format_) try: if isinstance(self.format, ixbrlFormat): parsed_value = self.format.parse_value(self.text) if isinstance(parsed_value, int | float): self.value = parsed_value except ValueError: logging.info(attrs) raise ``` -------------------------------- ### Determine File Type and Initialize Parser Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Internal method to detect if the file is iXBRL or XBRL based on the root element and initialize the appropriate parser. ```python def _get_parser(self) -> None: if self.soup.find("html"): self.filetype = FILETYPE_IXBRL parser = IXBRLParser elif self.soup.find("xbrl"): self.filetype = FILETYPE_XBRL parser = XBRLParser else: msg = "Filetype not recognised" raise IXBRLParseError(msg) self.parser: BaseParser = parser(self.soup, raise_on_error=self.raise_on_error) ``` -------------------------------- ### Initialize ixbrlNonNumeric Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Constructor for the ixbrlNonNumeric class. It parses the name to extract schema and name, and initializes context, format, text, and value. Handles format parsing and value conversion. ```python def __init__(self, context=None, name=None, format_=None, value=None, soup_tag=None): """Parameters: context (ixbrlContext): The context of the non-numeric element name (str): The name of the non-numeric element format_ (str): The format of the non-numeric element value (str): The value of the non-numeric element soup_tag (Tag): The source tag in beautiful soup """ if isinstance(name, str): name_split: list[str] = name.split(":", maxsplit=1) if len(name_split) == NAME_SPLIT_EXPECTED: self.schema = name_split[0] self.name = name_split[1] else: self.schema = "unknown" self.name = name_split[0] self.context = context self.format: ixbrlFormat | None = None self.text: str | None = value self.value: str | int | float | None | date | None = value if isinstance(format_, str) and format_ != "" and self.text is not None: try: self.format = get_format(format_)(format_=format_) self.value = self.format.parse_value(self.text) except NotImplementedError: msg = f"Format {format_} not implemented - value '{value}' not parsed" warnings.warn(msg, stacklevel=2) self.soup_tag = soup_tag ``` -------------------------------- ### Open iXBRL File from Path Source: https://ixbrl-parse.readthedocs.io/en/latest/reference A class method to open and parse an iXBRL file given its file path. It handles file opening in binary mode and passes the file object to the class constructor. ```python @classmethod def open(cls, filename: str | Path, raise_on_error: bool = True): # noqa: FBT001, FBT002 """Open an iXBRL file. Parameters: filename: Path to file to parse. raise_on_error: Whether to raise an exception on error """ with open(filename, "rb") as a: return cls(a, raise_on_error=raise_on_error) ``` -------------------------------- ### Format Code Source: https://ixbrl-parse.readthedocs.io/en/latest/development Automatically format the code using Ruff. This command applies possible auto-formatting changes to adhere to style guidelines. ```bash hatch run lint:fmt ``` -------------------------------- ### Parse File Handle Source: https://ixbrl-parse.readthedocs.io/en/latest/python-module Initialize an IXBRL object by passing an open file handle. Ensure the file is opened with appropriate encoding. ```python with open('sample_ixbrl.html', encoding="utf8") as a: x = IXBRL(a) ``` -------------------------------- ### Initialize ixbrlNonNumeric Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Constructor for the ixbrlNonNumeric class. Parses the name, initializes context, format, and value. Handles potential parsing errors for formatted values. ```python def __init__( self, context: ixbrlContext | str | None = None, name: str | None = None, format_: str | None = None, value: str | None = None, soup_tag: Tag | None = None, ) -> None: """Constructor for the ixbrlNonNumeric class. Parameters: context (ixbrlContext): The context of the non-numeric element name (str): The name of the non-numeric element format_ (str): The format of the non-numeric element value (str): The value of the non-numeric element soup_tag (Tag): The source tag in beautiful soup """ if isinstance(name, str): name_split: list[str] = name.split(":", maxsplit=1) if len(name_split) == NAME_SPLIT_EXPECTED: self.schema = name_split[0] self.name = name_split[1] else: self.schema = "unknown" self.name = name_split[0] self.context = context self.format: ixbrlFormat | None = None self.text: str | None = value self.value: str | int | float | None | date | None = value if isinstance(format_, str) and format_ != "" and self.text is not None: try: self.format = get_format(format_)(format_=format_) self.value = self.format.parse_value(self.text) except NotImplementedError: msg = f"Format {format_} not implemented - value '{value}' not parsed" warnings.warn(msg, stacklevel=2) ``` -------------------------------- ### Initialize ixbrlNumeric Class Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Constructor for the ixbrlNumeric class. It accepts various parameters to define a numeric element, including its name, unit, value, text, context, and source tag. It also handles parsing the value based on associated formatting. ```python def __init__( self, name: str | None = None, unit: str | None = None, value: str | int | float | None = None, text: str | int | float | None = None, context: ixbrlContext | str | None = None, soup_tag: Tag | None = None, **attrs, ) -> None: """Constructor for the ixbrlNumeric class. Parameters: name (str): The name of the numeric element unit (str): The unit of the numeric element value (float): The value of the numeric element text (str): The text of the numeric element context (ixbrlContext): The context of the numeric element soup_tag (Tag): The source tag in beautiful soup """ self.name: str | None = name self.schema: str = "unknown" if isinstance(name, str): name_value = name.split(":", maxsplit=1) if len(name_value) == NAME_SPLIT_EXPECTED: self.schema = name_value[0] self.name = name_value[1] else: self.schema = "unknown" self.name = name_value[0] if not isinstance(value, str | int | float): value = text if not isinstance(value, str | int | float): msg = "Must provide either value or text" raise ValueError(msg) self.text: str | int | float = value self.context: ixbrlContext | str | None = context self.unit: str | None = unit self.value: int | float | None = None self.soup_tag = soup_tag format_ = { "format_": attrs.get("format"), "decimals": attrs.get("decimals", "0"), "scale": attrs.get("scale", 0), "sign": attrs.get("sign", ""), } self.format: ixbrlFormat | None = get_format(format_["format_"])(**format_) try: if isinstance(self.format, ixbrlFormat): parsed_value = self.format.parse_value(self.text) if isinstance(parsed_value, int | float): self.value = parsed_value except ValueError: logging.info(attrs) raise ``` -------------------------------- ### Convert IXBRL Data to Table Format Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Returns a list of dictionaries suitable for pandas DataFrame creation. Allows specifying whether to include 'numeric', 'nonnumeric', or 'all' fields. ```python def to_table(self, fields: str = "numeric") -> list[dict]: """Return a list of dictionaries representing the iXBRL file. This is suitable for passing to pandas.DataFrame.from_records(). Parameters: fields: Which fields to include in the output. Can be "numeric", "nonnumeric" or "all". Returns: A list of dictionaries representing the iXBRL file. The fields included are: - schema (str) - name (str) -- the name of the element - value -- the value of the element. Can be number, str, None, or boolean - unit (str) -- the unit of the element if present - instant (date) -- the instant date of the element context if present - startdate (date) -- the start date of the element context if present - enddate (date) -- the end date of the element context if present - segment:N (str) -- the Nth segment of the element context if present (can be repeated) Examples: >>> import pandas as pd >>> i = IXBRL.open( >>> "tests/fixtures/ixbrl/uk-gaap/2009-12-31/Company-Accounts-Data.xml" >>> ) >>> df = pd.DataFrame.from_records(i.to_table(fields="numeric")) >>> df.head() """ if fields == "nonnumeric": values = self.nonnumeric elif fields == "numeric": values = self.numeric else: values = self.nonnumeric + self.numeric ``` -------------------------------- ### to_table(fields='numeric') Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Returns a list of dictionaries representing the iXBRL file, which can be directly used with pandas.DataFrame.from_records(). Users can specify which fields to include: 'numeric', 'nonnumeric', or 'all'. ```APIDOC ## to_table(fields='numeric') ### Description Returns a list of dictionaries representing the iXBRL file. This method is suitable for passing to pandas.DataFrame.from_records(). ### Method `to_table` ### Parameters #### Parameters - **fields** (str) - Optional - Specifies which fields to include in the output. Accepted values are "numeric", "nonnumeric", or "all". Defaults to "numeric". ### Returns - **list[dict]** - A list of dictionaries, where each dictionary represents an iXBRL element with its associated data. ### Fields in each dictionary: - **schema** (str) - The schema of the element. - **name** (str) - The name of the iXBRL element. - **value** - The value of the element. Can be a number, string, boolean, or None. - **unit** (str) - The unit of the element, if present. - **instant** (date) - The instant date of the element's context, if present. - **startdate** (date) - The start date of the element's context, if present. - **enddate** (date) - The end date of the element's context, if present. - **segment:N** (str) - The Nth segment of the element's context, if present. This field can be repeated for multiple segments. ### Example ```python import pandas as pd from ixbrlparse import IXBRL i = IXBRL.open("path/to/your/file.xml") df = pd.DataFrame.from_records(i.to_table(fields="numeric")) print(df.head()) ``` ``` -------------------------------- ### Hook into ixbrlparse to Add Formats Source: https://ixbrl-parse.readthedocs.io/en/latest/plugins Implement the `ixbrl_add_formats` function, decorated with `@ixbrlparse.hookimpl`, to return a list of new format classes that will be added to the parser. ```python @ixbrlparse.hookimpl def ixbrl_add_formats(): return [ixtParseIsoDate] ``` -------------------------------- ### Run HTML Coverage Report Source: https://ixbrl-parse.readthedocs.io/en/latest/development Generate an HTML report for test coverage. This provides a visual representation of code coverage, highlighting missing areas. ```bash hatch run cov-html ``` -------------------------------- ### Run Pytest Source: https://ixbrl-parse.readthedocs.io/en/latest/development Execute tests using pytest. This command is used to verify the functionality of the module. ```bash hatch run test ``` -------------------------------- ### ixbrlNumeric Constructor Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Initializes an ixbrlNumeric object. This constructor allows setting the name, unit, value, text, context, and source tag of the numeric element, along with any additional attributes. ```APIDOC ## ixbrlNumeric Constructor ### Description Initializes an ixbrlNumeric object. This constructor allows setting the name, unit, value, text, context, and source tag of the numeric element, along with any additional attributes. ### Method __init__ ### Parameters #### Parameters - **name** (str) - Optional - The name of the numeric element - **unit** (str) - Optional - The unit of the numeric element - **value** (float) - Optional - The value of the numeric element - **text** (str) - Optional - The text of the numeric element - **context** (ixbrlContext) - Optional - The context of the numeric element - **soup_tag** (Tag) - Optional - The source tag in beautiful soup - **attrs** (dict) - Optional - Additional attributes for formatting and parsing. ### Request Example ```python ixbrlNumeric(name="exampleName", unit="USD", value=100.50, text="100.50", context=None, soup_tag=None) ``` ### Response #### Success Response An instance of the ixbrlNumeric class is created with the provided parameters. #### Response Example ```python # Example of a created ixbrlNumeric object (representation may vary) ``` ``` -------------------------------- ### Create Custom iXBRL Format Class Source: https://ixbrl-parse.readthedocs.io/en/latest/plugins Define a new format class that subclasses `ixbrlparse.ixbrlFormat`. This class must include a `format_names` attribute and a `parse_value` function to handle the conversion of iXBRL text values to Python values. ```python import ixbrlparse import datetime class ixtParseIsoDate(ixbrlparse.ixbrlFormat): format_names = ("isodateformat") def parse_value(self, value): return datetime.datetime.strptime(value, "%Y-%m-%d").astimezone().date() ``` -------------------------------- ### Parse String Content Source: https://ixbrl-parse.readthedocs.io/en/latest/python-module When iXBRL data is available as a string, wrap it with io.StringIO before passing it to the IXBRL constructor. ```python import io from ixbrlparse import IXBRL content = '''''' x = IXBRL(io.StringIO(content)) ``` -------------------------------- ### Access Contexts Source: https://ixbrl-parse.readthedocs.io/en/latest/python-module Retrieve the contexts used in the iXBRL data. Contexts are stored as a dictionary where keys are context IDs. ```python print(x.contexts) # { # "cfwd_2018_03_31": ixbrlContext( # id="cfwd_2018_03_31", # entity="0123456", # company number # segments=[], # used for hypercubes # instant="2018-03-31", # startdate=None, # used for periods # enddate=None, # used for periods # ), # .... # } ``` -------------------------------- ### Run Coverage Report Source: https://ixbrl-parse.readthedocs.io/en/latest/development Generate a test coverage report. This helps identify areas of the code that are not adequately tested. ```bash hatch run cov ``` -------------------------------- ### Format ixbrlContext for representation Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Provides a string representation of the ixbrlContext object, indicating the date range (instant or start/end dates) and whether segments are present. Useful for debugging. ```python def __repr__(self) -> str: if self.startdate and self.enddate: datestr = f"{self.startdate} to {self.enddate}" else: datestr = str(self.instant) segmentstr = " (with segments)" if self.segments else "" return f"" ``` -------------------------------- ### to_json() Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Converts the parsed iXBRL data into a JSON-serializable dictionary. ```APIDOC ## to_json to_json() ### Description Return a JSON representation of the iXBRL file. ### Returns - **dict** - A dictionary containing the following keys: - schema: The schema used in the iXBRL file. - namespaces: The namespaces used in the iXBRL file. - contexts: The contexts used in the iXBRL file. - units: The units used in the iXBRL file. - nonnumeric: The non-numeric elements in the iXBRL file. - numeric: The numeric elements in the iXBRL file. - errors: The number of errors encountered when parsing the iXBRL file. ``` -------------------------------- ### Run Typing Checks Source: https://ixbrl-parse.readthedocs.io/en/latest/development Perform static typing checks on the codebase. This ensures type consistency and helps catch potential type-related errors. ```bash hatch run lint:typing ``` -------------------------------- ### Lint Code Style Source: https://ixbrl-parse.readthedocs.io/en/latest/development Check the code style using Ruff. This command identifies any style violations that need to be corrected before committing. ```bash hatch run lint:style ``` -------------------------------- ### ixbrlparse.IXBRL Source: https://ixbrl-parse.readthedocs.io/en/latest/reference The main class for parsing iXBRL and XBRL files. It provides methods to access parsed data and convert it into different formats. ```APIDOC ## class ixbrlparse.IXBRL ### Description Parse an iXBRL file. This class handles both iXBRL and XBRL file formats. ### Methods #### `__init__(self, f: IO, raise_on_error: bool = True)` Constructor for the IXBRL class. Parameters: f: File-like object to parse. raise_on_error: Whether to raise an exception on error. #### `open(cls, filename: str | Path, raise_on_error: bool = True)` Open an iXBRL file from a given filename. Parameters: filename: Path to file to parse. raise_on_error: Whether to raise an exception on error. #### `to_json(self) -> dict` Return a JSON representation of the iXBRL file. Returns: A dictionary containing the schema, namespaces, contexts, units, non-numeric elements, numeric elements, and error count. #### `to_table(self, fields: str = "numeric") -> list[dict]` Return a list of dictionaries representing the iXBRL file, suitable for pandas.DataFrame.from_records(). Parameters: fields: Which fields to include in the output. Can be "numeric", "nonnumeric" or "all". Returns: A list of dictionaries representing the iXBRL file. The fields included are: - schema (str) - name (str) -- the name of the element - value -- the value of the element. Can be number, str, None, or boolean - unit (str) -- the unit of the element if present - instant (date) -- the instant date of the element context if present - startdate (date) -- the start date of the element context if present - enddate (date) -- the end date of the element context if present - segment:N (str) -- the Nth segment of the element context if present (can be repeated) Examples: >>> import pandas as pd >>> i = IXBRL.open( >>> "tests/fixtures/ixbrl/uk-gaap/2009-12-31/Company-Accounts-Data.xml" >>> ) >>> df = pd.DataFrame.from_records(i.to_table(fields="numeric")) >>> df.head() ``` -------------------------------- ### Access Units Source: https://ixbrl-parse.readthedocs.io/en/latest/python-module Retrieve the units defined in the iXBRL data. Units are stored as a key:value dictionary. ```python print(x.units) # { # "GBP": "ISO4107:GBP" # "shares": "shares" # } ``` -------------------------------- ### Convert IXBRL Data to JSON Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Returns a JSON (dictionary) representation of the parsed iXBRL file, including schema, namespaces, contexts, units, non-numeric, numeric elements, and error count. ```python def to_json(self) -> dict: """Return a JSON representation of the iXBRL file. Returns: A dictionary containing the following keys: - schema: The schema used in the iXBRL file. - namespaces: The namespaces used in the iXBRL file. - contexts: The contexts used in the iXBRL file. - units: The units used in the iXBRL file. - nonnumeric: The non-numeric elements in the iXBRL file. - numeric: The numeric elements in the iXBRL file. - errors: The number of errors encountered when parsing the iXBRL file. """ return { "schema": self.schema, "namespaces": self.namespaces, "contexts": {c: ct.to_json() for c, ct in self.contexts.items()}, "units": self.units, "nonnumeric": [a.to_json() for a in self.nonnumeric], "numeric": [a.to_json() for a in self.numeric], "errors": len(self.errors), } ``` -------------------------------- ### ixbrlFormat Class Definition Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Defines the ixbrlFormat class for representing and parsing ixbrl formats. It handles initialization with format details, scale, and sign, and includes methods for JSON serialization and value parsing. ```python class ixbrlFormat: # noqa: N801 """Class to represent an ixbrl format. This class should generally be subclassed to provide additional functionality. Attributes: format_names: A tuple of format names that this class should be used for.""" format_names: tuple[str, ...] = () def __init__( self, format_: str, decimals: int | str | None = None, scale: int | str = 0, sign: str | None = None, ) -> None: """Initialise the ixbrl format object. Parameters: format_: The name of the format. decimals: The number of decimal places (only used for numeric formats). scale: The scale of the format (only for numeric formats). If more than 0 this value is used as the exponent for a value, so for example with a scale of 4 and a value of 20, the parsed value is 20 * (10 ^ 4) == 200000. sign: The sign of the format (only for numeric formats). The sign given is usually "-" or empty. """ if isinstance(decimals, str): if decimals.lower() == "inf": self.decimals = None else: self.decimals = int(decimals) self.format: str | None = None self.namespace: str | None = None if format_: format_array: list[str] = format_.split(":") if len(format_array) > 1: self.format = ":".join(format_array[1:]) self.namespace = format_array[0] else: self.format = ":".join(format_array) self.namespace = None self.scale = int(scale) self.sign = sign def to_json(self): """Convert the object to a JSON serialisable dictionary.""" return deepcopy(self.__dict__) def parse_value( self, value: str | int | float ) -> int | float | bool | date | str | None: """Parse a value using the format. Parameters: value: The value to parse. Returns: The parsed value in the appropriate python type. """ if isinstance(value, int | float): return value if isinstance(value, str): if value in ("-", ""): return 0 value_numeric: float = float(value.replace(" ", "").replace(",", "")) if self.sign == "-": value_numeric = value_numeric * -1 if self.scale != 0: value_numeric = value_numeric * (10**self.scale) return value_numeric ``` -------------------------------- ### Convert iXBRL Data to JSON Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Converts the parsed iXBRL data into a JSON-serializable dictionary. The output includes schema, namespaces, contexts, units, non-numeric and numeric elements, and any encountered errors. ```python def to_json(self) -> dict: """Return a JSON representation of the iXBRL file. Returns: A dictionary containing the following keys: - schema: The schema used in the iXBRL file. - namespaces: The namespaces used in the iXBRL file. - contexts: The contexts used in the iXBRL file. - units: The units used in the iXBRL file. - nonnumeric: The non-numeric elements in the iXBRL file. - numeric: The numeric elements in the iXBRL file. - errors: The number of errors encountered when parsing the iXBRL file. """ return { "schema": self.schema, "namespaces": self.namespaces, "contexts": {c: ct.to_json() for c, ct in self.contexts.items()}, "units": self.units, "nonnumeric": [a.to_json() for a in self.nonnumeric], "numeric": [a.to_json() for a in self.numeric], "errors": len(self.errors), } ``` -------------------------------- ### ixbrlNonNumeric.to_json() Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Converts the ixbrlNonNumeric object into a JSON serializable dictionary. It handles date formatting and includes nested JSON representations for format and context if they exist. ```APIDOC ## ixbrlNonNumeric.to_json() ### Description Converts the ixbrlNonNumeric object into a JSON serializable dictionary. It handles date formatting and includes nested JSON representations for format and context if they exist. ### Method ```python def to_json(self) -> dict[str, Any]: # ... implementation details ... ``` ### Parameters This method does not accept any parameters. ### Response - **dict[str, Any]**: A dictionary representation of the ixbrlNonNumeric object, suitable for JSON serialization. ``` -------------------------------- ### Hook into ixbrlparse with Custom Specname Source: https://ixbrl-parse.readthedocs.io/en/latest/plugins Alternatively, use the `specname` argument in the `@ixbrlparse.hookimpl` decorator to specify a different name for the hook function, such as `ixbrl_add_formats`. ```python @ixbrlparse.hookimpl(specname="ixbrl_add_formats") def add_new_ixbrl_formats(): return [ixtParseIsoDate] ``` -------------------------------- ### Extend Existing iXBRL Format Class Source: https://ixbrl-parse.readthedocs.io/en/latest/plugins Override an existing format by subclassing it and extending its attributes, such as `date_format`, to include additional parsing patterns. This allows for parsing dates in new formats like '29-aug-2022'. ```python from ixbrlparse.components.formats import ixtDateDayMonthYear from ixbrlparse import hookimpl, ixbrlFormat class ixtDateDayMonthYearExtended(ixtDateDayMonthYear): date_format = (*ixtDateDayMonthYear.date_format, "%d-%b-%Y", "%d-%b-%y") @hookimpl def ixbrl_add_formats(self) -> list[type[ixbrlFormat]]: return [ixtDateDayMonthYearExtended] ``` -------------------------------- ### Convert ixbrlContext to JSON serializable dictionary Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Converts the ixbrlContext object to a JSON serializable dictionary, formatting date fields as strings. This is useful for data serialization and API responses. ```python def to_json(self) -> dict[str, list[dict[str, Any]]]: """Convert the object to a JSON serialisable dictionary.""" values = deepcopy(self.__dict__) for i in ["startdate", "enddate", "instant"]: if isinstance(values[i], datetime.date): values[i] = str(values[i]) return values ``` -------------------------------- ### to_json() Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Converts an object to a JSON serializable dictionary. This method is available on various objects within the library to facilitate data serialization. ```APIDOC ## to_json() ### Description Converts the object to a JSON serialisable dictionary. ### Method ``` def to_json(self): """Convert the object to a JSON serialisable dictionary.""" return deepcopy(self.__dict__) ``` ### Note This method is part of the base component and is intended for general use across different object types within the library to enable easy data export. ``` -------------------------------- ### Access Parser Attributes via getattr Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Allows accessing attributes of the underlying parser object directly through the IXBRL instance. This simplifies data retrieval. ```python def __getattr__(self, name: str): return getattr(self.parser, name) ``` -------------------------------- ### Convert iXBRL to Pandas DataFrame Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Use `to_table()` to extract numeric fields from an iXBRL file into a list of dictionaries, which can then be converted into a pandas DataFrame. This is useful for data analysis. ```python import pandas as pd from ixbrlparse import IXBRL i = IXBRL.open( "tests/fixtures/ixbrl/uk-gaap/2009-12-31/Company-Accounts-Data.xml" ) df = pd.DataFrame.from_records(i.to_table(fields="numeric")) df.head() ``` -------------------------------- ### Convert ixbrlNumeric to JSON Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Serializes the ixbrlNumeric object to a JSON-compatible dictionary. It includes all attributes except the soup_tag, and serializes nested format and context objects if they exist. ```python def to_json(self) -> dict: values = {k: deepcopy(v) for k, v in self.__dict__.items() if k != "soup_tag"} if isinstance(self.format, ixbrlFormat): values["format"] = self.format.to_json() if isinstance(self.context, ixbrlContext): values["context"] = self.context.to_json() return values ``` -------------------------------- ### Convert ixbrlNonNumeric to JSON Source: https://ixbrl-parse.readthedocs.io/en/latest/reference Serializes an ixbrlNonNumeric object to a JSON-serializable dictionary. Dates are converted to ISO format strings, and nested objects like format and context are also serialized. ```python def to_json(self) -> dict[str, Any]: values = {k: deepcopy(v) for k, v in self.__dict__.items() if k != "soup_tag"} if isinstance(self.value, date): values["value"] = self.value.isoformat() if isinstance(self.format, ixbrlFormat): values["format"] = self.format.to_json() if isinstance(self.context, ixbrlContext): values["context"] = self.context.to_json() return values ```