ixbrlParse

https://ixbrl-parse.readthedocs.io/
Admin
ixbrlParse is a lightweight Python module for extracting useful data from iXBRL™ and XBRL™ financial...
Tokens:13,773
Snippets:111
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### 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<VERSION_NUMBER>
git push origin v<VERSION_NUMBER>
```

--------------------------------

### 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)
<ixbrlNumeric name='exampleName' unit='USD' value=100.50>
```
```

--------------------------------

### 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 = '''<some 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"<IXBRLContext {self.id} [{datestr}]{segmentstr}>"
```

--------------------------------

### 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
```
Tokens:
Raw