Core API Reference#

Universal models and parsing engine in nse_xbrl_parser.core.

High-Level Parsing Functions#

async nse_xbrl_parser.parse_xbrl(content, source_name=None)[source]#

Parse an XBRL XML instance document asynchronously into a universal XBRLInstance.

Parameters:

content (str | bytes)
source_name (str | None)

Return type:

XBRLInstance

async nse_xbrl_parser.parse_file(file_path)[source]#

Parse a local XBRL file asynchronously into a universal XBRLInstance.

Parameters:: file_path (str | Path)
Return type:: XBRLInstance

async nse_xbrl_parser.parse_archive(zip_bytes)[source]#

Parse all XBRL filings within a zip archive asynchronously.

Parameters:: zip_bytes (bytes)
Return type:: List[XBRLInstance]

nse_xbrl_parser.parse_xbrl_sync(content, source_name=None)[source]#

Synchronous universal parsing convenience function.

Parameters:

content (str | bytes)
source_name (str | None)

Return type:

XBRLInstance

Parsing Engine#

class nse_xbrl_parser.core.parser.AsyncXBRLParser[source]#

Bases: object

High-performance parser for XBRL instance documents.

__init__()[source]#

Return type:: None

async parse(content, source_name=None)[source]#

Parse XML string or bytes asynchronously without blocking the event loop.

Parameters:

content (str | bytes)
source_name (str | None)

Return type:

XBRLInstance

async parse_file(file_path)[source]#

Parse a local XML file asynchronously.

Parameters:: file_path (str | Path)
Return type:: XBRLInstance

async parse_zip(zip_content)[source]#

Parse all XBRL XML files contained in a ZIP archive.

Parameters:: zip_content (bytes)
Return type:: List[XBRLInstance]

parse_sync(content, source_name=None)[source]#

Parse XML synchronously into an XBRLInstance.

Parameters:

content (str | bytes)
source_name (str | None)

Return type:

XBRLInstance

Universal Models#

class nse_xbrl_parser.core.models.XBRLInstance(*, source=None, target_namespaces=<factory>, schema_refs=<factory>, contexts=<factory>, units=<factory>, facts=<factory>)[source]#

Bases: BaseModel

Universal model representing a parsed XBRL instance document.

Parameters:

source (str | None)
target_namespaces (Dict[str, str])
schema_refs (List[str])
contexts (Dict[str, XBRLContext])
units (Dict[str, XBRLUnit])
facts (List[XBRLFact])

source: str | None#

target_namespaces: Dict[str, str]#

schema_refs: List[str]#

contexts: Dict[str, XBRLContext]#

units: Dict[str, XBRLUnit]#

facts: List[XBRLFact]#

model_post_init(_XBRLInstance__context)[source]#

Override this method to perform additional initialization after __init__ and model_construct. This is useful if you want to do some validation that requires the entire model to be initialized.

Parameters:: _XBRLInstance__context (Any)
Return type:: None

get_facts_by_tag(tag_name)[source]#

Lookup facts by case-insensitive tag name (e.g. ‘RevenueFromOperations’ or ‘ScripCode’).

Parameters:: tag_name (str)
Return type:: List[XBRLFact]

get_fact_value(tag_name, context_ref=None, default=None)[source]#

Get parsed value for a tag. If context_ref is specified, returns match for that context.

Parameters:

tag_name (str)
context_ref (str | None)
default (Any)

Return type:

Any

get_fact_float(tag_name, context_ref=None, default=None)[source]#

Get numeric float value for a tag.

Parameters:

tag_name (str)
context_ref (str | None)
default (float | None)

Return type:

float | None

get_entity_id()[source]#

Extract first available entity identifier (e.g. Scrip code or CIN).

Return type:: str | None

search_facts(regex_pattern)[source]#

Search all facts whose local tag matches a regular expression.

Parameters:: regex_pattern (str)
Return type:: List[XBRLFact]

to_dict()[source]#

Convert facts into flat dictionary of tag -> value for simple context.

Return type:: Dict[str, Any]

model_config = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class nse_xbrl_parser.core.models.XBRLFact(*, tag, namespace='', prefix='', context_ref, unit_ref=None, decimals=None, scale=None, raw_value, value=None)[source]#

Bases: BaseModel

Represents a single parsed XBRL Fact.

Parameters:

tag (str)
namespace (str)
prefix (str)
context_ref (str)
unit_ref (str | None)
decimals (str | None)
scale (int | None)
raw_value (str)
value (float | int | bool | str | None)

tag: str#

namespace: str#

prefix: str#

context_ref: str#

unit_ref: str | None#

decimals: str | None#

scale: int | None#

raw_value: str#

value: float | int | bool | str | None#

property local_name: str#: Return the tag name without any prefix or namespace.

property is_numeric: bool#

property as_float: float | None#

model_config = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class nse_xbrl_parser.core.context.XBRLContext(*, context_id, entity_id='', entity_scheme='', period_type=PeriodType.DURATION, instant=None, start_date=None, end_date=None, dimensions=<factory>, scenario_dimensions=<factory>)[source]#

Bases: BaseModel

Represents an XBRL context element.

Parameters:

context_id (str)
entity_id (str)
entity_scheme (str)
period_type (PeriodType)
instant (date | None)
start_date (date | None)
end_date (date | None)
dimensions (Dict[str, str])
scenario_dimensions (Dict[str, str])

context_id: str#

entity_id: str#

entity_scheme: str#

period_type: PeriodType#

instant: date | None#

start_date: date | None#

end_date: date | None#

dimensions: Dict[str, str]#

scenario_dimensions: Dict[str, str]#

property is_instant: bool#

property is_duration: bool#

property is_standalone: bool#: Check if context explicitly targets Standalone filing.

property is_consolidated: bool#: Check if context explicitly targets Consolidated filing.

model_config = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class nse_xbrl_parser.core.unit.XBRLUnit(*, unit_id, measure, measure_namespace=None, divide_numerator=None, divide_denominator=None)[source]#

Bases: BaseModel

Represents an XBRL unit element (e.g. INR, Shares, Pure).

Parameters:

unit_id (str)
measure (str)
measure_namespace (str | None)
divide_numerator (str | None)
divide_denominator (str | None)

unit_id: str#

measure: str#

measure_namespace: str | None#

divide_numerator: str | None#

divide_denominator: str | None#

property is_currency: bool#: Return True if unit represents a currency (e.g. INR, USD).

property is_shares: bool#: Return True if unit represents shares.

property is_ratio: bool#: Return True if unit is a dimensionless ratio/percentage.

model_config = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].