Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

4mritGiri/NepseClient

Open more actions menu

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

37 Commits
37 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

NEPSE Client

Tests Publish Documentation PyPI version Python versions License: MIT Code style: black

A comprehensive, production-ready Python client library for interacting with the Nepal Stock Exchange (NEPSE) API. Built with modern Python best practices, full type hints, and both synchronous and asynchronous support.

🌟 Features

  • ✨ Dual API Support - Both synchronous and asynchronous clients for flexible integration
  • πŸ”’ Smart Token Management - Automatic authentication with token refresh and caching
  • πŸ“Š Complete API Coverage - Access all NEPSE endpoints: market data, company info, floor sheets, news, and more
  • πŸ›‘οΈ Robust Error Handling - Comprehensive exception hierarchy with automatic retries
  • πŸ“ Full Type Hints - Complete type annotations for excellent IDE support and type safety
  • πŸ”„ Automatic Retry Logic - Built-in exponential backoff for network failures
  • πŸ“ˆ Progress Tracking - Optional progress bars for long-running operations
  • πŸ§ͺ Well Tested - Comprehensive test suite with >80% coverage
  • πŸš€ Production Ready - Battle-tested, secure, and optimized for performance
  • πŸ“š Excellent Documentation - Detailed docs, examples, and API reference

πŸ“¦ Installation

From PyPI (Recommended)

pip install nepse-client

Using uv (Fast)

uv pip install nepse-client

From Source

git clone https://github.com/4mritgiri/NepseClient.git
cd nepse-client
pip install -e .

Development Installation

# Clone and install with dev dependencies
git clone https://github.com/4mritgiri/NepseClient.git
cd nepse-client
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

πŸš€ Quick Start

Synchronous Usage

from nepse_client import NepseClient

# Initialize client
client = NepseClient()

# Optional: Disable TLS verification (for testing only)
client.setTLSVerification(False)

# Get market status
market_status = client.getMarketStatus()
print(f"Market is: {market_status['isOpen']}")

# Get company details
nabil = client.getCompanyDetails('NABIL')
print(f"NABIL LTP: {nabil['lastTradedPrice']}")

# Get today's top gainers
gainers = client.getTopGainers()
for stock in gainers[:5]:
    print(f"{stock['symbol']}: +{stock['percentageChange']}%")

Asynchronous Usage

import asyncio
from nepse_client import AsyncNepseClient

async def main():
    # Initialize async client
    async with AsyncNepseClient() as client:
        # Optional: Disable TLS verification (for testing only)
        client.setTLSVerification(False)

        # Concurrent requests for better performance
        market_status, summary, gainers = await asyncio.gather(
            client.getMarketStatus(),
            client.getSummary(),
            client.getTopGainers()
        )

        print(f"Market: {market_status['isOpen']}")
        print(f"Turnover: {summary['totalTurnover']}")
        print(f"Top Gainer: {gainers[0]['symbol']}")

# Run async function
asyncio.run(main())

Context Manager Support

# Automatic resource cleanup with context manager
with NepseClient() as client:
    status = client.getMarketStatus()
    companies = client.getCompanyList()
# Client automatically closed

πŸ“– API Documentation

Market Information

# Get market status (open/closed)
status = client.getMarketStatus()

# Get market summary (turnover, trades, etc.)
summary = client.getSummary()

# Get NEPSE index
index = client.getNepseIndex()

# Get sub-indices (sector indices)
sub_indices = client.getNepseSubIndices()

# Get live market data
live_market = client.getLiveMarket()

# Get price volume data
price_volume = client.getPriceVolume()

# Get supply and demand data
supply_demand = client.getSupplyDemand()

Company Information

# Get list of all companies
companies = client.getCompanyList()

# Get security list (non-delisted securities)
securities = client.getSecurityList()

# Get company details by symbol
details = client.getCompanyDetails('NABIL')

# Get company price history
from datetime import date, timedelta
end_date = date.today()
start_date = end_date - timedelta(days=365)

