nselite 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
nselite/__init__.py ADDED
@@ -0,0 +1,21 @@
1
+ """nselite: lean, async-first client for NSE India reports and market data."""
2
+
3
+ from ._dates import split_range, weekdays
4
+ from .client import NSE, SyncNSE
5
+ from .errors import NotAvailable, NSEError, RateLimited, SessionExpired
6
+ from .reports import DailyReports, ReportFile, ReportKey
7
+
8
+ __all__ = [
9
+ "NSE",
10
+ "DailyReports",
11
+ "NSEError",
12
+ "NotAvailable",
13
+ "RateLimited",
14
+ "ReportFile",
15
+ "ReportKey",
16
+ "SessionExpired",
17
+ "SyncNSE",
18
+ "split_range",
19
+ "weekdays",
20
+ ]
21
+ __version__ = "0.1.0"
nselite/_dates.py ADDED
@@ -0,0 +1,47 @@
1
+ """Date helpers shared by all modules."""
2
+
3
+ from collections.abc import Iterator
4
+ from datetime import date, datetime, timedelta
5
+
6
+ NSE_DATE_FORMATS = ("%d-%b-%Y %H:%M:%S", "%d-%b-%Y %H:%M", "%d-%b-%Y")
7
+
8
+
9
+ def split_range(start: date, end: date, max_days: int = 365) -> list[tuple[date, date]]:
10
+ """Split ``start``..``end`` (inclusive) into consecutive chunks of at most ``max_days``.
11
+
12
+ NSE's historical endpoints reject long ranges, so callers fetch each chunk concurrently.
13
+ """
14
+ if start > end:
15
+ raise ValueError(f"start {start} is after end {end}")
16
+ if max_days < 1:
17
+ raise ValueError("max_days must be at least 1")
18
+
19
+ chunks: list[tuple[date, date]] = []
20
+ step = timedelta(days=max_days - 1)
21
+ cur = start
22
+ while cur <= end:
23
+ chunk_end = min(cur + step, end)
24
+ chunks.append((cur, chunk_end))
25
+ cur = chunk_end + timedelta(days=1)
26
+ return chunks
27
+
28
+
29
+ def weekdays(start: date, end: date) -> Iterator[date]:
30
+ """Yield Monday-Friday dates in ``start``..``end``. Holidays are not excluded."""
31
+ cur = start
32
+ one = timedelta(days=1)
33
+ while cur <= end:
34
+ if cur.weekday() < 5:
35
+ yield cur
36
+ cur += one
37
+
38
+
39
+ def parse_nse_date(text: str) -> date:
40
+ """Parse NSE's ``19-Nov-2026`` style dates (with or without a time part)."""
41
+ text = text.strip()
42
+ for fmt in NSE_DATE_FORMATS:
43
+ try:
44
+ return datetime.strptime(text, fmt).date()
45
+ except ValueError:
46
+ continue
47
+ raise ValueError(f"unrecognised NSE date: {text!r}")
nselite/_files.py ADDED
@@ -0,0 +1,45 @@
1
+ """Archive unpacking. Runs in a worker thread so large files never block the event loop."""
2
+
3
+ import asyncio
4
+ import gzip
5
+ import shutil
6
+ from datetime import date, datetime
7
+ from pathlib import Path
8
+ from zipfile import ZipFile
9
+
10
+
11
+ def as_date(d: date) -> date:
12
+ """Accept ``date`` or ``datetime`` (the fork took datetimes) and return a plain ``date``."""
13
+ return d.date() if isinstance(d, datetime) else d
14
+
15
+
16
+ def unpacked_name(archive_name: str) -> str:
17
+ """``x.csv.zip`` -> ``x.csv``; ``x.csv.gz`` -> ``x.csv``."""
18
+ return archive_name.removesuffix(".zip").removesuffix(".gz")
19
+
20
+
21
+ def _unpack(archive: Path, members: list[str] | None) -> Path:
22
+ folder = archive.parent
23
+ if archive.suffix.lower() == ".zip":
24
+ with ZipFile(archive) as zf:
25
+ if members:
26
+ zf.extractall(folder, members=members)
27
+ out = folder / members[-1]
28
+ else:
29
+ out = Path(zf.extract(zf.namelist()[0], folder))
30
+ elif archive.suffix.lower() == ".gz":
31
+ out = folder / archive.stem
32
+ with gzip.open(archive, "rb") as src, out.open("wb") as dst:
33
+ shutil.copyfileobj(src, dst, 1 << 20)
34
+ else:
35
+ raise ValueError(f"not a .zip or .gz file: {archive.name}")
36
+ archive.unlink()
37
+ return out
38
+
39
+
40
+ async def unpack(archive: Path, members: list[str] | None = None) -> Path:
41
+ """Extract ``archive`` next to itself, delete it, and return the extracted file.
42
+
43
+ For zips, extracts ``members`` (returning the last) or else the first member.
44
+ """
45
+ return await asyncio.to_thread(_unpack, archive, members)
nselite/_hosts.py ADDED
@@ -0,0 +1,7 @@
1
+ """NSE hosts. Override with environment variables if NSE moves domains again."""
2
+
3
+ import os
4
+
5
+ NSE_HOST = os.environ.get("NSE_HOST", "https://www.nseindia.in").rstrip("/")
6
+ ARCHIVES_HOST = os.environ.get("NSE_ARCHIVES_HOST", "https://nsearchives.nseindia.in").rstrip("/")
7
+ API_BASE = f"{NSE_HOST}/api"
nselite/_http.py ADDED
@@ -0,0 +1,234 @@
1
+ """Shared HTTP layer: one AsyncClient per NSE instance, persisted cookies, throttle and retries.
2
+
3
+ Every request in nselite goes through :class:`Http`. Never create another client.
4
+ """
5
+
6
+ import asyncio
7
+ import random
8
+ import time
9
+ from pathlib import Path
10
+ from typing import Any
11
+
12
+ import httpx
13
+ import orjson
14
+
15
+ from ._hosts import NSE_HOST
16
+ from .errors import NetworkError, NotAvailable, RateLimited, SessionExpired
17
+
18
+ USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; rv:109.0) Gecko/20100101 Firefox/118.0"
19
+ DEFAULT_HEADERS = {
20
+ "User-Agent": USER_AGENT,
21
+ "Accept": "*/*",
22
+ "Accept-Language": "en-US,en;q=0.5",
23
+ "Accept-Encoding": "gzip, deflate",
24
+ "Referer": f"{NSE_HOST}/get-quotes/equity?symbol=HDFCBANK",
25
+ }
26
+ # Page that reliably sets the session cookies NSE's API expects.
27
+ WARM_URL = f"{NSE_HOST}/option-chain"
28
+ CHUNK = 1 << 20 # 1 MiB
29
+ RETRY_STATUS = frozenset({429, 500, 502, 503, 504})
30
+ RETRY_EXC = (httpx.TimeoutException, httpx.RemoteProtocolError, httpx.ConnectError)
31
+
32
+ type Params = dict[str, str | int] | None
33
+
34
+
35
+ def default_cookie_path() -> Path:
36
+ """``$XDG_CACHE_HOME/nselite/cookies.json`` (``~/.cache`` when unset)."""
37
+ import os
38
+
39
+ base = Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache")
40
+ return base / "nselite" / "cookies.json"
41
+
42
+
43
+ class TokenBucket:
44
+ """Async token bucket: at most ``rate`` requests per second, bursts up to ``burst``."""
45
+
46
+ def __init__(self, rate: float, burst: int | None = None) -> None:
47
+ if rate <= 0:
48
+ raise ValueError("rate must be positive")
49
+ self.rate = rate
50
+ self.capacity = float(burst if burst is not None else max(1, int(rate)))
51
+ self._tokens = self.capacity
52
+ self._last = time.monotonic()
53
+ self._lock = asyncio.Lock()
54
+
55
+ async def acquire(self) -> None:
56
+ async with self._lock:
57
+ while True:
58
+ now = time.monotonic()
59
+ self._tokens = min(self.capacity, self._tokens + (now - self._last) * self.rate)
60
+ self._last = now
61
+ if self._tokens >= 1:
62
+ self._tokens -= 1
63
+ return
64
+ await asyncio.sleep((1 - self._tokens) / self.rate)
65
+
66
+
67
+ class Http:
68
+ """Throttled, retrying HTTP/2 client with NSE session cookies.
69
+
70
+ :param rps: requests per second across all concurrent tasks (NSE blocks aggressive clients).
71
+ :param timeout: per-request timeout in seconds.
72
+ :param retries: extra attempts on timeouts, dropped connections, 429 and 5xx.
73
+ :param http2: use HTTP/2 multiplexing (falls back to HTTP/1.1 if the server refuses).
74
+ :param cookie_path: where session cookies persist between runs; ``None`` for the default.
75
+ :param cookie_ttl: seconds before saved cookies are re-warmed proactively.
76
+ """
77
+
78
+ def __init__(
79
+ self,
80
+ *,
81
+ rps: float = 3.0,
82
+ timeout: float = 15.0,
83
+ retries: int = 3,
84
+ http2: bool = True,
85
+ cookie_path: Path | None = None,
86
+ cookie_ttl: float = 3600.0,
87
+ transport: httpx.AsyncBaseTransport | None = None,
88
+ ) -> None:
89
+ self.retries = retries
90
+ self.cookie_path = cookie_path or default_cookie_path()
91
+ self.cookie_ttl = cookie_ttl
92
+ self._bucket = TokenBucket(rps)
93
+ self._client = httpx.AsyncClient(
94
+ headers=DEFAULT_HEADERS,
95
+ http2=http2,
96
+ timeout=timeout,
97
+ follow_redirects=True,
98
+ transport=transport,
99
+ )
100
+ self._warm_lock = asyncio.Lock()
101
+ self._warmed = False
102
+
103
+ # ---------------------------------------------------------------- lifecycle
104
+
105
+ async def aclose(self) -> None:
106
+ await self._client.aclose()
107
+
108
+ # ---------------------------------------------------------------- cookies
109
+
110
+ def _load_cookies(self) -> bool:
111
+ try:
112
+ saved = orjson.loads(self.cookie_path.read_bytes())
113
+ except (FileNotFoundError, orjson.JSONDecodeError):
114
+ return False
115
+ if time.time() - saved.get("saved_at", 0) > self.cookie_ttl or not saved.get("cookies"):
116
+ return False
117
+ self._client.cookies.update(saved["cookies"])
118
+ return True
119
+
120
+ def _save_cookies(self) -> None:
121
+ cookies = {c.name: c.value for c in self._client.cookies.jar if c.value is not None}
122
+ self.cookie_path.parent.mkdir(parents=True, exist_ok=True)
123
+ tmp = self.cookie_path.with_suffix(".tmp")
124
+ tmp.write_bytes(orjson.dumps({"saved_at": time.time(), "cookies": cookies}))
125
+ tmp.replace(self.cookie_path)
126
+
127
+ async def _warm(self, *, force: bool = False) -> None:
128
+ """Make sure the client holds valid NSE cookies. Safe to call from many tasks at once."""
129
+ async with self._warm_lock:
130
+ if self._warmed and not force:
131
+ return
132
+ if not force and self._load_cookies():
133
+ self._warmed = True
134
+ return
135
+ self._client.cookies.clear()
136
+ await self._bucket.acquire()
137
+ try:
138
+ r = await self._client.get(WARM_URL)
139
+ except RETRY_EXC as e:
140
+ raise NetworkError(f"could not reach {WARM_URL}: {e!r}") from e
141
+ if r.status_code >= 400:
142
+ raise SessionExpired(f"could not warm NSE session: {r.status_code} on {WARM_URL}")
143
+ self._save_cookies()
144
+ self._warmed = True
145
+
146
+ def forget_cookies(self) -> None:
147
+ """Delete the saved cookies; the next request warms a fresh session."""
148
+ self.cookie_path.unlink(missing_ok=True)
149
+ self._client.cookies.clear()
150
+ self._warmed = False
151
+
152
+ # ---------------------------------------------------------------- requests
153
+
154
+ @staticmethod
155
+ async def _backoff(attempt: int) -> None:
156
+ await asyncio.sleep(0.5 * 2**attempt + random.uniform(0, 0.25))
157
+
158
+ async def _request(self, url: str, params: Params, *, stream: bool) -> httpx.Response:
159
+ """Send a GET with throttle, retries and one cookie refresh. Raises on any non-2xx."""
160
+ await self._warm()
161
+ attempt = 0
162
+ refreshed = False
163
+ while True:
164
+ await self._bucket.acquire()
165
+ req = self._client.build_request("GET", url, params=params)
166
+ try:
167
+ r = await self._client.send(req, stream=stream)
168
+ except RETRY_EXC as e:
169
+ if attempt >= self.retries:
170
+ raise NetworkError(
171
+ f"GET {url} failed after {attempt + 1} attempts: {e!r}"
172
+ ) from e
173
+ await self._backoff(attempt)
174
+ attempt += 1
175
+ continue
176
+
177
+ status = r.status_code
178
+ if 200 <= status < 300:
179
+ return r
180
+ if stream:
181
+ await r.aclose()
182
+
183
+ if status in (401, 403):
184
+ if refreshed:
185
+ raise SessionExpired(f"GET {url}: {status} even after refreshing cookies")
186
+ refreshed = True
187
+ await self._warm(force=True)
188
+ continue
189
+ if status == 404:
190
+ raise NotAvailable(f"GET {url}: 404 Not Found")
191
+ if status in RETRY_STATUS and attempt < self.retries:
192
+ await self._backoff(attempt)
193
+ attempt += 1
194
+ continue
195
+ if status == 429:
196
+ raise RateLimited(f"GET {url}: still 429 after {attempt + 1} attempts")
197
+ raise NetworkError(f"GET {url}: {status} {r.reason_phrase}")
198
+
199
+ async def get(self, url: str, params: Params = None) -> httpx.Response:
200
+ """GET ``url`` and return the fully read response."""
201
+ return await self._request(url, params, stream=False)
202
+
203
+ async def get_json(self, url: str, params: Params = None) -> Any:
204
+ """GET ``url`` and parse JSON with orjson. Raises :class:`NotAvailable` on empty/HTML."""
205
+ r = await self.get(url, params)
206
+ if not r.content or "text/html" in r.headers.get("content-type", ""):
207
+ raise NotAvailable(f"GET {url}: no JSON in response")
208
+ return orjson.loads(r.content)
209
+
210
+ async def download(self, url: str, dest: Path, *, overwrite: bool = False) -> Path:
211
+ """Stream ``url`` to ``dest`` in 1 MiB chunks; skip if ``dest`` already exists.
212
+
213
+ Writes to ``dest.part`` first and renames on success, so a crash never leaves a
214
+ truncated file under the final name. Local file I/O stays synchronous on purpose:
215
+ a stat or a 1 MiB write is far cheaper than a thread hop, and the network dominates.
216
+ """
217
+ if dest.exists() and not overwrite: # noqa: ASYNC240
218
+ return dest
219
+ dest.parent.mkdir(parents=True, exist_ok=True)
220
+ part = dest.with_name(dest.name + ".part")
221
+ r = await self._request(url, None, stream=True)
222
+ try:
223
+ if "text/html" in r.headers.get("content-type", ""):
224
+ raise NotAvailable(f"GET {url}: HTML page instead of a file (not published yet?)")
225
+ with part.open("wb") as f:
226
+ async for chunk in r.aiter_bytes(CHUNK):
227
+ f.write(chunk)
228
+ except BaseException:
229
+ part.unlink(missing_ok=True)
230
+ raise
231
+ finally:
232
+ await r.aclose()
233
+ part.replace(dest)
234
+ return dest
nselite/archives.py ADDED
@@ -0,0 +1,67 @@
1
+ """End-of-day archive files our pipelines read every day (bhavcopies, MII file, price bands)."""
2
+
3
+ from datetime import date
4
+ from pathlib import Path
5
+
6
+ from ._files import as_date, unpack, unpacked_name
7
+ from ._hosts import ARCHIVES_HOST
8
+ from .reports import SPECS, ReportKey, ReportsMixin
9
+
10
+ # NSE switched the CM bhavcopy to the UDiFF format on this date.
11
+ UDIFF_SWITCH_DATE = date(2024, 7, 8)
12
+
13
+
14
+ class ArchivesMixin(ReportsMixin):
15
+ """Archive downloads mixed into :class:`nselite.NSE`. All take the trading date."""
16
+
17
+ async def _download_unpacked(self, url: str, folder: Path, overwrite: bool) -> Path:
18
+ name = url.rsplit("/", 1)[-1]
19
+ target = folder / unpacked_name(name)
20
+ if target.exists() and not overwrite:
21
+ return target
22
+ archive = await self._http.download(url, folder / name, overwrite=True)
23
+ return await unpack(archive)
24
+
25
+ async def equity_bhavcopy(self, day: date, folder: Path, *, overwrite: bool = False) -> Path:
26
+ """CM bhavcopy CSV (extracted); pre-UDiFF ``cmDDMONYYYYbhav.csv`` before 2024-07-08."""
27
+ day = as_date(day)
28
+ if day < UDIFF_SWITCH_DATE:
29
+ stamp = day.strftime("%d%b%Y").upper()
30
+ url = (
31
+ f"{ARCHIVES_HOST}/content/historical/EQUITIES/{day.year}/{stamp[2:5]}"
32
+ f"/cm{stamp}bhav.csv.zip"
33
+ )
34
+ else:
35
+ url = SPECS[ReportKey.CM_UDIFF_BHAVCOPY].url(day)
36
+ return await self._download_unpacked(url, folder, overwrite)
37
+
38
+ async def delivery_bhavcopy(self, day: date, folder: Path, *, overwrite: bool = False) -> Path:
39
+ """Full bhavcopy with delivery quantities (``sec_bhavdata_full_DDMMYYYY.csv``)."""
40
+ return await self.download_report(
41
+ ReportKey.CM_BHAVDATA_FULL, folder, day, overwrite=overwrite
42
+ )
43
+
44
+ async def indices_bhavcopy(self, day: date, folder: Path, *, overwrite: bool = False) -> Path:
45
+ """Closing values of all indices (``ind_close_all_DDMMYYYY.csv``)."""
46
+ return await self.download_report(
47
+ ReportKey.INDEX_SNAPSHOT, folder, day, overwrite=overwrite
48
+ )
49
+
50
+ async def priceband_report(self, day: date, folder: Path, *, overwrite: bool = False) -> Path:
51
+ """Price band of every security (``sec_list_DDMMYYYY.csv``)."""
52
+ return await self.download_report(
53
+ ReportKey.CM_PRICEBAND_COMPLETE, folder, day, overwrite=overwrite
54
+ )
55
+
56
+ async def pr_bhavcopy(self, day: date, folder: Path, *, overwrite: bool = False) -> Path:
57
+ """PR bhavcopy zip (kept zipped: it bundles many reports plus a Readme)."""
58
+ return await self.download_report(
59
+ ReportKey.CM_BHAVCOPY_PR, folder, day, overwrite=overwrite
60
+ )
61
+
62
+ async def cm_mii_security_report(
63
+ self, day: date, folder: Path, *, overwrite: bool = False
64
+ ) -> Path:
65
+ """CM MII security master CSV (extracted from ``.csv.gz``)."""
66
+ url = SPECS[ReportKey.CM_SECURITY].url(day)
67
+ return await self._download_unpacked(url, folder, overwrite)
nselite/client.py ADDED
@@ -0,0 +1,95 @@
1
+ """Public entry points: async :class:`NSE` and blocking :class:`SyncNSE`."""
2
+
3
+ import asyncio
4
+ import inspect
5
+ from pathlib import Path
6
+ from types import TracebackType
7
+ from typing import Any, Self
8
+
9
+ import httpx
10
+
11
+ from ._http import Http
12
+ from .archives import ArchivesMixin
13
+ from .corporate import CorporateMixin
14
+ from .filings import FilingsMixin
15
+ from .market import MarketMixin
16
+
17
+
18
+ class NSE(ArchivesMixin, CorporateMixin, FilingsMixin, MarketMixin):
19
+ """Async NSE client. Use one instance per process and share it across tasks.
20
+
21
+ >>> async with NSE() as nse:
22
+ ... path = await nse.download_report(ReportKey.CM_UDIFF_BHAVCOPY, Path("data"))
23
+ """
24
+
25
+ def __init__(
26
+ self,
27
+ *,
28
+ rps: float = 3.0,
29
+ timeout: float = 15.0,
30
+ retries: int = 3,
31
+ http2: bool = True,
32
+ cookie_path: Path | None = None,
33
+ transport: httpx.AsyncBaseTransport | None = None,
34
+ ) -> None:
35
+ self._http = Http(
36
+ rps=rps,
37
+ timeout=timeout,
38
+ retries=retries,
39
+ http2=http2,
40
+ cookie_path=cookie_path,
41
+ transport=transport,
42
+ )
43
+
44
+ async def __aenter__(self) -> Self:
45
+ return self
46
+
47
+ async def __aexit__(
48
+ self,
49
+ exc_type: type[BaseException] | None,
50
+ exc: BaseException | None,
51
+ tb: TracebackType | None,
52
+ ) -> None:
53
+ await self.aclose()
54
+
55
+ async def aclose(self) -> None:
56
+ await self._http.aclose()
57
+
58
+ def forget_cookies(self) -> None:
59
+ """Delete saved cookies; the next call starts a fresh NSE session."""
60
+ self._http.forget_cookies()
61
+
62
+
63
+ class SyncNSE:
64
+ """Blocking wrapper with the same methods as :class:`NSE`, for existing scripts.
65
+
66
+ >>> with SyncNSE() as nse:
67
+ ... path = nse.download_report(ReportKey.CM_UDIFF_BHAVCOPY, Path("data"))
68
+
69
+ All calls run on one private event loop, so the HTTP/2 connection is reused between calls.
70
+ """
71
+
72
+ def __init__(self, **kwargs: Any) -> None:
73
+ self._runner = asyncio.Runner()
74
+ self._nse = NSE(**kwargs)
75
+
76
+ def __getattr__(self, name: str) -> Any:
77
+ attr = getattr(self._nse, name)
78
+ if inspect.iscoroutinefunction(attr):
79
+
80
+ def call(*args: Any, **kwargs: Any) -> Any:
81
+ return self._runner.run(attr(*args, **kwargs))
82
+
83
+ call.__doc__ = attr.__doc__
84
+ return call
85
+ return attr
86
+
87
+ def close(self) -> None:
88
+ self._runner.run(self._nse.aclose())
89
+ self._runner.close()
90
+
91
+ def __enter__(self) -> Self:
92
+ return self
93
+
94
+ def __exit__(self, *_: object) -> None:
95
+ self.close()