Utilities

This page documents utility functions and helper classes.

Helper Functions

mask_sensitive_data

nepse_client.client.mask_sensitive_data(data, keys=('token', 'password', 'Authorization'))[source]

Mask sensitive fields in data for safe logging.

Parameters:

data (dict[str, Any]) – Dictionary containing potentially sensitive data
keys (tuple) – Tuple of keys to mask

Return type:

dict[str, Any]

Returns:

Dictionary with masked sensitive values

Masks sensitive fields in data dictionaries for safe logging.

Example:

from nepse_client.client import mask_sensitive_data

data = {
   'token': 'secret_token_12345',
   'password': 'my_password',
   'username': 'user123'
}

masked = mask_sensitive_data(data)
# {'token': '***MASKED***', 'password': '***MASKED***', 'username': 'user123'}

safe_serialize

nepse_client.client.safe_serialize(obj)[source]

Safely serialize objects for logging.

Parameters:: obj (Any) – Object to serialize
Return type:: Union[str, dict, list]
Returns:: Serialized representation

Safely serializes objects for logging, handling complex types.

Example:

from nepse_client.client import safe_serialize
from datetime import datetime

obj = {
   'date': datetime.now(),
   'data': [1, 2, 3],
   'nested': {'key': 'value'}
}

serialized = safe_serialize(obj)
print(serialized)  # JSON string

get_client_info

nepse_client.get_client_info()

Get information about the NEPSE client package.

Returns:: Package information including version, author, and features.
Return type:: dict

Example

>>> from nepse_client import get_client_info
>>> info = get_client_info()
>>> print(info['version'])
1.0.0

Returns information about the nepse-client package.

Example:

from nepse_client import get_client_info

info = get_client_info()
print(info)
# {
#     'name': 'nepse-client',
#     'version': '1.0.0',
#     'author': 'Amrit Giri',
#     'features': [...],
#     ...
# }

Token Parser

TokenParser

class nepse_client.token_manager.TokenParser[source]

Bases: object

Parse authentication tokens using WebAssembly module.

This class uses a WASM module to decode and parse the authentication tokens returned by the NEPSE API.

__init__()[source]: Initialize token parser with WASM runtime.

parse_token_response(token_response)[source]

Parse access and refresh tokens from API response.

Parameters:: token_response (dict) – Raw token response from API
Return type:: tuple[str, str]
Returns:: Tuple of (access_token, refresh_token)

Parses authentication tokens using WebAssembly module.

Example:

from nepse_client.token_manager import TokenParser

parser = TokenParser()
token_response = {
   'accessToken': '...',
   'refreshToken': '...',
   'salt1': 100,
   'salt2': 200,
   'salt3': 300,
   'salt4': 400,
   'salt5': 500,
   'serverTime': 1234567890
}

access_token, refresh_token = parser.parse_token_response(token_response)

Data Type Conversions

Date/Time Handling

The library handles various date and time formats:

String to Date:

from datetime import date

# ISO format strings
date_obj = date.fromisoformat('2024-01-15')

# In client methods
history = client.getCompanyPriceVolumeHistory(
   symbol='NABIL',
   start_date='2024-01-01',  # String
   end_date=date.today()      # date object
)

DateTime Parsing:

The DummyIDManager includes robust datetime parsing:

from nepse_client.dummy_id_manager import DummyIDManager

manager = DummyIDManager()

# Handles various formats
dt1 = manager.convertToDateTime('2024-01-15T10:45:00')
dt2 = manager.convertToDateTime('2024-01-15T10:45:00.123456')
dt3 = manager.convertToDateTime('2024-01-15T10:45:00.123456789')  # Truncates

Type Annotations

The library provides comprehensive type hints:

Client Types:

from typing import Dict, List, Any, Optional
from nepse_client import NepseClient

client: NepseClient = NepseClient()

# All methods have return type annotations
status: Dict[str, Any] = client.getMarketStatus()
companies: List[Dict[str, Any]] = client.getCompanyList()
company: Dict[str, Any] = client.getCompanyDetails('NABIL')

Optional Parameters:

from datetime import date
from typing import Optional, Union

history = client.getCompanyPriceVolumeHistory(
   symbol: str,
   start_date: Optional[Union[str, date]] = None,
   end_date: Optional[Union[str, date]] = None
)

Configuration Loading

The client loads configuration from JSON files:

API Endpoints:

Located at nepse_client/data/API_ENDPOINTS.json