history = client.getCompanyPriceVolumeHistory(
    symbol='NABIL',
    start_date=start_date,
    end_date=end_date
)

# Get daily price graph data
graph = client.getDailyScripPriceGraph('NABIL')

# Get company financial details
financials = client.getCompanyFinancialDetails(company_id='123')

# Get company AGM information
agm = client.getCompanyAGM(company_id='123')

# Get company dividend information
dividend = client.getCompanyDividend(company_id='123')

# Get company market depth
market_depth = client.getCompanyMarketDepth(company_id='123')

Trading Data

# Get complete floor sheet (all trades)
floor_sheet = client.getFloorSheet()

# Get floor sheet with progress bar
floor_sheet = client.getFloorSheet(show_progress=True)

# Get floor sheet for specific company
company_trades = client.getFloorSheetOf(
    symbol='NABIL',
    business_date='2024-01-15'
)

# Get trading average
trading_avg = client.getTradingAverage(
    business_date='2024-01-15',
    nDays=180
)

# Get market depth for symbol
depth = client.getSymbolMarketDepth('NABIL')

Top Performers

# Get top gainers
gainers = client.getTopGainers()

# Get top losers
losers = client.getTopLosers()

# Get top 10 by trade volume
top_trade = client.getTopTenTradeScrips()

# Get top 10 by transaction count
top_transaction = client.getTopTenTransactionScrips()

# Get top 10 by turnover
top_turnover = client.getTopTenTurnoverScrips()

News and Announcements

# Get company news with pagination
news = client.getCompanyNewsList(
    page=1,
    page_size=100,
    is_strip_tags=True  # Remove HTML tags
)

# Get news and alerts
alerts = client.getNewsAndAlertList(
    page=1,
    page_size=100,
    is_strip_tags=True
)

# Get press releases
press_releases = client.getPressRelease()

# Get NEPSE notices
notices = client.getNepseNotice(page=0)

Other Data

# Get holiday list for specific year
holidays = client.getHolidayList(year=2025)

# Get debenture and bond list
debentures = client.getDebentureAndBondList(type='debenture')
bonds = client.getDebentureAndBondList(type='bond')

# Get price volume history for specific date
price_history = client.getPriceVolumeHistory(business_date='2024-01-15')

Advanced Features

Caching and ID Mappings

# Get company ID to symbol mapping (cached)
company_map = client.getCompanyIDKeyMap()

# Get security ID to symbol mapping (cached)
security_map = client.getSecurityIDKeyMap()

# Force update cache
company_map = client.getCompanyIDKeyMap(force_update=True)

# Get sector-wise scrips
sector_scrips = client.getSectorScrips()
# Returns: {'Commercial Banks': ['NABIL', 'SCB', ...], ...}

Custom Configuration

import logging

# Custom logger
logger = logging.getLogger('my_nepse_app')
logger.setLevel(logging.DEBUG)

# Initialize with custom settings
client = NepseClient(
    logger=logger,
    mask_request_data=True,  # Mask sensitive data in logs
    timeout=120.0            # Request timeout in seconds
)

# Disable TLS verification (not recommended for production)
client.setTLSVerification(False)

# Re-enable TLS verification
client.setTLSVerification(True)

πŸ”₯ Advanced Usage Examples

Portfolio Value Calculator

def calculate_portfolio_value(portfolio):
    """
    Calculate total portfolio value.

    Args:
        portfolio: Dict of {symbol: quantity}

    Returns:
        Total value in NPR
    """
    client = NepseClient()
    total = 0

    for symbol, quantity in portfolio.items():
        details = client.getCompanyDetails(symbol)
        price = float(details['lastTradedPrice'])
        value = price * quantity
        total += value
        print(f"{symbol}: {quantity} @ NPR {price} = NPR {value:,.2f}")

    return total

# Example
portfolio = {'NABIL': 100, 'NICA': 50, 'SCB': 75}
total_value = calculate_portfolio_value(portfolio)
print(f"\nTotal Portfolio Value: NPR {total_value:,.2f}")

Async Batch Operations

import asyncio
from nepse_client import AsyncNepseClient

