# 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.
[](https://badge.fury.io/py/cse.lk)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/your-username/cse.lk/actions)
---
## 🚀 Quick Start
### Installation
```bash
pip install cse.lk
```
### Basic Usage
```python
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
```python
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
```python
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
```python
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
```python
# 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
```python
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:
```bash
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run tests with coverage
pytest --cov=cse_lk --cov-report=html
```
---
## 📦 Installation for Development
```bash
# 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](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](https://github.com/GH0STH4CKER/Colombo-Stock-Exchange-CSE-API-Documentation)
- Colombo Stock Exchange for providing the public API endpoints
---
## 📊 Sample Response Data
### Company Information
```json
{
"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
```json
{
"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": [...]
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/your-username/cse.lk",
"name": "cse.lk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "colombo stock exchange cse api finance sri lanka stocks trading",
"author": "CSE API Client",
"author_email": "contact@example.com",
"download_url": "https://files.pythonhosted.org/packages/32/1f/7871eaf4c4a60bf98abf22367207ac9688ba5bd19a1bdf36ad04e4d32b3a/cse_lk-1.0.0.tar.gz",
"platform": null,
"description": "# CSE.LK - Colombo Stock Exchange Python Client \ud83d\udcc8\ud83d\udc0d\n\n> **A comprehensive Python package for accessing the Colombo Stock Exchange (CSE) API** \n> Simple, type-safe, and feature-rich client with complete API coverage and professional error handling.\n\n[](https://badge.fury.io/py/cse.lk)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/your-username/cse.lk/actions)\n\n---\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n```bash\npip install cse.lk\n```\n\n### Basic Usage\n\n```python\nfrom cse_lk import CSEClient\n\n# Initialize the client\nclient = CSEClient()\n\n# Get company information\ncompany = client.get_company_info(\"LOLC.N0000\")\nprint(f\"{company.name}: LKR {company.last_traded_price}\")\n# Output: L O L C HOLDINGS PLC: LKR 546.5\n\n# Get market overview\noverview = client.get_market_overview()\nprint(f\"Market Status: {overview['status'].status}\")\nprint(f\"ASPI: {overview['aspi'].value}\")\n\n# Get top gainers\ngainers = client.get_top_gainers()\nfor gainer in gainers[:5]:\n print(f\"{gainer.symbol}: +{gainer.change_percentage:.2f}%\")\n```\n\n---\n\n## \ud83d\udcda Features\n\n- \u2705 **Complete API Coverage** - All 22 CSE API endpoints supported\n- \u2705 **Type Safety** - Full type hints with proper data models\n- \u2705 **Error Handling** - Comprehensive exception handling with custom error types\n- \u2705 **Rate Limiting** - Built-in retry logic with exponential backoff\n- \u2705 **Easy to Use** - Pythonic interface with intuitive method names\n- \u2705 **Well Documented** - Extensive documentation and examples\n- \u2705 **Tested** - Comprehensive test suite with >95% coverage\n- \u2705 **Production Ready** - Used in production environments\n\n---\n\n## \ud83c\udfe2 Supported Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `get_company_info(symbol)` | companyInfoSummery | Get detailed company information |\n| `get_trade_summary()` | tradeSummary | Get trade summary for all securities |\n| `get_today_share_prices()` | todaySharePrice | Get today's share prices |\n| `get_top_gainers()` | topGainers | Get top gaining stocks |\n| `get_top_losers()` | topLooses | Get top losing stocks |\n| `get_most_active_trades()` | mostActiveTrades | Get most active trades |\n| `get_market_status()` | marketStatus | Get market open/close status |\n| `get_market_summary()` | marketSummery | Get market summary data |\n| `get_aspi_data()` | aspiData | Get All Share Price Index data |\n| `get_snp_data()` | snpData | Get S&P Sri Lanka 20 Index data |\n| `get_all_sectors()` | allSectors | Get all sector data |\n| `get_detailed_trades(symbol?)` | detailedTrades | Get detailed trade information |\n| `get_daily_market_summary()` | dailyMarketSummery | Get daily market summary |\n\n### Announcement Endpoints\n\n| Method | Description |\n|--------|-------------|\n| `get_new_listings_announcements()` | New listings and related announcements |\n| `get_buy_in_board_announcements()` | Buy-in board announcements |\n| `get_approved_announcements()` | Approved announcements |\n| `get_covid_announcements()` | COVID-related announcements |\n| `get_financial_announcements()` | Financial announcements |\n| `get_circular_announcements()` | Circular announcements |\n| `get_directive_announcements()` | Directive announcements |\n| `get_non_compliance_announcements()` | Non-compliance announcements |\n\n---\n\n## \ud83d\udca1 Advanced Usage\n\n### Using Context Manager\n\n```python\nfrom cse_lk import CSEClient\n\nwith CSEClient() as client:\n # Client will automatically close session when done\n company_info = client.get_company_info(\"LOLC.N0000\")\n market_status = client.get_market_status()\n```\n\n### Custom Configuration\n\n```python\nfrom cse_lk import CSEClient\n\nclient = CSEClient(\n timeout=60, # Custom timeout\n max_retries=5, # Custom retry count\n retry_delay=2.0 # Custom retry delay\n)\n```\n\n### Error Handling\n\n```python\nfrom cse_lk import CSEClient, CSEError, CSEValidationError, CSENetworkError\n\nclient = CSEClient()\n\ntry:\n company = client.get_company_info(\"INVALID\")\nexcept CSEValidationError as e:\n print(f\"Validation error: {e}\")\nexcept CSENetworkError as e:\n print(f\"Network error: {e}\")\nexcept CSEError as e:\n print(f\"General CSE error: {e}\")\n```\n\n### Searching Companies\n\n```python\n# Search for companies containing \"LOLC\"\nresults = client.search_companies(\"LOLC\")\nfor company in results:\n print(f\"{company.symbol}: LKR {company.last_traded_price}\")\n```\n\n### Working with Data Models\n\n```python\ncompany = client.get_company_info(\"LOLC.N0000\")\n\n# Access company logo\nif company.logo:\n print(f\"Logo URL: {company.logo.full_url}\")\n\n# Check market status\nstatus = client.get_market_status()\nif status.is_open:\n print(\"Market is currently open\")\nelse:\n print(\"Market is closed\")\n\n# Get historical data\ndaily_summary = client.get_daily_market_summary()\nfor day in daily_summary[:5]: # Last 5 days\n print(f\"{day.trade_date}: LKR {day.market_turnover:,.0f}\")\n```\n\n---\n\n## \ud83d\udcd6 API Reference\n\n### Data Models\n\nAll API responses are parsed into type-safe data models:\n\n- **CompanyInfo** - Company details with logo, price, and beta information\n- **TradeSummary** - Trade summary with volume and price data\n- **SharePrice** - Current share price with change information\n- **MarketStatus** - Market open/close status with convenience methods\n- **IndexData** - Index values (ASPI, S&P SL20) with change data\n- **DetailedTrade** - Detailed trade information with quantities\n- **DailyMarketSummary** - Comprehensive daily market statistics\n- **Announcement** - Company announcements and notices\n\n### Exception Hierarchy\n\n```\nCSEError (Base exception)\n\u251c\u2500\u2500 CSEAPIError (API response errors)\n\u251c\u2500\u2500 CSENetworkError (Network/connection errors)\n\u251c\u2500\u2500 CSEValidationError (Input validation errors)\n\u251c\u2500\u2500 CSEAuthenticationError (Authentication failures)\n\u2514\u2500\u2500 CSERateLimitError (Rate limiting errors)\n```\n\n---\n\n## \ud83e\uddea Testing\n\nRun the test suite:\n\n```bash\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run tests with coverage\npytest --cov=cse_lk --cov-report=html\n```\n\n---\n\n## \ud83d\udce6 Installation for Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/your-username/cse.lk.git\ncd cse.lk\n\n# Install in development mode\npip install -e \".[dev]\"\n\n# Install pre-commit hooks\npre-commit install\n```\n\n---\n\n## \ud83e\udd1d Contributing\n\nContributions 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.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n---\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## \u26a0\ufe0f Disclaimer\n\n- This is an **unofficial** client for the CSE API\n- Use responsibly and verify data accuracy with official CSE sources\n- API endpoints and formats may change without notice\n- This package is for educational and development purposes\n- Not affiliated with the Colombo Stock Exchange\n\n---\n\n## \ud83d\ude4f Acknowledgments\n\n- Original API documentation by [GH0STH4CKER](https://github.com/GH0STH4CKER/Colombo-Stock-Exchange-CSE-API-Documentation)\n- Colombo Stock Exchange for providing the public API endpoints\n\n---\n\n## \ud83d\udcca Sample Response Data\n\n### Company Information\n```json\n{\n \"symbol\": \"LOLC.N0000\",\n \"name\": \"L O L C HOLDINGS PLC\",\n \"last_traded_price\": 546.5,\n \"change\": -2.5,\n \"change_percentage\": -0.455,\n \"market_cap\": 259696800000,\n \"beta_value\": 1.0227,\n \"logo\": {\n \"id\": 2168,\n \"path\": \"upload_logo/378_1601611239.jpeg\"\n }\n}\n```\n\n### Market Overview\n```json\n{\n \"status\": {\"status\": \"Market Open\"},\n \"aspi\": {\"value\": 19826.57, \"change\": 21.77},\n \"snp_sl20\": {\"value\": 5825.39, \"change\": -2.46},\n \"top_gainers\": [...],\n \"top_losers\": [...],\n \"most_active\": [...]\n}\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "A comprehensive Python client for the Colombo Stock Exchange (CSE) API",
"version": "1.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/your-username/cse.lk/issues",
"Documentation": "https://github.com/your-username/cse.lk#readme",
"Homepage": "https://github.com/your-username/cse.lk",
"Source Code": "https://github.com/your-username/cse.lk"
},
"split_keywords": [
"colombo",
"stock",
"exchange",
"cse",
"api",
"finance",
"sri",
"lanka",
"stocks",
"trading"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8e388c092281333a5f0e3fad0c97a245ae50e7585766f62d0497ae668c30201e",
"md5": "e050a3c2c4d62cf0e164304f17a66adf",
"sha256": "be8095c599e863db69bedf05091f36ec7adbe1b1011d3316f61ec9d34d47a10c"
},
"downloads": -1,
"filename": "cse_lk-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e050a3c2c4d62cf0e164304f17a66adf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 17821,
"upload_time": "2025-08-15T21:21:17",
"upload_time_iso_8601": "2025-08-15T21:21:17.617837Z",
"url": "https://files.pythonhosted.org/packages/8e/38/8c092281333a5f0e3fad0c97a245ae50e7585766f62d0497ae668c30201e/cse_lk-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "321f7871eaf4c4a60bf98abf22367207ac9688ba5bd19a1bdf36ad04e4d32b3a",
"md5": "a23fc32b9ee096c324e5d777f3ea1377",
"sha256": "8d686bbbc6acd59e52cf7eabd7ed4767831387d324e1baf1683dbc3a94b5805a"
},
"downloads": -1,
"filename": "cse_lk-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "a23fc32b9ee096c324e5d777f3ea1377",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 36623,
"upload_time": "2025-08-15T21:21:18",
"upload_time_iso_8601": "2025-08-15T21:21:18.697641Z",
"url": "https://files.pythonhosted.org/packages/32/1f/7871eaf4c4a60bf98abf22367207ac9688ba5bd19a1bdf36ad04e4d32b3a/cse_lk-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-15 21:21:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "your-username",
"github_project": "cse.lk",
"github_not_found": true,
"lcname": "cse.lk"
}
JSON
