nepsepy 1.0.0__tar.gz

nepsepy-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nepsepy contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nepsepy-1.0.0/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.4
+Name: nepsepy
+Version: 1.0.0
+Summary: Unofficial Python client for public Nepal Stock Exchange market data
+Author: nepsepy contributors
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: wasmtime>=12
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# nepsepy
+
+![nepsepy banner](https://res.cloudinary.com/dzbc5mlm9/image/upload/v1790524377/nepsepybanner_ucetgq.png)
+
+[![PyPI](https://img.shields.io/pypi/v/nepsepy?logo=pypi&logoColor=white)](https://pypi.org/project/nepsepy/)
+[![Python](https://img.shields.io/pypi/pyversions/nepsepy?logo=python&logoColor=white)](https://pypi.org/project/nepsepy/)
+[![Tests](https://github.com/menaceXnadin/nepsepy/actions/workflows/tests.yml/badge.svg)](https://github.com/menaceXnadin/nepsepy/actions/workflows/tests.yml)
+[![License](https://img.shields.io/badge/license-MIT-0b7f52)](LICENSE)
+
+> A clean Python interface for public Nepal Stock Exchange (NEPSE) market data.
+
+`nepsepy` provides a small, synchronous API for market status, prices, floor
+sheets, indices, company information, notices, and other data used by the
+NEPSE website.
+
+It is not affiliated with the Nepal Stock Exchange.
+
+## Why nepsepy?
+
+- **Simple API** — use named methods such as `today_price()` and
+  `security_profile()` instead of manually assembling HTTP requests.
+- **Public session handling** — performs the same login-free bootstrap used by
+  the NEPSE frontend; no user credentials are needed.
+- **Careful by default** — requests are paced, token values are kept in memory,
+  and rate limiting is surfaced clearly instead of retried aggressively.
+
+## Installation
+
+Requires Python 3.10 or later.
+
+```bash
+python -m pip install nepsepy
+```
+
+The PyPI distribution and Python import package are both named `nepsepy`.
+
+## Quick start
+
+```python
+from nepsepy import NepseClient
+
+with NepseClient() as client:
+    status = client.market_status()
+    gainers = client.top_gainers()
+    prices = client.today_price(page=1, size=20)
+
+    print(status["isOpen"])
+    print(gainers[:3])
+    print(prices["content"][:3])
+```
+
+Most methods return the JSON object or list supplied by NEPSE. Pagination uses
+1-based page numbers, matching the website UI. Dates use `yyyy-MM-dd`.
+
+## Features
+
+| Area | Included data |
+| --- | --- |
+| Market | Status, summaries, live market data, ticker, and top-ten lists |
+| Prices & trades | Today’s prices, floor sheets, depth, supply/demand, and trade history |
+| Charts | NEPSE indices, index history, and market/company chart data |
+| Companies | Profiles, corporate actions, financial reports, dividends, AGMs, and news |
+| Directories | Companies, sectors, share groups, promoters, brokers, and dealers |
+| News & files | Notices, disclosures, holidays, reports, events, CSV exports, and downloads |
+
+## Authentication and rate limits
+
+No account credentials are required. `NepseClient` performs the same public
+session bootstrap used by NEPSE’s frontend when it is first needed. Session
+tokens stay in memory and are redacted from package diagnostics.
+
+Requests are paced conservatively. A `429 Too Many Requests` response raises
+`RateLimitedError`; the client does not retry in a loop.
+
+## Common examples
+
+```python
+from nepsepy import NepseClient
+
+with NepseClient() as client:
+    # Use numeric security IDs; resolve them from companies() or securities().
+    companies = client.companies()
+    barun = next(row for row in companies if row["symbol"] == "BARUN")
+
+    profile = client.security_profile(barun["id"])
+    floorsheet = client.floorsheets(stock_id=barun["id"])
+
+    print(profile)
+    print(floorsheet["totalTrades"])
+```
+
+## Interactive explorer
+
+The repository includes a terminal explorer for local use:
+
+```bash
+python tui.py
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest -q
+```
+
+## Scope and disclaimer
+
+This package is for public, read-only market-data workflows. It does not handle
+user login, trading, portfolio actions, or other state-changing operations.
+NEPSE data may be delayed or corrected by the exchange; verify information
+independently before making financial decisions.
+
+## License
+
+Distributed under the [MIT License](LICENSE).

nepsepy-1.0.0/README.md

@@ -0,0 +1,116 @@
+# nepsepy
+
+![nepsepy banner](https://res.cloudinary.com/dzbc5mlm9/image/upload/v1790524377/nepsepybanner_ucetgq.png)
+
+[![PyPI](https://img.shields.io/pypi/v/nepsepy?logo=pypi&logoColor=white)](https://pypi.org/project/nepsepy/)
+[![Python](https://img.shields.io/pypi/pyversions/nepsepy?logo=python&logoColor=white)](https://pypi.org/project/nepsepy/)
+[![Tests](https://github.com/menaceXnadin/nepsepy/actions/workflows/tests.yml/badge.svg)](https://github.com/menaceXnadin/nepsepy/actions/workflows/tests.yml)
+[![License](https://img.shields.io/badge/license-MIT-0b7f52)](LICENSE)
+
+> A clean Python interface for public Nepal Stock Exchange (NEPSE) market data.
+
+`nepsepy` provides a small, synchronous API for market status, prices, floor
+sheets, indices, company information, notices, and other data used by the
+NEPSE website.
+
+It is not affiliated with the Nepal Stock Exchange.
+
+## Why nepsepy?
+
+- **Simple API** — use named methods such as `today_price()` and
+  `security_profile()` instead of manually assembling HTTP requests.
+- **Public session handling** — performs the same login-free bootstrap used by
+  the NEPSE frontend; no user credentials are needed.
+- **Careful by default** — requests are paced, token values are kept in memory,
+  and rate limiting is surfaced clearly instead of retried aggressively.
+
+## Installation
+
+Requires Python 3.10 or later.
+
+```bash
+python -m pip install nepsepy
+```
+
+The PyPI distribution and Python import package are both named `nepsepy`.
+
+## Quick start
+
+```python
+from nepsepy import NepseClient
+
+with NepseClient() as client:
+    status = client.market_status()
+    gainers = client.top_gainers()
+    prices = client.today_price(page=1, size=20)
+
+    print(status["isOpen"])
+    print(gainers[:3])
+    print(prices["content"][:3])
+```
+
+Most methods return the JSON object or list supplied by NEPSE. Pagination uses
+1-based page numbers, matching the website UI. Dates use `yyyy-MM-dd`.
+
+## Features
+
+| Area | Included data |
+| --- | --- |
+| Market | Status, summaries, live market data, ticker, and top-ten lists |
+| Prices & trades | Today’s prices, floor sheets, depth, supply/demand, and trade history |
+| Charts | NEPSE indices, index history, and market/company chart data |
+| Companies | Profiles, corporate actions, financial reports, dividends, AGMs, and news |
+| Directories | Companies, sectors, share groups, promoters, brokers, and dealers |
+| News & files | Notices, disclosures, holidays, reports, events, CSV exports, and downloads |
+
+## Authentication and rate limits
+
+No account credentials are required. `NepseClient` performs the same public
+session bootstrap used by NEPSE’s frontend when it is first needed. Session
+tokens stay in memory and are redacted from package diagnostics.
+
+Requests are paced conservatively. A `429 Too Many Requests` response raises
+`RateLimitedError`; the client does not retry in a loop.
+
+## Common examples
+
+```python
+from nepsepy import NepseClient
+
+with NepseClient() as client:
+    # Use numeric security IDs; resolve them from companies() or securities().
+    companies = client.companies()
+    barun = next(row for row in companies if row["symbol"] == "BARUN")
+
+    profile = client.security_profile(barun["id"])
+    floorsheet = client.floorsheets(stock_id=barun["id"])
+
+    print(profile)
+    print(floorsheet["totalTrades"])
+```
+
+## Interactive explorer
+
+The repository includes a terminal explorer for local use:
+
+```bash
+python tui.py
+```
+
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+pytest -q
+```
+
+## Scope and disclaimer
+
+This package is for public, read-only market-data workflows. It does not handle
+user login, trading, portfolio actions, or other state-changing operations.
+NEPSE data may be delayed or corrected by the exchange; verify information
+independently before making financial decisions.
+
+## License
+
+Distributed under the [MIT License](LICENSE).

nepsepy-1.0.0/nepsepy/__init__.py

@@ -0,0 +1,18 @@
+"""Public NEPSE market-data client (normal public-site flow only)."""
+
+from .auth import ProveResponse, TokenState
+from .checksum import base as checksum_base
+from .checksum import current_day as checksum_day
+from .checksum import variant_a as checksum_a
+from .checksum import variant_b as checksum_b
+from .checksum import variant_c as checksum_c
+from .client import NepseClient
+from .exceptions import (AuthExpiredError, BootstrapError, NepseError,
+                         PublicEndpointError, RateLimitedError, WasmError)
+from .wasm import WasmCleaner, redact, strip_at_indexes
+
+__all__ = ["NepseClient", "ProveResponse", "TokenState", "WasmCleaner",
+           "redact", "strip_at_indexes", "NepseError", "BootstrapError",
+           "WasmError", "AuthExpiredError", "RateLimitedError",
+           "PublicEndpointError", "checksum_base", "checksum_day",
+           "checksum_a", "checksum_b", "checksum_c"]

nepsepy-1.0.0/nepsepy/_company.py

@@ -0,0 +1,115 @@
+"""Per-security data and company tabs. endpoints (mixin for NepseClient)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class CompanyMixin:
+    # -- per-security data (GET; mirrors company tabs) --------------------------
+    def security_detail(self, security_id: int) -> dict:
+        """{securityData, securityMcsData} (Market Depth page header)."""
+        return self.get_json(f"/api/nots/security/{security_id}")  # type: ignore[return-value]
+
+    def security_profile(self, security_id: int) -> dict:
+        return self.get_json(f"/api/nots/security/profile/{security_id}")  # type: ignore[return-value]
+
+    def board_of_directors(self, security_id: int) -> list:
+        return self.get_json(f"/api/nots/security/boardOfDirectors/{security_id}")  # type: ignore[return-value]
+
+    def corporate_actions(self, security_id: int) -> list:
+        """Bonus/cash/right [{fiscalYear, bonusPercentage, ...}]."""
+        return self.get_json(f"/api/nots/security/corporate-actions/{security_id}")  # type: ignore[return-value]
+
+    def financial_reports(self, security_id: int) -> list:
+        return self.get_json(f"/api/nots/application/reports/{security_id}")  # type: ignore[return-value]
+
+    def agm(self, security_id: int) -> list:
+        return self.get_json(f"/api/nots/application/agm/{security_id}")  # type: ignore[return-value]
+
+    def security_company_news(self, security_id: int) -> list:
+        return self.get_json(f"/api/nots/application/company-news/{security_id}")  # type: ignore[return-value]
+
+    def market_security(self, security_id: int) -> dict:
+        """Flat daily-trade snapshot + nested security (Listing Information)."""
+        return self.get_json(f"/api/nots/market/security/{security_id}")  # type: ignore[return-value]
+
+    def security_market_picture(self, security_id: int) -> dict:
+        """Compact quote {receivedDateTime, securityId, lastTradedPrice,
+        openPrice, highPrice, lowPrice} (site's getSecurityDetailsFromMarketPicture)."""
+        return self.get_json(f"/api/nots/security-detail/{security_id}")  # type: ignore[return-value]
+
+    def dividends(self, security_id: int) -> list:
+        """Dividend applications/news for a security (site's getSecurityDividendNewsById)."""
+        return self.get_json(f"/api/nots/application/dividend/{security_id}")  # type: ignore[return-value]
+
+    def book_close(self, news_id: int) -> dict:
+        """Book-closure news by id (site's getSecurityBookCloseNewsById).
+
+        NOTE: currently HTTP 404 for every id tried (security ids and
+        company-news ids alike), so this is mapped-but-dead like
+        security_floorsheet() until the backend serves it again.
+        """
+        return self.get_json(f"/api/nots/news/book-close/{news_id}")  # type: ignore[return-value]
+
+    def security_price_history(self, security_id: int, page: int = 1,
+                               size: int = 20,
+                               business_date: Optional[str] = None) -> dict:
+        """Price History tab (Spring page of OHLCV rows; page 1-based)."""
+        query = f"?&size={size}"
+        if business_date:
+            query += f"&businessDate={business_date}"
+        if page > 1:
+            query = f"?page={page - 1}&size={size}" + (
+                f"&businessDate={business_date}" if business_date else "")
+        return self.get_json(f"/api/nots/market/security/price/{security_id}{query}")  # type: ignore[return-value]
+
+    def stock_trading_history(self, security_id: int, page: int = 1,
+                              size: int = 20,
+                              start: Optional[str] = None,
+                              end: Optional[str] = None) -> dict:
+        """Stock Trading page (page 1-based; dates 'yyyy-MM-dd')."""
+        query = f"?&size={size}"
+        if start:
+            query += f"&startDate={start}"
+        if end:
+            query += f"&endDate={end}"
+        if page > 1:
+            query = f"?page={page - 1}&size={size}" + (
+                f"&startDate={start}" if start else "") + (
+                    f"&endDate={end}" if end else "")
+        return self.get_json(f"/api/nots/market/history/security/{security_id}{query}")  # type: ignore[return-value]
+
+    def trading_average(self, n_days: int = 120,
+                        business_date: Optional[str] = None,
+                        stock_id: Optional[int] = None) -> list:
+        """N-day average price per security (Trading Average page)."""
+        path = f"/api/nots/nepse-data/trading-average?nDays={n_days}"
+        if business_date:
+            path += f"&businessDate={business_date}"
+        if stock_id is not None:
+            path += f"&stockId={stock_id}"
+        return self.get_json(path)  # type: ignore[return-value]
+
+    def market_cap_history(self, page: int = 1) -> list:
+        """Daily market caps [{businessDate, marCap, ...}] (filter client-side)."""
+        path = "/api/nots/nepse-data/marcapbydate/?"
+        if page > 1:
+            path = f"/api/nots/nepse-data/marcapbydate/?page={page - 1}"
+        return self.get_json(path)  # type: ignore[return-value]
+
+    # -- signed POST: company data --------------------------------------------------
+    def company_info(self, security_id: int) -> dict:
+        """Company header {securityDailyTradeDto, security, ...} (detail page)."""
+        return self.post_json(f"/api/nots/security/{security_id}",  # type: ignore[return-value]
+                              {"id": self._signed("raw")})
+
+    def company_graph(self, security_id: int) -> list:
+        """Company OHLC history [{businessDate, openPrice, ...}] (chart tab)."""
+        return self.post_json(f"/api/nots/market/graphdata/{security_id}",  # type: ignore[return-value]
+                              {"id": self._signed("raw")})
+
+    def company_graph_intraday(self, security_id: int) -> list:
+        """Company intraday LTP (Charts Company tab, 1D range)."""
+        return self.post_json(f"/api/nots/market/graphdata/daily/{security_id}",  # type: ignore[return-value]
+                              {"id": self._signed("raw")})

nepsepy-1.0.0/nepsepy/_market.py

@@ -0,0 +1,101 @@
+"""Market data, indices, top tens and depth. endpoints (mixin for NepseClient)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+class MarketMixin:
+    # -- market status / summary / ticker --------------------------------
+    def market_status(self) -> dict:
+        """Market open state (homepage + every page reads this)."""
+        return self.get_json("/api/nots/nepse-data/market-open")  # type: ignore[return-value]
+
+    def market_summary(self) -> list:
+        """Homepage summary tiles [{detail, value}]."""
+        return self.get_json("/api/nots/market-summary/")  # type: ignore[return-value]
+
+    def market_summary_history(self) -> list:
+        """Daily history [{businessDate, totalTurnover, ...}]."""
+        return self.get_json("/api/nots/market-summary-history")  # type: ignore[return-value]
+
+    def ticker(self, index_id: int = 58) -> list:
+        """Live ticker strip [{symbol, ltp, ...}] (every page load)."""
+        return self.get_json(f"/api/nots/securityDailyTradeStat/{index_id}")  # type: ignore[return-value]
+
+    def live_market(self) -> list:
+        """Full live snapshot (356 rows: OHLC, volumes, per-security indexId).
+
+        The Live Market *page* redirects to `/` while the market is closed,
+        but the API itself answers 200 regardless — verified live.
+        """
+        return self.get_json("/api/nots/lives-market")  # type: ignore[return-value]
+
+    def nepse_indices(self) -> list:
+        """Index snapshot [{index, close, change, perChange, ...}]."""
+        return self.get_json("/api/nots/nepse-index")  # type: ignore[return-value]
+
+    def sub_indices(self) -> list:
+        """Sub-index snapshot [{id, index, change, currentValue}]."""
+        return self.get_json("/api/nots")  # type: ignore[return-value]
+
+    def indices_list(self) -> list:
+        """Index directory [{id, indexCode, indexName, ...}]."""
+        return self.get_json("/api/nots/index")  # type: ignore[return-value]
+
+    def index_history(self, index_id: int = 58, page: int = 1,
+                      size: int = 20) -> dict:
+        """Datewise index OHLC (Indices page; page is 1-based like the UI)."""
+        path = f"/api/nots/index/history/{index_id}?&size={size}"
+        if page > 1:
+            path = f"/api/nots/index/history/{index_id}?page={page - 1}&size={size}"
+        return self.get_json(path)  # type: ignore[return-value]
+
+    def sector_summary(self, business_date: Optional[str] = None) -> list:
+        """Sector turnover (Sector Summary page; date 'yyyy-MM-dd')."""
+        path = "/api/nots/sectorwise"
+        if business_date:
+            path += f"?businessDate={business_date}"
+        return self.get_json(path)  # type: ignore[return-value]
+
+    # -- top tens ------------------------------------------------------------
+    def _top_ten(self, kind: str, full: bool = False) -> list:
+        return self.get_json(f"/api/nots/top-ten/{kind}?all={str(full).lower()}")  # type: ignore[return-value]
+
+    def top_gainers(self, full: bool = False) -> list:
+        """Top gainers [{symbol, ltp, pointChange, percentageChange, ...}]."""
+        return self._top_ten("top-gainer", full)
+
+    def top_losers(self, full: bool = False) -> list:
+        """Top losers (same shape as gainers)."""
+        return self._top_ten("top-loser", full)
+
+    def top_turnover(self, full: bool = False) -> list:
+        """Top by turnover."""
+        return self._top_ten("turnover", full)
+
+    def top_traded_shares(self, full: bool = False) -> list:
+        """Top by shares traded."""
+        return self._top_ten("trade", full)
+
+    def top_transactions(self, full: bool = False) -> list:
+        """Top by transaction count."""
+        return self._top_ten("transaction", full)
+
+    def top_active(self, full: bool = False) -> list:
+        """Most active scrips (trade quantity)."""
+        return self._top_ten("trade-qty", full)
+
+    # -- supply / demand / depth ----------------------------------------------
+    def supply_demand(self, full: bool = False) -> dict:
+        """Top supply/demand {supplyList, demandList}."""
+        return self.get_json(  # type: ignore[return-value]
+            f"/api/nots/nepse-data/supplydemand?all={str(full).lower()}")
+
+    def market_depth(self, security_id: int) -> dict:
+        """Order book {totalBuyQty, totalSellQty, marketDepth{...}}."""
+        return self.get_json(f"/api/nots/nepse-data/marketdepth/{security_id}")  # type: ignore[return-value]
+
+    def odd_lot_depth(self, security_id: int) -> dict:
+        """Odd-lot order book (same shape as market_depth)."""
+        return self.get_json(f"/api/nots/nepse-data/marketdepth-ol/{security_id}")  # type: ignore[return-value]