async def fetch_multiple_companies(symbols):
    """Fetch details for multiple companies concurrently."""
    async with AsyncNepseClient() as client:
        # Create tasks for all symbols
        tasks = [client.getCompanyDetails(symbol) for symbol in symbols]

        # Fetch all concurrently
        results = await asyncio.gather(*tasks, return_exceptions=True)

        # Process results
        for symbol, result in zip(symbols, results):
            if isinstance(result, Exception):
                print(f"{symbol}: Error - {result}")
            else:
                ltp = result['lastTradedPrice']
                print(f"{symbol}: NPR {ltp}")

# Run
symbols = ['NABIL', 'NICA', 'SCB', 'EBL', 'ADBL']
asyncio.run(fetch_multiple_companies(symbols))

Real-time Market Monitoring

import asyncio
from nepse_client import AsyncNepseClient

async def monitor_market(interval=60):
    """Monitor market status continuously."""
    async with AsyncNepseClient() as client:
        while True:
            try:
                status = await client.getMarketStatus()
                summary = await client.getSummary()

                print(f"[{status['asOf']}] Market: {status['isOpen']}")
                print(f"Turnover: NPR {summary['totalTurnover']:,.2f}")

                await asyncio.sleep(interval)
            except KeyboardInterrupt:
                break
            except Exception as e:
                print(f"Error: {e}")
                await asyncio.sleep(interval)

asyncio.run(monitor_market())

πŸ› Error Handling

The library provides a comprehensive exception hierarchy:

from nepse_client import (
    NepseError,                  # Base exception
    NepseClientError,            # 400 errors
    NepseAuthenticationError,    # 401 errors
    NepseBadGatewayError,        # 502 errors
    NepseServerError,            # 5xx errors
    NepseNetworkError,           # Network/connection errors
    NepseValidationError,        # Input validation errors
    NepseRateLimitError,         # Rate limit exceeded
    NepseDataNotFoundError,      # Data not found
    NepseTimeoutError,           # Request timeout
)

# Example error handling
try:
    data = client.getCompanyDetails('INVALID')
except NepseAuthenticationError:
    print("Authentication failed - token will auto-refresh")
except NepseDataNotFoundError:
    print("Company symbol not found")
except NepseRateLimitError as e:
    print(f"Rate limited - retry after {e.retry_after}s")
except NepseServerError as e:
    print(f"Server error: {e}")
except NepseError as e:
    print(f"NEPSE error: {e}")

πŸ§ͺ Testing

# Install test dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run with coverage
pytest --cov=nepse_client --cov-report=html

# Run specific test file
pytest tests/test_sync_client.py -v

# Run only unit tests
pytest -m unit

# Run only integration tests
pytest -m integration

πŸ“Š Code Quality

This project maintains high code quality standards:

# Format code
black nepse_client tests examples
isort nepse_client tests examples

# Lint code
flake8 nepse_client tests --max-line-length=100

# Type check
mypy nepse_client --ignore-missing-imports

# Security check
bandit -r nepse_client

# Run all pre-commit hooks
pre-commit run --all-files

πŸ—οΈ Project Structure

nepse-client/
β”œβ”€β”€ nepse_client/            # Main package
β”‚   β”œβ”€β”€ __init__.py          # Package exports
β”‚   β”œβ”€β”€ client.py            # Base client
β”‚   β”œβ”€β”€ sync_client.py       # Sync implementation
β”‚   β”œβ”€β”€ async_client.py      # Async implementation
β”‚   β”œβ”€β”€ token_manager.py     # Token management
β”‚   β”œβ”€β”€ dummy_id_manager.py  # Dummy ID management
β”‚   β”œβ”€β”€ exceptions.py        # Custom exceptions
β”‚   β”œβ”€β”€ py.typed             # Type hint marker
β”‚   └── data/                # Configuration files
β”œβ”€β”€ tests/                   # Test suite
β”œβ”€β”€ examples/                # Usage examples
β”œβ”€β”€ docs/                    # Documentation
β”œβ”€β”€ .github/                 # GitHub Actions
β”‚   β”œβ”€β”€ workflows/           # CI/CD pipelines
β”‚   └── ISSUE_TEMPLATE/      # Issue templates
β”œβ”€β”€ pyproject.toml           # Project config
└── README.md                # This file