{
   "market_status_url": "/api/nots/nepse-data/market-open",
   "summary_url": "/api/nots/market-summary/",
   ...
}

Headers:

Located at nepse_client/data/HEADERS.json

{
   "User-Agent": "Mozilla/5.0 ...",
   "Accept": "application/json",
   ...
}

Dummy Data:

Located at nepse_client/data/DUMMY_DATA.json

[147, 117, 239, 143, ...]

WASM Module:

Located at nepse_client/data/css.wasm - Used for token parsing

Logging Utilities

The library uses Python’s standard logging:

Basic Setup:

import logging

# Configure root logger
logging.basicConfig(
   level=logging.INFO,
   format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Client will use configured logger
client = NepseClient()

Custom Logger:

import logging

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

# Add handler
handler = logging.FileHandler('nepse.log')
handler.setFormatter(
   logging.Formatter('%(asctime)s - %(levelname)s - %(message)s')
)
logger.addHandler(handler)

# Use with client
client = NepseClient(logger=logger)

Log Levels:

DEBUG: Detailed information (HTTP requests, responses)
INFO: General information (token refresh, cache updates)
WARNING: Warning messages (retry attempts)
ERROR: Error messages (API failures)
CRITICAL: Critical errors (configuration failures)

Response Processing

The client automatically processes responses:

JSON Parsing:

# Automatic JSON parsing
response = client.getMarketStatus()
# Returns: Dict[str, Any]

Error Handling:

# Automatic error handling based on status code
# 200-299: Success - returns data
# 400: NepseClientError
# 401: NepseAuthenticationError (auto-retry)
# 502: NepseBadGatewayError
# 5xx: NepseServerError

Data Extraction:

# Some responses have nested content
history = client.getCompanyPriceVolumeHistory('NABIL')

# Automatically extracts 'content' field if present
if isinstance(history, dict) and 'content' in history:
   data = history['content']
else:
   data = history

Caching Mechanisms

The client implements smart caching:

Company ID Cache:

# First call - fetches from API
company_map = client.getCompanyIDKeyMap()
# {'NABIL': 1, 'NICA': 2, ...}

# Subsequent calls - returns cached data
company_map = client.getCompanyIDKeyMap()

# Force refresh
company_map = client.getCompanyIDKeyMap(force_update=True)

Security ID Cache:

security_map = client.getSecurityIDKeyMap()
# Cached automatically

Sector Scrips Cache:

sector_scrips = client.getSectorScrips()
# {'Commercial Banks': ['NABIL', ...], ...}
# Cached after first call

Progress Tracking

For long-running operations:

Floor Sheet with Progress:

from nepse_client import NepseClient

client = NepseClient()

# Shows progress bar
floor_sheet = client.getFloorSheet(show_progress=True)
# Downloading floor sheet: 100%|████████| 150/150 [00:30<00:00]

Async Progress:

import asyncio
from nepse_client import AsyncNepseClient

async def main():
   client = AsyncNepseClient()
   floor_sheet = await client.getFloorSheet(show_progress=True)

asyncio.run(main())

Pagination Helpers

Some endpoints return paginated data:

Manual Pagination:

# Get specific page
page_0 = client.getFloorSheet(page=0)
page_1 = client.getFloorSheet(page=1)

Automatic Pagination:

# Get all pages automatically
all_data = client.getFloorSheet()  # Fetches all pages

Paginated Format:

# Returns list of pages
pages = client.getFloorSheet(paginated=True)
# [[page_0_data], [page_1_data], ...]

Testing Utilities

For testing your application:

Mock Client:

from unittest.mock import Mock
from nepse_client import NepseClient

# Create mock client
mock_client = Mock(spec=NepseClient)
mock_client.getMarketStatus.return_value = {
   'isOpen': 'OPEN',
   'asOf': '2024-01-15T10:00:00'
}

# Use in tests
status = mock_client.getMarketStatus()

Disable TLS for Testing:

# Only for testing!
client = NepseClient()
client.setTLSVerification(False)

# Run tests
# ...

# Re-enable
client.setTLSVerification(True)

Constants

Package Constants:

from nepse_client import __version__, __author__

print(__version__)  # '1.0.0'
print(__author__)   # 'Amrit Giri'

Client Constants:

client = NepseClient()

print(client.base_url)           # 'https://nepalstock.com.np'
print(client.floor_sheet_size)   # 500
print(client.timeout)            # 100.0