cse.lk 1.0.0

A comprehensive Python client for the Colombo Stock Exchange (CSE) API

CSE.LK - Colombo Stock Exchange Python Client 📈🐍

A comprehensive Python package for accessing the Colombo Stock Exchange (CSE) API
Simple, type-safe, and feature-rich client with complete API coverage and professional error handling.

---

🚀 Quick Start

Installation

pip install cse.lk

Basic Usage

from cse_lk import CSEClient

# Initialize the client
client = CSEClient()

# Get company information
company = client.get_company_info("LOLC.N0000")
print(f"{company.name}: LKR {company.last_traded_price}")
# Output: L O L C HOLDINGS PLC: LKR 546.5

# Get market overview
overview = client.get_market_overview()
print(f"Market Status: {overview['status'].status}")
print(f"ASPI: {overview['aspi'].value}")

# Get top gainers
gainers = client.get_top_gainers()
for gainer in gainers[:5]:
    print(f"{gainer.symbol}: +{gainer.change_percentage:.2f}%")

---

📚 Features

• ✅ Complete API Coverage - All 22 CSE API endpoints supported
• ✅ Type Safety - Full type hints with proper data models
• ✅ Error Handling - Comprehensive exception handling with custom error types
• ✅ Rate Limiting - Built-in retry logic with exponential backoff
• ✅ Easy to Use - Pythonic interface with intuitive method names
• ✅ Well Documented - Extensive documentation and examples
• ✅ Tested - Comprehensive test suite with >95% coverage
• ✅ Production Ready - Used in production environments

---

🏢 Supported Endpoints

Method	Endpoint	Description
get_company_info(symbol)	companyInfoSummery	Get detailed company information
get_trade_summary()	tradeSummary	Get trade summary for all securities
get_today_share_prices()	todaySharePrice	Get today's share prices
get_top_gainers()	topGainers	Get top gaining stocks
get_top_losers()	topLooses	Get top losing stocks
get_most_active_trades()	mostActiveTrades	Get most active trades
get_market_status()	marketStatus	Get market open/close status
get_market_summary()	marketSummery	Get market summary data
get_aspi_data()	aspiData	Get All Share Price Index data
get_snp_data()	snpData	Get S&P Sri Lanka 20 Index data
get_all_sectors()	allSectors	Get all sector data
get_detailed_trades(symbol?)	detailedTrades	Get detailed trade information
get_daily_market_summary()	dailyMarketSummery	Get daily market summary

Announcement Endpoints

Method	Description
get_new_listings_announcements()	New listings and related announcements
get_buy_in_board_announcements()	Buy-in board announcements
get_approved_announcements()	Approved announcements
get_covid_announcements()	COVID-related announcements
get_financial_announcements()	Financial announcements
get_circular_announcements()	Circular announcements
get_directive_announcements()	Directive announcements
get_non_compliance_announcements()	Non-compliance announcements

---

💡 Advanced Usage

Using Context Manager

from cse_lk import CSEClient

with CSEClient() as client:
    # Client will automatically close session when done
    company_info = client.get_company_info("LOLC.N0000")
    market_status = client.get_market_status()

Custom Configuration

from cse_lk import CSEClient

client = CSEClient(
    timeout=60,           # Custom timeout
    max_retries=5,        # Custom retry count
    retry_delay=2.0       # Custom retry delay
)

Error Handling

from cse_lk import CSEClient, CSEError, CSEValidationError, CSENetworkError

client = CSEClient()

try:
    company = client.get_company_info("INVALID")
except CSEValidationError as e:
    print(f"Validation error: {e}")
except CSENetworkError as e:
    print(f"Network error: {e}")
except CSEError as e:
    print(f"General CSE error: {e}")

Searching Companies

# Search for companies containing "LOLC"
results = client.search_companies("LOLC")
for company in results:
    print(f"{company.symbol}: LKR {company.last_traded_price}")

Working with Data Models

company = client.get_company_info("LOLC.N0000")

# Access company logo
if company.logo:
    print(f"Logo URL: {company.logo.full_url}")

# Check market status
status = client.get_market_status()
if status.is_open:
    print("Market is currently open")
else:
    print("Market is closed")

# Get historical data
daily_summary = client.get_daily_market_summary()
for day in daily_summary[:5]:  # Last 5 days
    print(f"{day.trade_date}: LKR {day.market_turnover:,.0f}")

---

📖 API Reference

Data Models

All API responses are parsed into type-safe data models:

• CompanyInfo - Company details with logo, price, and beta information
• TradeSummary - Trade summary with volume and price data
• SharePrice - Current share price with change information
• MarketStatus - Market open/close status with convenience methods
• IndexData - Index values (ASPI, S&P SL20) with change data
• DetailedTrade - Detailed trade information with quantities
• DailyMarketSummary - Comprehensive daily market statistics
• Announcement - Company announcements and notices

Exception Hierarchy

CSEError (Base exception)
├── CSEAPIError (API response errors)
├── CSENetworkError (Network/connection errors)
├── CSEValidationError (Input validation errors)
├── CSEAuthenticationError (Authentication failures)
└── CSERateLimitError (Rate limiting errors)

---

🧪 Testing

Run the test suite:

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

# Run tests
pytest

# Run tests with coverage
pytest --cov=cse_lk --cov-report=html

---

📦 Installation for Development

# Clone the repository
git clone https://github.com/your-username/cse.lk.git
cd cse.lk

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

# Install pre-commit hooks
pre-commit install

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

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

---

⚠️ Disclaimer

• This is an unofficial client for the CSE API
• Use responsibly and verify data accuracy with official CSE sources
• API endpoints and formats may change without notice
• This package is for educational and development purposes
• Not affiliated with the Colombo Stock Exchange

---

🙏 Acknowledgments

• Original API documentation by GH0STH4CKER
• Colombo Stock Exchange for providing the public API endpoints

---

📊 Sample Response Data

Company Information

{
  "symbol": "LOLC.N0000",
  "name": "L O L C HOLDINGS PLC",
  "last_traded_price": 546.5,
  "change": -2.5,
  "change_percentage": -0.455,
  "market_cap": 259696800000,
  "beta_value": 1.0227,
  "logo": {
    "id": 2168,
    "path": "upload_logo/378_1601611239.jpeg"
  }
}

Market Overview

{
  "status": {"status": "Market Open"},
  "aspi": {"value": 19826.57, "change": 21.77},
  "snp_sl20": {"value": 5825.39, "change": -2.46},
  "top_gainers": [...],
  "top_losers": [...],
  "most_active": [...]
}