🀝 Contributing

We welcome contributions! Please follow these guidelines:

Getting Started

  1. Fork the repository
  2. Clone your fork: git clone https://github.com/yourusername/nepse-client.git
  3. Create a branch: git checkout -b feature/amazing-feature
  4. Install dev dependencies: pip install -e ".[dev]"
  5. Install pre-commit: pre-commit install

Making Changes

  1. Make your changes
  2. Add tests for new functionality
  3. Run tests: pytest
  4. Run code quality checks: pre-commit run --all-files
  5. Commit: git commit -m 'Add amazing feature'
  6. Push: git push origin feature/amazing-feature
  7. Create a Pull Request

Code Standards

  • Follow PEP 8 style guide
  • Use Black for formatting (line length: 100)
  • Add type hints to all functions
  • Write docstrings (Google style)
  • Maintain test coverage above 80%
  • Update documentation for new features

Pull Request Checklist

  • Tests pass locally
  • Code formatted with Black and isort
  • Type hints added
  • Documentation updated
  • CHANGELOG.md updated
  • No linting errors
  • Test coverage maintained

See CONTRIBUTING.md for detailed guidelines.

πŸ“ Development

Setup Development Environment

# Clone repository
git clone https://github.com/4mritgiri/NepseClient.git
cd nepse-client

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

# Verify installation
pytest --version
black --version

Running Tests

# Run all tests
pytest

# Run with coverage report
pytest --cov=nepse_client --cov-report=term-missing

# Run specific test
pytest tests/test_sync_client.py::test_get_market_status

# Run in watch mode (requires pytest-watch)
ptw

Building Documentation

# Install documentation dependencies
pip install sphinx sphinx-rtd-theme

# Build HTML docs
cd docs
make html

# Open in browser
open _build/html/index.html  # macOS
xdg-open _build/html/index.html  # Linux

πŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

πŸ™ Acknowledgments

  • Nepal Stock Exchange for providing the API
  • All contributors who have helped improve this library
  • The Python community for excellent tools and libraries

πŸ‘¨β€πŸ’» Author

Amrit Giri

πŸ”— Links

πŸ“ˆ Project Stats

GitHub stars GitHub forks GitHub watchers GitHub issues GitHub pull requests

πŸ’– Support

If you find this library helpful, please consider:

  • ⭐ Starring the repository
  • πŸ› Reporting bugs and issues
  • πŸ’‘ Suggesting new features
  • 🀝 Contributing code improvements
  • πŸ“’ Sharing with others

πŸ—ΊοΈ Roadmap

  • WebSocket support for real-time data
  • Data export utilities (CSV, Excel, JSON)
  • Advanced filtering and sorting
  • Rate limiting with automatic backoff
  • Caching layer for repeated requests
  • CLI tool for quick queries
  • Django/Flask integration examples
  • Interactive Jupyter notebook examples

❓ FAQ

Q: Is this library official?
A: No, this is an unofficial client library for the NEPSE API.

Q: Do I need an API key?
A: No, the NEPSE API doesn't require authentication keys. The client handles token management automatically.

Q: Can I use this in production?
A: Yes! The library is production-ready with comprehensive error handling, retries, and logging.

Q: Which Python versions are supported?
A: Python 3.8 and above are supported.

Q: How do I report a bug?
A: Please open an issue on GitHub Issues with details and a minimal reproduction example.

Q: Can I contribute?
A: Absolutely! Contributions are welcome. Please read CONTRIBUTING.md first.


Made with ❀️ for the Nepali Tech Community

If this project helps you, please consider giving it a ⭐!

About

A comprehensive Python client for Nepal Stock Exchange (NEPSE) API'

Topics

Resources

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Morty Proxy This is a proxified and sanitized view of the page, visit original site.