Metadata-Version: 2.4
Name: nepsepy
Version: 1.0.2
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.svg?logo=pypi&logoColor=white)](https://pypi.org/project/nepsepy/)
[![Python](https://img.shields.io/pypi/pyversions/nepsepy.svg?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 synchronous and async APIs 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`.

## Async use

For async applications such as FastAPI, use `AsyncNepseClient`. It has the
same endpoint methods and automatically manages the temporary NEPSE token.

```python
from nepsepy import AsyncNepseClient

async def load_market():
    async with AsyncNepseClient() as client:
        status = await client.market_status()
        gainers = await client.top_gainers()
        return status, gainers
```

## 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).
