nse-xbrl-parser 0.1.0__tar.gz

nse_xbrl_parser-0.1.0/PKG-INFO

@@ -0,0 +1,197 @@
+Metadata-Version: 2.3
+Name: nse-xbrl-parser
+Version: 0.1.0
+Summary: Async Python 3.14 library for parsing XBRL Filing Information of NSE & BSE across all taxonomies
+Author: innerkorehq
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: lxml>=5.2.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: python-dateutil>=2.9.0
+Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0 ; extra == 'dev'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/innerkorehq/nse-xbrl
+Project-URL: Documentation, https://innerkorehq.github.io/nse-xbrl/
+Project-URL: Repository, https://github.com/innerkorehq/nse-xbrl
+Project-URL: Issues, https://github.com/innerkorehq/nse-xbrl/issues
+Provides-Extra: dev
+Description-Content-Type: text/markdown
+
+# nse-xbrl
+
+[![Documentation](https://img.shields.io/badge/docs-online-blue.svg)](https://innerkorehq.github.io/nse-xbrl/)
+[![Python 3.12 | 3.13 | 3.14](https://img.shields.io/badge/python-3.12%20|%203.13%20|%203.14-blue.svg)](https://github.com/innerkorehq/nse-xbrl)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Modern Asynchronous Python 3.14 library for parsing XBRL Filing Information across **all 58 taxonomies** of the National Stock Exchange of India (NSE) and Bombay Stock Exchange (BSE).
+
+📖 **[Read the Documentation](https://innerkorehq.github.io/nse-xbrl/)**
+
+---
+
+## Features
+
+- **Universal XBRL 2.1 & Dimensions Parser**:
+  - Asynchronous stream and file parsing using Python 3.14 native `asyncio` and `lxml`.
+  - Automatically resolves contexts (`instant`, `duration`), entity identifiers (CIN, Scrip Code), units (`INR`, `shares`, ratios), and dimensional segments.
+  - Zero requirement for custom parsers per filing type—parses *any* NSE/BSE filing format.
+- **Coverage of all 58 NSE & BSE Taxonomies**:
+  - Built-in catalog indexing all 58 taxonomies from [NSE XBRL Information Portal](https://www.nseindia.com/static/companies-listing/xbrl-information).
+  - Automatically downloads and caches official schemas (`.xsd`), label linkbases (`*-lab.xml`), calculations, and presentations.
+- **High-Level Typed Model Adapters**:
+  - `FinancialResultsModel`: Regulation 33 Financial Results (`Ind AS`, `Banking`, `NBFC`, `Insurance`, `Integrated Filings`).
+  - `ShareholdingPatternModel`: Regulation 31 Shareholding Patterns with promoter & public breakdown.
+  - `CorporateGovernanceModel`: Regulation 27(2) Board composition & committee details.
+- **Async HTTP Client (`AsyncNSEClient`)**:
+  - Automated download and extraction of filing ZIP packages and instance XML documents.
+
+---
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv add nse-xbrl-parser
+
+# Or with pip
+pip install nse-xbrl-parser
+```
+
+---
+
+## Quickstart
+
+### 1. Parse an XBRL Filing Asynchronously
+
+```python
+import asyncio
+from nse_xbrl_parser import parse_file, FinancialResultsModel
+
+async def main():
+    # Parse any filing XML
+    instance = await parse_file("RELIANCE_Financial_Results.xml")
+
+    # Universal Fact Lookups
+    print("Company:", instance.get_fact_value("NameOfTheCompany"))
+    print("Scrip Code:", instance.get_fact_value("ScripCode"))
+    print("Revenue:", instance.get_fact_float("RevenueFromOperations"))
+
+    # Convert to Strongly-Typed Model
+    results = FinancialResultsModel.from_instance(instance)
+    print(f"PAT: ₹{results.profit_after_tax:,.2f}")
+    print(f"EBITDA: ₹{results.ebitda:,.2f}")
+    print(f"Basic EPS: ₹{results.basic_eps:.2f}")
+
+asyncio.run(main())
+```
+
+### 2. Inspect Any of the 58 NSE/BSE Taxonomies
+
+```python
+import asyncio
+from nse_xbrl_parser import TaxonomyRegistry, AsyncTaxonomyDownloader
+
+async def main():
+    registry = TaxonomyRegistry()
+
+    # Total 58 taxonomies registered
+    print("Total Taxonomies:", registry.count())
+
+    # Get Regulation 31 Shareholding Pattern Taxonomy (ID 4)
+    shp_tax = registry.get_by_id(4)
+    print(shp_tax.name)
+    print("Download URL:", shp_tax.primary_taxonomy_url)
+
+    # Download schema & label linkbase on the fly
+    downloader = AsyncTaxonomyDownloader()
+    schema, linkbase = await downloader.load_taxonomy_metadata(shp_tax)
+
+    print(f"Total concepts declared: {len(schema.elements)}")
+    print("Human friendly label:", linkbase.get_label("PublicShareholdingAsAPercentageOfTotalNumberOfShares"))
+
+asyncio.run(main())
+```
+
+### 3. Parse Shareholding Patterns & Corporate Governance
+
+```python
+from nse_xbrl_parser import parse_xbrl_sync, ShareholdingPatternModel, CorporateGovernanceModel
+
+xml_content = open("TCS_SHP.xml", "rb").read()
+instance = parse_xbrl_sync(xml_content)
+
+shp = ShareholdingPatternModel.from_instance(instance)
+print(f"Promoter Holding: {shp.promoter_holding_percentage}%")
+print(f"Public Holding: {shp.public_holding_percentage}%")
+```
+
+---
+
+## Supported Taxonomies (All 58 Categories)
+
+1. `Regulation 13 (3)` - Statement of Investor complaints
+2. `Investor complaints` - REITs / InvITs
+3. `Regulation 27 (2)` - Corporate Governance
+4. `Regulation 31` - Shareholding Pattern
+5. `Reconciliation of Share Capital Audit`
+6. `Regulation 33` - Financial Results - Ind AS & Integrated Filing
+7. `Regulation 33` - Financial Results - Other than Banks
+8. `Regulation 33` - Financial Results - REITs / InvITs
+9. `Regulation 33` - Financial Results - General Insurance
+10. `Regulation 33` - Financial Results - Life Insurance
+11. `Regulation 33` - Financial Results - Banking
+12. `Regulation 33` - Financial Results - NBFC
+13. `Regulation 44` - Voting Results
+14. `Regulation 7(2) & 7(3)` - Insider Trading
+15. `Regulation 32 (1)` - Statement of Deviation/Variation
+16. `Regulation 24A` - Secretarial Compliance Report
+17. `Regulation 60` - Record Date / Book Closure
+18. `Unit Holding Pattern`
+19. `Regulation 23 (9)` - Related Party Transactions
+20. `Business Responsibility and Sustainability Reporting (BRSR)`
+21. `Credit Rating`
+22. `Default History Information`
+23. `Interest Payment`
+24. `Redemption Payment`
+25. `Regulation 50` - Prior Intimation of Board Meeting
+26. `Regulation 29` - Prior Intimation of Board Meeting
+27. `Regulation 30` - Change in Directors / KMP / SMP / Auditor
+28. `Regulation 30` - Acquisitions / Scheme of Arrangement / Restructuring
+29. `Regulation 30` - Outcome of Board Meeting (Dividend, Bonus, Buyback)
+30. `Regulation 30` - Issuance / Forfeiture / Alteration of Securities
+31. `Regulation 30` - Material Agreements / Joint Ventures
+32. `Regulation 30` - Fraud / Defaults / Arrests
+33. `Regulation 30` - One Time Settlement (OTS)
+34. `Regulation 30` - Resolution Plan / Debt Restructuring
+35. `Regulation 30` - Notice of Shareholders Meeting
+36. `Regulation 30` - Closure of Trading Window
+37. `Regulation 39` - Loss of Share Certificate / Duplicate Issue
+38. `Regulation 30` - Corporate Insolvency Resolution Process (CIRP)
+39. `Regulation 33` - Statement on Impact of Audit Qualifications
+40. `Insider Trading Plan`
+41. `Integrated Filing - Governance`
+42. `Regulation 30` - Awarding / Bagging of Orders
+43. `ISD` - Buy-back from Open Market Route
+44. `ISD` - Buy-back through Tender Offer Route
+45. `Initial Public Offer (IPO)` - In-principle
+46. `ADR / GDR` - In-principle and Post Allotment
+47. `FCCB` - In-principle and Post Allotment
+48. `Preferential Issue` - In-principle and Post Allotment
+49. `QIP` - In-principle and Post Allotment
+50. `Rights Issue` - In-principle and Post Allotment
+51. `Initial Public Offer (IPO)` - Final Listing
+52. `Resignation of Director / KMP / SMP / Compliance Officer`
+53. `Regulation 30` - Resignation of Statutory Auditor
+54. `Regulation 30` - Forensic Audit
+55. `Regulation 30` - Actions initiated / taken or orders passed
+56. `Regulation 30` - Analyst / Investor Meet
+57. `Violation of Code of Conduct` (Insider Trading)
+58. `Regulation 30` - Para B of Part A of Schedule III
+
+---
+
+## Testing
+
+```bash
+uv run pytest
+```

nse_xbrl_parser-0.1.0/README.md

@@ -0,0 +1,178 @@
+# nse-xbrl
+
+[![Documentation](https://img.shields.io/badge/docs-online-blue.svg)](https://innerkorehq.github.io/nse-xbrl/)
+[![Python 3.12 | 3.13 | 3.14](https://img.shields.io/badge/python-3.12%20|%203.13%20|%203.14-blue.svg)](https://github.com/innerkorehq/nse-xbrl)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Modern Asynchronous Python 3.14 library for parsing XBRL Filing Information across **all 58 taxonomies** of the National Stock Exchange of India (NSE) and Bombay Stock Exchange (BSE).
+
+📖 **[Read the Documentation](https://innerkorehq.github.io/nse-xbrl/)**
+
+---
+
+## Features
+
+- **Universal XBRL 2.1 & Dimensions Parser**:
+  - Asynchronous stream and file parsing using Python 3.14 native `asyncio` and `lxml`.
+  - Automatically resolves contexts (`instant`, `duration`), entity identifiers (CIN, Scrip Code), units (`INR`, `shares`, ratios), and dimensional segments.
+  - Zero requirement for custom parsers per filing type—parses *any* NSE/BSE filing format.
+- **Coverage of all 58 NSE & BSE Taxonomies**:
+  - Built-in catalog indexing all 58 taxonomies from [NSE XBRL Information Portal](https://www.nseindia.com/static/companies-listing/xbrl-information).
+  - Automatically downloads and caches official schemas (`.xsd`), label linkbases (`*-lab.xml`), calculations, and presentations.
+- **High-Level Typed Model Adapters**:
+  - `FinancialResultsModel`: Regulation 33 Financial Results (`Ind AS`, `Banking`, `NBFC`, `Insurance`, `Integrated Filings`).
+  - `ShareholdingPatternModel`: Regulation 31 Shareholding Patterns with promoter & public breakdown.
+  - `CorporateGovernanceModel`: Regulation 27(2) Board composition & committee details.
+- **Async HTTP Client (`AsyncNSEClient`)**:
+  - Automated download and extraction of filing ZIP packages and instance XML documents.
+
+---
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv add nse-xbrl-parser
+
+# Or with pip
+pip install nse-xbrl-parser
+```
+
+---
+
+## Quickstart
+
+### 1. Parse an XBRL Filing Asynchronously
+
+```python
+import asyncio
+from nse_xbrl_parser import parse_file, FinancialResultsModel
+
+async def main():
+    # Parse any filing XML
+    instance = await parse_file("RELIANCE_Financial_Results.xml")
+
+    # Universal Fact Lookups
+    print("Company:", instance.get_fact_value("NameOfTheCompany"))
+    print("Scrip Code:", instance.get_fact_value("ScripCode"))
+    print("Revenue:", instance.get_fact_float("RevenueFromOperations"))
+
+    # Convert to Strongly-Typed Model
+    results = FinancialResultsModel.from_instance(instance)
+    print(f"PAT: ₹{results.profit_after_tax:,.2f}")
+    print(f"EBITDA: ₹{results.ebitda:,.2f}")
+    print(f"Basic EPS: ₹{results.basic_eps:.2f}")
+
+asyncio.run(main())
+```
+
+### 2. Inspect Any of the 58 NSE/BSE Taxonomies
+
+```python
+import asyncio
+from nse_xbrl_parser import TaxonomyRegistry, AsyncTaxonomyDownloader
+
+async def main():
+    registry = TaxonomyRegistry()
+
+    # Total 58 taxonomies registered
+    print("Total Taxonomies:", registry.count())
+
+    # Get Regulation 31 Shareholding Pattern Taxonomy (ID 4)
+    shp_tax = registry.get_by_id(4)
+    print(shp_tax.name)
+    print("Download URL:", shp_tax.primary_taxonomy_url)
+
+    # Download schema & label linkbase on the fly
+    downloader = AsyncTaxonomyDownloader()
+    schema, linkbase = await downloader.load_taxonomy_metadata(shp_tax)
+
+    print(f"Total concepts declared: {len(schema.elements)}")
+    print("Human friendly label:", linkbase.get_label("PublicShareholdingAsAPercentageOfTotalNumberOfShares"))
+
+asyncio.run(main())
+```
+
+### 3. Parse Shareholding Patterns & Corporate Governance
+
+```python
+from nse_xbrl_parser import parse_xbrl_sync, ShareholdingPatternModel, CorporateGovernanceModel
+
+xml_content = open("TCS_SHP.xml", "rb").read()
+instance = parse_xbrl_sync(xml_content)
+
+shp = ShareholdingPatternModel.from_instance(instance)
+print(f"Promoter Holding: {shp.promoter_holding_percentage}%")
+print(f"Public Holding: {shp.public_holding_percentage}%")
+```
+
+---
+
+## Supported Taxonomies (All 58 Categories)
+
+1. `Regulation 13 (3)` - Statement of Investor complaints
+2. `Investor complaints` - REITs / InvITs
+3. `Regulation 27 (2)` - Corporate Governance
+4. `Regulation 31` - Shareholding Pattern
+5. `Reconciliation of Share Capital Audit`
+6. `Regulation 33` - Financial Results - Ind AS & Integrated Filing
+7. `Regulation 33` - Financial Results - Other than Banks
+8. `Regulation 33` - Financial Results - REITs / InvITs
+9. `Regulation 33` - Financial Results - General Insurance
+10. `Regulation 33` - Financial Results - Life Insurance
+11. `Regulation 33` - Financial Results - Banking
+12. `Regulation 33` - Financial Results - NBFC
+13. `Regulation 44` - Voting Results
+14. `Regulation 7(2) & 7(3)` - Insider Trading
+15. `Regulation 32 (1)` - Statement of Deviation/Variation
+16. `Regulation 24A` - Secretarial Compliance Report
+17. `Regulation 60` - Record Date / Book Closure
+18. `Unit Holding Pattern`
+19. `Regulation 23 (9)` - Related Party Transactions
+20. `Business Responsibility and Sustainability Reporting (BRSR)`
+21. `Credit Rating`
+22. `Default History Information`
+23. `Interest Payment`
+24. `Redemption Payment`
+25. `Regulation 50` - Prior Intimation of Board Meeting
+26. `Regulation 29` - Prior Intimation of Board Meeting
+27. `Regulation 30` - Change in Directors / KMP / SMP / Auditor
+28. `Regulation 30` - Acquisitions / Scheme of Arrangement / Restructuring
+29. `Regulation 30` - Outcome of Board Meeting (Dividend, Bonus, Buyback)
+30. `Regulation 30` - Issuance / Forfeiture / Alteration of Securities
+31. `Regulation 30` - Material Agreements / Joint Ventures
+32. `Regulation 30` - Fraud / Defaults / Arrests
+33. `Regulation 30` - One Time Settlement (OTS)
+34. `Regulation 30` - Resolution Plan / Debt Restructuring
+35. `Regulation 30` - Notice of Shareholders Meeting
+36. `Regulation 30` - Closure of Trading Window
+37. `Regulation 39` - Loss of Share Certificate / Duplicate Issue
+38. `Regulation 30` - Corporate Insolvency Resolution Process (CIRP)
+39. `Regulation 33` - Statement on Impact of Audit Qualifications
+40. `Insider Trading Plan`
+41. `Integrated Filing - Governance`
+42. `Regulation 30` - Awarding / Bagging of Orders
+43. `ISD` - Buy-back from Open Market Route
+44. `ISD` - Buy-back through Tender Offer Route
+45. `Initial Public Offer (IPO)` - In-principle
+46. `ADR / GDR` - In-principle and Post Allotment
+47. `FCCB` - In-principle and Post Allotment
+48. `Preferential Issue` - In-principle and Post Allotment
+49. `QIP` - In-principle and Post Allotment
+50. `Rights Issue` - In-principle and Post Allotment
+51. `Initial Public Offer (IPO)` - Final Listing
+52. `Resignation of Director / KMP / SMP / Compliance Officer`
+53. `Regulation 30` - Resignation of Statutory Auditor
+54. `Regulation 30` - Forensic Audit
+55. `Regulation 30` - Actions initiated / taken or orders passed
+56. `Regulation 30` - Analyst / Investor Meet
+57. `Violation of Code of Conduct` (Insider Trading)
+58. `Regulation 30` - Para B of Part A of Schedule III
+
+---
+
+## Testing
+
+```bash
+uv run pytest
+```

nse_xbrl_parser-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "nse-xbrl-parser"
+version = "0.1.0"
+description = "Async Python 3.14 library for parsing XBRL Filing Information of NSE & BSE across all taxonomies"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "aiohttp>=3.9.0",
+    "lxml>=5.2.0",
+    "pydantic>=2.7.0",
+    "python-dateutil>=2.9.0",
+]
+
+[[project.authors]]
+name = "innerkorehq"
+
+[project.urls]
+Homepage = "https://github.com/innerkorehq/nse-xbrl"
+Documentation = "https://innerkorehq.github.io/nse-xbrl/"
+Repository = "https://github.com/innerkorehq/nse-xbrl"
+Issues = "https://github.com/innerkorehq/nse-xbrl/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.21,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "myst-parser>=5.1.0",
+    "pydata-sphinx-theme>=0.22.0",
+    "sphinx>=9.1.0",
+    "sphinx-copybutton>=0.5.2",
+    "sphinx-design>=0.7.0",
+    "sphinxcontrib-mermaid>=2.1.1",
+]

nse_xbrl_parser-0.1.0/pyproject.toml.orig

@@ -0,0 +1,45 @@
+[project]
+name = "nse-xbrl-parser"
+version = "0.1.0"
+description = "Async Python 3.14 library for parsing XBRL Filing Information of NSE & BSE across all taxonomies"
+readme = "README.md"
+authors = [
+    { name = "innerkorehq" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "aiohttp>=3.9.0",
+    "lxml>=5.2.0",
+    "pydantic>=2.7.0",
+    "python-dateutil>=2.9.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/innerkorehq/nse-xbrl"
+Documentation = "https://innerkorehq.github.io/nse-xbrl/"
+Repository = "https://github.com/innerkorehq/nse-xbrl"
+Issues = "https://github.com/innerkorehq/nse-xbrl/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.21,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "myst-parser>=5.1.0",
+    "pydata-sphinx-theme>=0.22.0",
+    "sphinx>=9.1.0",
+    "sphinx-copybutton>=0.5.2",
+    "sphinx-design>=0.7.0",
+    "sphinxcontrib-mermaid>=2.1.1",
+]

nse_xbrl_parser-0.1.0/src/nse_xbrl_parser/__init__.py

@@ -0,0 +1,86 @@
+"""
+nse-xbrl
+
+Async Python 3.14 library for parsing XBRL Filing Information of NSE & BSE across all taxonomies.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import List, Union
+
+from .client.nse_client import AsyncNSEClient
+from .core.context import ExplicitMember, PeriodType, XBRLContext
+from .core.models import XBRLFact, XBRLInstance
+from .core.parser import AsyncXBRLParser
+from .core.unit import XBRLUnit
+from .taxonomy.downloader import AsyncTaxonomyDownloader
+from .taxonomy.linkbase import ConceptLabel, TaxonomyLinkbase
+from .taxonomy.registry import TaxonomyInfo, TaxonomyRegistry
+from .taxonomy.schema import SchemaElement, TaxonomySchema
+from .typed.corporate_governance import CorporateGovernanceModel
+from .typed.financial_results import FinancialResultsModel
+from .typed.shareholding import ShareholdingPatternModel
+
+__version__ = "0.1.0"
+
+_parser = AsyncXBRLParser()
+
+
+async def parse_xbrl(
+    content: Union[str, bytes],
+    source_name: str | None = None,
+) -> XBRLInstance:
+    """Parse an XBRL XML instance document asynchronously.
+    
+    Args:
+        content: XML string or raw bytes.
+        source_name: Optional file or URL name for tracking.
+        
+    Returns:
+        XBRLInstance: Universal representation of facts, contexts, and units.
+    """
+    return await _parser.parse(content, source_name=source_name)
+
+
+async def parse_file(file_path: Union[str, Path]) -> XBRLInstance:
+    """Parse a local XBRL file asynchronously."""
+    return await _parser.parse_file(file_path)
+
+
+async def parse_archive(zip_bytes: bytes) -> List[XBRLInstance]:
+    """Parse all XBRL filings within a zip archive asynchronously."""
+    return await _parser.parse_zip(zip_bytes)
+
+
+def parse_xbrl_sync(
+    content: Union[str, bytes],
+    source_name: str | None = None,
+) -> XBRLInstance:
+    """Synchronous parsing convenience function."""
+    return _parser.parse_sync(content, source_name=source_name)
+
+
+__all__ = [
+    "parse_xbrl",
+    "parse_file",
+    "parse_archive",
+    "parse_xbrl_sync",
+    "AsyncXBRLParser",
+    "XBRLInstance",
+    "XBRLFact",
+    "XBRLContext",
+    "XBRLUnit",
+    "PeriodType",
+    "ExplicitMember",
+    "TaxonomyRegistry",
+    "TaxonomyInfo",
+    "TaxonomySchema",
+    "SchemaElement",
+    "TaxonomyLinkbase",
+    "ConceptLabel",
+    "AsyncTaxonomyDownloader",
+    "FinancialResultsModel",
+    "ShareholdingPatternModel",
+    "CorporateGovernanceModel",
+    "AsyncNSEClient",
+]

nse_xbrl_parser-0.1.0/src/nse_xbrl_parser/client/__init__.py

@@ -0,0 +1,10 @@
+"""
+nse_xbrl_parser.client
+
+Async clients for NSE and BSE filings.
+"""
+from __future__ import annotations
+
+from .nse_client import AsyncNSEClient
+
+__all__ = ["AsyncNSEClient"]

nse_xbrl_parser-0.1.0/src/nse_xbrl_parser/client/nse_client.py

@@ -0,0 +1,93 @@
+"""
+nse_xbrl_parser.client.nse_client
+
+Asynchronous client for interacting with NSE corporate filings and archive downloads.
+"""
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+import aiohttp
+
+from ..core.models import XBRLInstance
+from ..core.parser import AsyncXBRLParser
+from ..taxonomy.downloader import AsyncTaxonomyDownloader
+from ..taxonomy.registry import TaxonomyInfo, TaxonomyRegistry
+
+
+class AsyncNSEClient:
+    """Asynchronous client for downloading and parsing NSE XBRL disclosures."""
+
+    DEFAULT_USER_AGENT = (
+        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) "
+        "AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+    )
+
+    def __init__(
+        self,
+        cookie_string: Optional[str] = None,
+        cache_dir: Optional[Path] = None,
+    ) -> None:
+        self.cookie_string = cookie_string
+        self.parser = AsyncXBRLParser()
+        self.registry = TaxonomyRegistry()
+        self.downloader = AsyncTaxonomyDownloader(cache_dir=cache_dir)
+        self._session: Optional[aiohttp.ClientSession] = None
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            headers = {
+                "User-Agent": self.DEFAULT_USER_AGENT,
+                "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+                "Referer": "https://www.nseindia.com/",
+            }
+            if self.cookie_string:
+                headers["Cookie"] = self.cookie_string
+            self._session = aiohttp.ClientSession(headers=headers)
+        return self._session
+
+    async def close(self) -> None:
+        """Close client session."""
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    async def __aenter__(self) -> AsyncNSEClient:
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.close()
+
+    async def download_bytes(self, url: str) -> bytes:
+        """Download raw bytes from URL asynchronously."""
+        session = await self._get_session()
+        async with session.get(url) as response:
+            if response.status != 200:
+                raise ConnectionError(f"HTTP GET failed with status {response.status} for {url}")
+            return await response.read()
+
+    async def parse_url(self, url: str) -> XBRLInstance:
+        """Download XBRL instance document from URL and parse it."""
+        data = await self.download_bytes(url)
+        return await self.parser.parse(data, source_name=url)
+
+    async def parse_url_archive(self, zip_url: str) -> List[XBRLInstance]:
+        """Download ZIP archive from URL and parse all contained XBRL filings."""
+        data = await self.download_bytes(zip_url)
+        return await self.parser.parse_zip(data)
+
+    async def get_taxonomy_schema(self, taxonomy_id: int):
+        """Fetch schema for any of the 58 NSE taxonomies."""
+        info = self.registry.get_by_id(taxonomy_id)
+        if not info:
+            raise KeyError(f"Taxonomy ID {taxonomy_id} not found in registry (1-58)")
+        schema, _ = await self.downloader.load_taxonomy_metadata(info)
+        return schema
+
+    async def get_taxonomy_labels(self, taxonomy_id: int):
+        """Fetch label dictionary for any of the 58 NSE taxonomies."""
+        info = self.registry.get_by_id(taxonomy_id)
+        if not info:
+            raise KeyError(f"Taxonomy ID {taxonomy_id} not found in registry (1-58)")
+        _, linkbase = await self.downloader.load_taxonomy_metadata(info)
+        return linkbase

nse_xbrl_parser-0.1.0/src/nse_xbrl_parser/core/__init__.py

@@ -0,0 +1,21 @@
+"""
+nse_xbrl_parser.core
+
+Core XBRL models, contexts, units, and asynchronous parser engine.
+"""
+from __future__ import annotations
+
+from .context import ExplicitMember, PeriodType, XBRLContext
+from .models import XBRLFact, XBRLInstance
+from .parser import AsyncXBRLParser
+from .unit import XBRLUnit
+
+__all__ = [
+    "ExplicitMember",
+    "PeriodType",
+    "XBRLContext",
+    "XBRLFact",
+    "XBRLInstance",
+    "XBRLUnit",
+    "AsyncXBRLParser",
+]