sahmk 0.1.0__tar.gz

sahmk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SAHMK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sahmk-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: sahmk
+Version: 0.1.0
+Summary: Lightweight Python client for the SAHMK Developer API.
+Author-email: Sahmk <developer@sahmk.sa>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sahmk-sa/sahmk-python
+Project-URL: Documentation, https://sahmk.sa/developers/docs
+Project-URL: Repository, https://github.com/sahmk-sa/sahmk-python
+Project-URL: Issues, https://github.com/sahmk-sa/sahmk-python/issues
+Keywords: stocks,tadawul,market-data,websocket,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: websockets>=12.0
+Dynamic: license-file
+
+# SAHMK Python SDK
+
+A lightweight Python client for the [SAHMK Developer API](https://sahmk.sa/developers) — real-time and historical Saudi stock market (Tadawul) data.
+
+## Features
+
+- **Real-time quotes** — live prices for 350+ Tadawul stocks
+- **Batch quotes** — up to 50 stocks in a single request
+- **Historical data** — daily/weekly/monthly OHLCV with custom date ranges
+- **Market overview** — TASI index, gainers, losers, volume/value leaders, sectors
+- **Company info** — fundamentals, technicals, valuation, analyst consensus (by plan)
+- **Financials** — income statements, balance sheets, cash flow
+- **Dividends** — history, yield, upcoming payments
+- **Events** — AI-generated stock event summaries
+- **WebSocket streaming** — real-time price updates pushed to you (Pro+ plan)
+
+## Installation
+
+After the first PyPI release:
+
+```bash
+pip install sahmk
+```
+
+Or clone this repo for local development:
+
+```bash
+git clone https://github.com/sahmk-sa/sahmk-python.git
+cd sahmk-python
+pip install -r requirements.txt
+```
+
+## Quick Start
+
+```python
+from sahmk import SahmkClient
+
+client = SahmkClient("your_api_key")
+
+# Get a stock quote
+quote = client.quote("2222")
+print(f"{quote['name_en']}: {quote['price']} SAR ({quote['change_percent']}%)")
+
+# Get market summary
+market = client.market_summary()
+print(f"TASI: {market['index_value']} ({market['index_change_percent']}%)")
+
+# Batch quotes (Starter+ plan)
+result = client.quotes(["2222", "1120", "4191"])
+for q in result["quotes"]:
+    print(f"{q['symbol']}: {q['price']}")
+```
+
+## Get Your API Key
+
+1. Sign up at [sahmk.sa/developers](https://sahmk.sa/developers)
+2. Verify your email
+3. Go to Dashboard → API Keys → Create Key
+4. Copy your key (starts with `shmk_live_` or `shmk_test_`)
+
+## Plans
+
+| Plan | Price | Requests/Day | WebSocket |
+|------|-------|-------------|-----------|
+| Free | 0 SAR | 100 | - |
+| Starter | 149 SAR/mo | 5,000 | - |
+| Pro | 499 SAR/mo | 50,000 | Yes |
+| Enterprise | 1,499+ SAR/mo | Unlimited | Yes |
+
+## Examples
+
+Check the [`examples/`](examples/) directory:
+
+| File | Description |
+|------|-------------|
+| [`quote.py`](examples/quote.py) | Get a single stock quote |
+| [`batch_quotes.py`](examples/batch_quotes.py) | Fetch multiple stocks at once |
+| [`historical.py`](examples/historical.py) | Historical price data |
+| [`market_summary.py`](examples/market_summary.py) | Market overview and movers |
+| [`websocket_stream.py`](examples/websocket_stream.py) | Real-time WebSocket streaming (Pro+) |
+
+## API Reference
+
+Base URL: `https://app.sahmk.sa/api/v1`
+
+| Endpoint | Plan | Description |
+|----------|------|-------------|
+| `GET /quote/{symbol}/` | Free | Stock quote |
+| `GET /quotes/?symbols=...` | Starter+ | Batch quotes (up to 50) |
+| `GET /historical/{symbol}/` | Starter+ | Historical OHLCV data |
+| `GET /market/summary/` | Free | Market overview & TASI index |
+| `GET /market/gainers/` | Free | Top gainers |
+| `GET /market/losers/` | Free | Top losers |
+| `GET /market/volume/` | Free | Volume leaders |
+| `GET /market/value/` | Free | Value leaders |
+| `GET /market/sectors/` | Free | Sector performance |
+| `GET /company/{symbol}/` | Free+ | Company info (tiered by plan) |
+| `GET /financials/{symbol}/` | Starter+ | Financial statements |
+| `GET /dividends/{symbol}/` | Starter+ | Dividend history & yield |
+| `GET /events/` | Pro+ | AI-generated stock events |
+
+All endpoints require the `X-API-Key` header.
+
+Full docs: [sahmk.sa/developers/docs](https://sahmk.sa/developers/docs)
+
+## WebSocket Streaming (Pro+)
+
+```python
+import asyncio
+from sahmk import SahmkClient
+
+client = SahmkClient("your_api_key")
+
+async def on_quote(msg):
+    symbol = msg["symbol"]
+    price = msg["data"]["price"]
+    print(f"{symbol}: {price}")
+
+asyncio.run(client.stream(["2222", "1120"], on_quote=on_quote))
+```
+
+Connection URL: `wss://app.sahmk.sa/ws/v1/stocks/?api_key=YOUR_KEY`
+
+## License
+
+MIT — see [LICENSE](LICENSE)

sahmk-0.1.0/README.md

@@ -0,0 +1,126 @@
+# SAHMK Python SDK
+
+A lightweight Python client for the [SAHMK Developer API](https://sahmk.sa/developers) — real-time and historical Saudi stock market (Tadawul) data.
+
+## Features
+
+- **Real-time quotes** — live prices for 350+ Tadawul stocks
+- **Batch quotes** — up to 50 stocks in a single request
+- **Historical data** — daily/weekly/monthly OHLCV with custom date ranges
+- **Market overview** — TASI index, gainers, losers, volume/value leaders, sectors
+- **Company info** — fundamentals, technicals, valuation, analyst consensus (by plan)
+- **Financials** — income statements, balance sheets, cash flow
+- **Dividends** — history, yield, upcoming payments
+- **Events** — AI-generated stock event summaries
+- **WebSocket streaming** — real-time price updates pushed to you (Pro+ plan)
+
+## Installation
+
+After the first PyPI release:
+
+```bash
+pip install sahmk
+```
+
+Or clone this repo for local development:
+
+```bash
+git clone https://github.com/sahmk-sa/sahmk-python.git
+cd sahmk-python
+pip install -r requirements.txt
+```
+
+## Quick Start
+
+```python
+from sahmk import SahmkClient
+
+client = SahmkClient("your_api_key")
+
+# Get a stock quote
+quote = client.quote("2222")
+print(f"{quote['name_en']}: {quote['price']} SAR ({quote['change_percent']}%)")
+
+# Get market summary
+market = client.market_summary()
+print(f"TASI: {market['index_value']} ({market['index_change_percent']}%)")
+
+# Batch quotes (Starter+ plan)
+result = client.quotes(["2222", "1120", "4191"])
+for q in result["quotes"]:
+    print(f"{q['symbol']}: {q['price']}")
+```
+
+## Get Your API Key
+
+1. Sign up at [sahmk.sa/developers](https://sahmk.sa/developers)
+2. Verify your email
+3. Go to Dashboard → API Keys → Create Key
+4. Copy your key (starts with `shmk_live_` or `shmk_test_`)
+
+## Plans
+
+| Plan | Price | Requests/Day | WebSocket |
+|------|-------|-------------|-----------|
+| Free | 0 SAR | 100 | - |
+| Starter | 149 SAR/mo | 5,000 | - |
+| Pro | 499 SAR/mo | 50,000 | Yes |
+| Enterprise | 1,499+ SAR/mo | Unlimited | Yes |
+
+## Examples
+
+Check the [`examples/`](examples/) directory:
+
+| File | Description |
+|------|-------------|
+| [`quote.py`](examples/quote.py) | Get a single stock quote |
+| [`batch_quotes.py`](examples/batch_quotes.py) | Fetch multiple stocks at once |
+| [`historical.py`](examples/historical.py) | Historical price data |
+| [`market_summary.py`](examples/market_summary.py) | Market overview and movers |
+| [`websocket_stream.py`](examples/websocket_stream.py) | Real-time WebSocket streaming (Pro+) |
+
+## API Reference
+
+Base URL: `https://app.sahmk.sa/api/v1`
+
+| Endpoint | Plan | Description |
+|----------|------|-------------|
+| `GET /quote/{symbol}/` | Free | Stock quote |
+| `GET /quotes/?symbols=...` | Starter+ | Batch quotes (up to 50) |
+| `GET /historical/{symbol}/` | Starter+ | Historical OHLCV data |
+| `GET /market/summary/` | Free | Market overview & TASI index |
+| `GET /market/gainers/` | Free | Top gainers |
+| `GET /market/losers/` | Free | Top losers |
+| `GET /market/volume/` | Free | Volume leaders |
+| `GET /market/value/` | Free | Value leaders |
+| `GET /market/sectors/` | Free | Sector performance |
+| `GET /company/{symbol}/` | Free+ | Company info (tiered by plan) |
+| `GET /financials/{symbol}/` | Starter+ | Financial statements |
+| `GET /dividends/{symbol}/` | Starter+ | Dividend history & yield |
+| `GET /events/` | Pro+ | AI-generated stock events |
+
+All endpoints require the `X-API-Key` header.
+
+Full docs: [sahmk.sa/developers/docs](https://sahmk.sa/developers/docs)
+
+## WebSocket Streaming (Pro+)
+
+```python
+import asyncio
+from sahmk import SahmkClient
+
+client = SahmkClient("your_api_key")
+
+async def on_quote(msg):
+    symbol = msg["symbol"]
+    price = msg["data"]["price"]
+    print(f"{symbol}: {price}")
+
+asyncio.run(client.stream(["2222", "1120"], on_quote=on_quote))
+```
+
+Connection URL: `wss://app.sahmk.sa/ws/v1/stocks/?api_key=YOUR_KEY`
+
+## License
+
+MIT — see [LICENSE](LICENSE)

sahmk-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sahmk"
+version = "0.1.0"
+description = "Lightweight Python client for the SAHMK Developer API."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [
+  { name = "Sahmk", email = "developer@sahmk.sa" }
+]
+keywords = ["stocks", "tadawul", "market-data", "websocket", "api"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Office/Business :: Financial",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+dependencies = [
+  "requests>=2.28.0",
+  "websockets>=12.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/sahmk-sa/sahmk-python"
+Documentation = "https://sahmk.sa/developers/docs"
+Repository = "https://github.com/sahmk-sa/sahmk-python"
+Issues = "https://github.com/sahmk-sa/sahmk-python/issues"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["sahmk*"]

sahmk-0.1.0/sahmk/__init__.py

@@ -0,0 +1,4 @@
+from .client import SahmkClient
+
+__version__ = "0.1.0"
+__all__ = ["SahmkClient"]

sahmk-0.1.0/sahmk/client.py

@@ -0,0 +1,334 @@
+"""
+SAHMK Python Client
+
+A lightweight wrapper for the SAHMK Developer API.
+https://sahmk.sa/developers/docs
+"""
+
+import json
+
+import requests
+
+BASE_URL = "https://app.sahmk.sa/api/v1"
+WS_URL = "wss://app.sahmk.sa/ws/v1/stocks/"
+
+
+class SahmkError(Exception):
+    """Base exception for SAHMK API errors."""
+
+    def __init__(self, message, status_code=None, error_code=None, response=None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.error_code = error_code
+        self.response = response
+
+
+class SahmkClient:
+    """
+    SAHMK Developer API client.
+
+    Usage:
+        client = SahmkClient("your_api_key")
+        quote = client.quote("2222")
+        print(quote["price"])
+    """
+
+    def __init__(self, api_key, base_url=None, timeout=30):
+        """
+        Initialize the client.
+
+        Args:
+            api_key: Your SAHMK API key (starts with shmk_live_ or shmk_test_)
+            base_url: Override the default API base URL
+            timeout: Request timeout in seconds (default: 30)
+        """
+        self.api_key = api_key
+        self.base_url = (base_url or BASE_URL).rstrip("/")
+        self.timeout = timeout
+        self.session = requests.Session()
+        self.session.headers.update({"X-API-Key": api_key})
+
+    def _request(self, method, endpoint, params=None):
+        """Make an API request."""
+        url = f"{self.base_url}{endpoint}"
+        try:
+            response = self.session.request(
+                method, url, params=params, timeout=self.timeout
+            )
+        except requests.RequestException as e:
+            raise SahmkError(f"Request failed: {e}")
+
+        if response.status_code == 429:
+            raise SahmkError(
+                "Rate limit exceeded. Check X-RateLimit-Remaining header.",
+                status_code=429,
+                error_code="RATE_LIMIT",
+                response=response,
+            )
+
+        if response.status_code != 200:
+            try:
+                body = response.json()
+                err = body.get("error", {})
+                code = err.get("code", "UNKNOWN")
+                message = err.get("message", response.text)
+            except (ValueError, KeyError):
+                code = "UNKNOWN"
+                message = response.text
+            raise SahmkError(
+                f"API error {response.status_code}: {message}",
+                status_code=response.status_code,
+                error_code=code,
+                response=response,
+            )
+
+        return response.json()
+
+    # -------------------------------------------------------------------------
+    # Quotes
+    # -------------------------------------------------------------------------
+
+    def quote(self, symbol):
+        """
+        Get a stock quote.
+
+        Args:
+            symbol: Stock symbol (e.g., "2222" for Aramco)
+
+        Returns:
+            dict with keys: symbol, name, name_en, price, change,
+            change_percent, volume, bid, ask, liquidity, etc.
+        """
+        return self._request("GET", f"/quote/{symbol}/")
+
+    def quotes(self, symbols):
+        """
+        Get batch quotes for multiple stocks (Starter+ plan).
+
+        Args:
+            symbols: List of stock symbols (up to 50)
+
+        Returns:
+            dict with "quotes" list and "count"
+        """
+        if len(symbols) > 50:
+            raise SahmkError("Maximum 50 symbols per batch request")
+        return self._request(
+            "GET", "/quotes/", params={"symbols": ",".join(symbols)}
+        )
+
+    # -------------------------------------------------------------------------
+    # Historical
+    # -------------------------------------------------------------------------
+
+    def historical(self, symbol, from_date=None, to_date=None, interval=None):
+        """
+        Get historical OHLCV data (Starter+ plan).
+
+        Args:
+            symbol: Stock symbol
+            from_date: Start date YYYY-MM-DD (default: 30 days ago)
+            to_date: End date YYYY-MM-DD (default: today)
+            interval: "1d", "1w", or "1m" (default: "1d")
+
+        Returns:
+            dict with "symbol", "interval", "from", "to", "count", and "data" list
+        """
+        params = {}
+        if from_date:
+            params["from"] = from_date
+        if to_date:
+            params["to"] = to_date
+        if interval:
+            params["interval"] = interval
+        return self._request("GET", f"/historical/{symbol}/", params=params)
+
+    # -------------------------------------------------------------------------
+    # Market
+    # -------------------------------------------------------------------------
+
+    def market_summary(self):
+        """Get market overview (TASI index, change, volume, market_mood)."""
+        return self._request("GET", "/market/summary/")
+
+    def gainers(self, limit=None):
+        """
+        Get top gaining stocks.
+
+        Args:
+            limit: Number of results (default: 10, max: 50)
+
+        Returns:
+            dict with "gainers" list and "count"
+        """
+        params = {}
+        if limit is not None:
+            params["limit"] = limit
+        return self._request("GET", "/market/gainers/", params=params or None)
+
+    def losers(self, limit=None):
+        """
+        Get top losing stocks.
+
+        Args:
+            limit: Number of results (default: 10, max: 50)
+
+        Returns:
+            dict with "losers" list and "count"
+        """
+        params = {}
+        if limit is not None:
+            params["limit"] = limit
+        return self._request("GET", "/market/losers/", params=params or None)
+
+    def volume_leaders(self, limit=None):
+        """
+        Get stocks with highest trading volume.
+
+        Args:
+            limit: Number of results (default: 10, max: 50)
+
+        Returns:
+            dict with "stocks" list and "count"
+        """
+        params = {}
+        if limit is not None:
+            params["limit"] = limit
+        return self._request("GET", "/market/volume/", params=params or None)
+
+    def value_leaders(self, limit=None):
+        """
+        Get stocks with highest trading value (SAR).
+
+        Args:
+            limit: Number of results (default: 10, max: 50)
+
+        Returns:
+            dict with "stocks" list and "count"
+        """
+        params = {}
+        if limit is not None:
+            params["limit"] = limit
+        return self._request("GET", "/market/value/", params=params or None)
+
+    def sectors(self):
+        """
+        Get sector performance.
+
+        Returns:
+            dict with "sectors" list and "count"
+        """
+        return self._request("GET", "/market/sectors/")
+
+    # -------------------------------------------------------------------------
+    # Company Data
+    # -------------------------------------------------------------------------
+
+    def company(self, symbol):
+        """
+        Get company info. Response varies by plan:
+        Free (basic), Starter (fundamentals), Pro (technicals, valuation, analysts).
+        """
+        return self._request("GET", f"/company/{symbol}/")
+
+    def financials(self, symbol):
+        """Get financial statements (income, balance sheet, cash flow). Starter+ plan."""
+        return self._request("GET", f"/financials/{symbol}/")
+
+    def dividends(self, symbol):
+        """Get dividend history and yield. Starter+ plan."""
+        return self._request("GET", f"/dividends/{symbol}/")
+
+    # -------------------------------------------------------------------------
+    # Events
+    # -------------------------------------------------------------------------
+
+    def events(self, symbol=None, limit=None):
+        """
+        Get AI-generated stock event summaries (Pro+ plan).
+
+        Args:
+            symbol: Optional — filter events for a specific stock
+            limit: Number of results (default: 20)
+
+        Returns:
+            dict with "events" list, "count", and "available_types"
+        """
+        params = {}
+        if symbol:
+            params["symbol"] = symbol
+        if limit is not None:
+            params["limit"] = limit
+        return self._request("GET", "/events/", params=params or None)
+
+    # -------------------------------------------------------------------------
+    # WebSocket Streaming (Pro+ plan)
+    # -------------------------------------------------------------------------
+
+    async def stream(self, symbols, on_quote=None, on_error=None, ping_interval=30):
+        """
+        Stream real-time quotes via WebSocket (Pro+ plan).
+
+        Args:
+            symbols: List of stock symbols to subscribe to (max 20 per call,
+                     max 60 per connection on Pro, 200 on Enterprise)
+            on_quote: Async callback — on_quote(data) where data contains
+                      symbol, timestamp, and quote fields (price, change, etc.)
+            on_error: Async callback — on_error(error_data)
+            ping_interval: Seconds between keep-alive pings (default: 30)
+
+        Usage:
+            async def handle_quote(data):
+                print(f"{data['symbol']}: {data['data']['price']}")
+
+            await client.stream(["2222", "1120"], on_quote=handle_quote)
+        """
+        try:
+            import websockets
+        except ImportError:
+            raise SahmkError(
+                "websockets package required for streaming. "
+                "Install it with: pip install websockets"
+            )
+
+        import asyncio
+
+        url = f"{WS_URL}?api_key={self.api_key}"
+
+        async with websockets.connect(url) as ws:
+            msg = json.loads(await ws.recv())
+            if msg.get("type") == "error":
+                raise SahmkError(f"WebSocket error: {msg.get('message')}")
+
+            for i in range(0, len(symbols), 20):
+                batch = symbols[i : i + 20]
+                await ws.send(
+                    json.dumps({"action": "subscribe", "symbols": batch})
+                )
+                ack = json.loads(await ws.recv())
+                if ack.get("type") == "error":
+                    raise SahmkError(
+                        f"Subscribe error: {ack.get('message')}"
+                    )
+
+            async def _ping_loop():
+                while True:
+                    await asyncio.sleep(ping_interval)
+                    try:
+                        await ws.send(json.dumps({"action": "ping"}))
+                    except Exception:
+                        break
+
+            ping_task = asyncio.create_task(_ping_loop())
+
+            try:
+                async for message in ws:
+                    data = json.loads(message)
+                    msg_type = data.get("type")
+
+                    if msg_type == "quote" and on_quote:
+                        await on_quote(data)
+                    elif msg_type == "error" and on_error:
+                        await on_error(data)
+            finally:
+                ping_task.cancel()

sahmk-0.1.0/sahmk.egg-info/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: sahmk
+Version: 0.1.0
+Summary: Lightweight Python client for the SAHMK Developer API.
+Author-email: Sahmk <developer@sahmk.sa>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sahmk-sa/sahmk-python
+Project-URL: Documentation, https://sahmk.sa/developers/docs
+Project-URL: Repository, https://github.com/sahmk-sa/sahmk-python
+Project-URL: Issues, https://github.com/sahmk-sa/sahmk-python/issues
+Keywords: stocks,tadawul,market-data,websocket,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: websockets>=12.0
+Dynamic: license-file
+
+# SAHMK Python SDK
+
+A lightweight Python client for the [SAHMK Developer API](https://sahmk.sa/developers) — real-time and historical Saudi stock market (Tadawul) data.
+
+## Features
+
+- **Real-time quotes** — live prices for 350+ Tadawul stocks
+- **Batch quotes** — up to 50 stocks in a single request
+- **Historical data** — daily/weekly/monthly OHLCV with custom date ranges
+- **Market overview** — TASI index, gainers, losers, volume/value leaders, sectors
+- **Company info** — fundamentals, technicals, valuation, analyst consensus (by plan)
+- **Financials** — income statements, balance sheets, cash flow
+- **Dividends** — history, yield, upcoming payments
+- **Events** — AI-generated stock event summaries
+- **WebSocket streaming** — real-time price updates pushed to you (Pro+ plan)
+
+## Installation
+
+After the first PyPI release:
+
+```bash
+pip install sahmk
+```
+
+Or clone this repo for local development:
+
+```bash
+git clone https://github.com/sahmk-sa/sahmk-python.git
+cd sahmk-python
+pip install -r requirements.txt
+```
+
+## Quick Start
+
+```python
+from sahmk import SahmkClient
+
+client = SahmkClient("your_api_key")
+
+# Get a stock quote
+quote = client.quote("2222")
+print(f"{quote['name_en']}: {quote['price']} SAR ({quote['change_percent']}%)")
+
+# Get market summary
+market = client.market_summary()
+print(f"TASI: {market['index_value']} ({market['index_change_percent']}%)")
+
+# Batch quotes (Starter+ plan)
+result = client.quotes(["2222", "1120", "4191"])
+for q in result["quotes"]:
+    print(f"{q['symbol']}: {q['price']}")
+```
+
+## Get Your API Key
+
+1. Sign up at [sahmk.sa/developers](https://sahmk.sa/developers)
+2. Verify your email
+3. Go to Dashboard → API Keys → Create Key
+4. Copy your key (starts with `shmk_live_` or `shmk_test_`)
+
+## Plans
+
+| Plan | Price | Requests/Day | WebSocket |
+|------|-------|-------------|-----------|
+| Free | 0 SAR | 100 | - |
+| Starter | 149 SAR/mo | 5,000 | - |
+| Pro | 499 SAR/mo | 50,000 | Yes |
+| Enterprise | 1,499+ SAR/mo | Unlimited | Yes |
+
+## Examples
+
+Check the [`examples/`](examples/) directory:
+
+| File | Description |
+|------|-------------|
+| [`quote.py`](examples/quote.py) | Get a single stock quote |
+| [`batch_quotes.py`](examples/batch_quotes.py) | Fetch multiple stocks at once |
+| [`historical.py`](examples/historical.py) | Historical price data |
+| [`market_summary.py`](examples/market_summary.py) | Market overview and movers |
+| [`websocket_stream.py`](examples/websocket_stream.py) | Real-time WebSocket streaming (Pro+) |
+
+## API Reference
+
+Base URL: `https://app.sahmk.sa/api/v1`
+
+| Endpoint | Plan | Description |
+|----------|------|-------------|
+| `GET /quote/{symbol}/` | Free | Stock quote |
+| `GET /quotes/?symbols=...` | Starter+ | Batch quotes (up to 50) |
+| `GET /historical/{symbol}/` | Starter+ | Historical OHLCV data |
+| `GET /market/summary/` | Free | Market overview & TASI index |
+| `GET /market/gainers/` | Free | Top gainers |
+| `GET /market/losers/` | Free | Top losers |
+| `GET /market/volume/` | Free | Volume leaders |
+| `GET /market/value/` | Free | Value leaders |
+| `GET /market/sectors/` | Free | Sector performance |
+| `GET /company/{symbol}/` | Free+ | Company info (tiered by plan) |
+| `GET /financials/{symbol}/` | Starter+ | Financial statements |
+| `GET /dividends/{symbol}/` | Starter+ | Dividend history & yield |
+| `GET /events/` | Pro+ | AI-generated stock events |
+
+All endpoints require the `X-API-Key` header.
+
+Full docs: [sahmk.sa/developers/docs](https://sahmk.sa/developers/docs)
+
+## WebSocket Streaming (Pro+)
+
+```python
+import asyncio
+from sahmk import SahmkClient
+
+client = SahmkClient("your_api_key")
+
+async def on_quote(msg):
+    symbol = msg["symbol"]
+    price = msg["data"]["price"]
+    print(f"{symbol}: {price}")
+
+asyncio.run(client.stream(["2222", "1120"], on_quote=on_quote))
+```
+
+Connection URL: `wss://app.sahmk.sa/ws/v1/stocks/?api_key=YOUR_KEY`
+
+## License
+
+MIT — see [LICENSE](LICENSE)

sahmk-0.1.0/sahmk.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+sahmk/__init__.py
+sahmk/client.py
+sahmk.egg-info/PKG-INFO
+sahmk.egg-info/SOURCES.txt
+sahmk.egg-info/dependency_links.txt
+sahmk.egg-info/requires.txt
+sahmk.egg-info/top_level.txt

sahmk-0.1.0/sahmk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sahmk-0.1.0/sahmk.egg-info/requires.txt

@@ -0,0 +1,2 @@
+requests>=2.28.0
+websockets>=12.0

sahmk-0.1.0/sahmk.egg-info/top_level.txt

@@ -0,0 +1 @@
+sahmk

sahmk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+