v0.7.0: Add identifier resolution support for quote workflows

Expand quote and batch quote SDK ergonomics to accept symbols, Arabic names, and aliases while preserving legacy symbol compatibility through automatic backend fallback. Add typed resolution metadata, specialized resolution exceptions, refreshed docs/examples, and release metadata updates for a publish-ready 0.7.0.

Made-with: Cursor

Author: sahmk-sa

CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to the `sahmk` Python SDK will be documented in this file.
 
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [0.7.0] — 2026-04-18
+
+### Added
+
+- Identifier-resolution support for quote endpoints in the SDK: `quote()` and `quotes()` now accept symbols, Arabic names, English names, and aliases when backend resolution is enabled
+- New typed resolution metadata: `IdentifierResolution`, `Quote.requested_identifier`, `Quote.resolved_symbol`, `Quote.resolution`, plus batch-level `resolved`, `ambiguous`, and `unknown`
+- New resolution-focused exceptions: `SahmkIdentifierResolutionError`, `SahmkAmbiguousIdentifierError`, and `SahmkUnknownIdentifierError`
+
+### Changed
+
+- `quotes()` now prefers the new `identifiers` backend parameter and transparently falls back to legacy `symbols` for older backends
+- Resolution-related exceptions now preserve backend-provided `status_code` and `error_code` semantics
+- Quote docs and examples now explicitly show both classic symbol usage and identifier-based usage
+
+### Fixed
+
+- Improved backward compatibility during backend rollout by adding automatic quotes parameter fallback instead of requiring immediate backend parity
+
 ## [0.6.2] — 2026-04-12
 
 ### Added

README.md

@@ -53,6 +53,42 @@ for q in client.quotes(["2222", "1120", "7010"])["quotes"]:
     print(f"{q['symbol']}: {q['price']}")
 ```
 
+## Identifier Resolution (Quotes)
+
+`quote()` and `quotes()` accept either traditional symbols or resolvable identifiers:
+
+- Symbol: `"2222"`
+- Arabic company name: `"أرامكو السعودية"`
+- English company name/alias: `"Aramco"`
+
+Symbol input always works. Name/alias input requires backend identifier-resolution support.
+For batch quotes, the SDK first tries `identifiers=...`, then automatically falls back to
+legacy `symbols=...` when connected to older backends.
+
+```python
+q1 = client.quote("2222")              # classic symbol usage
+q2 = client.quote("أرامكو السعودية")   # Arabic identifier
+q3 = client.quote("Aramco")            # English alias
+
+batch = client.quotes(["2222", "الراجحي", "SABIC"])
+for q in batch.quotes:
+    print(q.requested_identifier, "=>", q.symbol)
+
+if batch.ambiguous:
+    print("Ambiguous:", batch.ambiguous)
+if batch.unknown:
+    print("Unknown:", batch.unknown)
+```
+
+When the backend returns resolution metadata, it is exposed on typed objects:
+
+```python
+quote = client.quote("Aramco")
+print(quote.requested_identifier)      # Aramco
+print(quote.resolved_symbol)           # 2222
+print(quote.resolution.matched_by)     # alias (if provided by API)
+```
+
 ## Production Reliability
 
 - The client retries transient failures: **HTTP 429** and **5xx** errors.

examples/batch_quotes.py

@@ -16,12 +16,18 @@
 
 client = SahmkClient(API_KEY)
 
-# Batch quotes — up to 50 symbols per request
-symbols = ["2222", "1120", "4191", "2010", "1010"]
-result = client.quotes(symbols)
+# Batch quotes — up to 50 identifiers.
+# Mix symbols and names/aliases (name/alias requires backend resolution support).
+identifiers = ["2222", "الراجحي", "SABIC", "2010", "7010"]
+result = client.quotes(identifiers)
 
 print(f"{'Symbol':<10} {'Name':<25} {'Price':<10} {'Change %':<10}")
 print("-" * 55)
 
 for q in result["quotes"]:
     print(f"{q['symbol']:<10} {q.get('name_en', ''):<25} {q['price']:<10} {q['change_percent']:<10}")
+
+if result.ambiguous:
+    print("\nAmbiguous identifiers:", result.ambiguous)
+if result.unknown:
+    print("\nUnknown identifiers:", result.unknown)

examples/quote.py

@@ -16,19 +16,31 @@
 
 client = SahmkClient(API_KEY)
 
-# Get Aramco quote
-quote = client.quote("2222")
-
-print(f"Stock: {quote['name_en']} ({quote['symbol']})")
-print(f"Price: {quote['price']} SAR")
-print(f"Change: {quote['change']} ({quote['change_percent']}%)")
-print(f"Volume: {quote.get('volume', 'N/A')}")
-print(f"High: {quote.get('high', 'N/A')}")
-print(f"Low: {quote.get('low', 'N/A')}")
-print(f"Bid: {quote.get('bid', 'N/A')}")
-print(f"Ask: {quote.get('ask', 'N/A')}")
-
-# Liquidity data (buy/sell flow)
-liq = quote.get("liquidity", {})
-if liq:
-    print(f"Net Liquidity: {liq.get('net_value', 'N/A')} SAR")
+
+def print_quote(label, quote):
+    print(f"\n{label}")
+    print(f"Stock: {quote['name_en']} ({quote['symbol']})")
+    print(f"Price: {quote['price']} SAR")
+    print(f"Change: {quote['change']} ({quote['change_percent']}%)")
+    print(f"Volume: {quote.get('volume', 'N/A')}")
+    print(f"High: {quote.get('high', 'N/A')}")
+    print(f"Low: {quote.get('low', 'N/A')}")
+    print(f"Bid: {quote.get('bid', 'N/A')}")
+    print(f"Ask: {quote.get('ask', 'N/A')}")
+
+    liq = quote.get("liquidity", {})
+    if liq:
+        print(f"Net Liquidity: {liq.get('net_value', 'N/A')} SAR")
+
+    if quote.resolution:
+        print(f"Resolved by: {quote.resolution.matched_by}")
+        print(f"Input => Symbol: {quote.requested_identifier} => {quote.resolved_symbol}")
+
+
+# 1) Classic symbol usage (always supported)
+quote_by_symbol = client.quote("2222")
+print_quote("Quote by symbol", quote_by_symbol)
+
+# 2) Name/alias usage (requires backend identifier-resolution support)
+quote_by_name = client.quote("Aramco")
+print_quote("Quote by name/alias", quote_by_name)

pyproject.toml

@@ -1,14 +1,14 @@
 [build-system]
-requires = ["setuptools>=68", "wheel"]
+requires = ["setuptools>=68,<77", "wheel"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "sahmk"
-version = "0.6.2"
+version = "0.7.0"
 description = "Official Python SDK for Sahmk — Saudi market data and richer market workflows for developers."
 readme = "README.md"
 requires-python = ">=3.9"
-license = "MIT"
+license = { text = "MIT" }
 authors = [
   { name = "Sahmk", email = "developer@sahmk.sa" }
 ]

sahmk/__init__.py

@@ -3,11 +3,15 @@
     SahmkError,
     SahmkRateLimitError,
     SahmkInvalidIndexError,
+    SahmkIdentifierResolutionError,
+    SahmkAmbiguousIdentifierError,
+    SahmkUnknownIdentifierError,
 )
 from .models import (
     Quote,
     BatchQuote,
     BatchQuotesResponse,
+    IdentifierResolution,
     HistoricalResponse,
     OHLCV,
     MarketSummary,
@@ -31,15 +35,19 @@
     Liquidity,
 )
 
-__version__ = "0.6.2"
+__version__ = "0.7.0"
 __all__ = [
     "SahmkClient",
     "SahmkError",
     "SahmkRateLimitError",
     "SahmkInvalidIndexError",
+    "SahmkIdentifierResolutionError",
+    "SahmkAmbiguousIdentifierError",
+    "SahmkUnknownIdentifierError",
     "Quote",
     "BatchQuote",
     "BatchQuotesResponse",
+    "IdentifierResolution",
     "HistoricalResponse",
     "OHLCV",
     "MarketSummary",

sahmk/client.py

@@ -75,6 +75,77 @@ def __init__(self, message, response=None):
         )
 
 
+class SahmkIdentifierResolutionError(SahmkError):
+    """Base exception for identifier-resolution failures."""
+
+    def __init__(
+        self,
+        message,
+        status_code=None,
+        error_code=None,
+        response=None,
+        identifier=None,
+        details=None,
+    ):
+        super().__init__(
+            message,
+            status_code=status_code,
+            error_code=error_code,
+            response=response,
+        )
+        self.identifier = identifier
+        self.details = details or {}
+
+
+class SahmkAmbiguousIdentifierError(SahmkIdentifierResolutionError):
+    """Raised when the input maps to multiple possible stocks."""
+
+    def __init__(
+        self,
+        message,
+        response=None,
+        identifier=None,
+        candidates=None,
+        details=None,
+        status_code=400,
+        error_code="AMBIGUOUS_IDENTIFIER",
+    ):
+        merged_details = dict(details or {})
+        if candidates is not None:
+            merged_details.setdefault("candidates", candidates)
+        super().__init__(
+            message,
+            status_code=status_code,
+            error_code=error_code,
+            response=response,
+            identifier=identifier,
+            details=merged_details,
+        )
+        self.candidates = merged_details.get("candidates", [])
+
+
+class SahmkUnknownIdentifierError(SahmkIdentifierResolutionError):
+    """Raised when an identifier cannot be resolved to any stock."""
+
+    def __init__(
+        self,
+        message,
+        response=None,
+        identifier=None,
+        details=None,
+        status_code=404,
+        error_code="UNKNOWN_IDENTIFIER",
+    ):
+        super().__init__(
+            message,
+            status_code=status_code,
+            error_code=error_code,
+            response=response,
+            identifier=identifier,
+            details=details,
+        )
+
+
 class SahmkClient:
     """
     SAHMK Developer API client.
@@ -223,11 +294,14 @@ def _header_int(name):
     @staticmethod
     def _build_api_error(response):
         """Build a SahmkError from a non-200 response."""
+        details = {}
         try:
             body = response.json()
             err = body.get("error", {})
             code = err.get("code", "UNKNOWN")
             message = err.get("message", response.text)
+            if isinstance(err.get("details"), dict):
+                details = err.get("details")
         except (ValueError, KeyError):
             code = "UNKNOWN"
             message = response.text
@@ -236,6 +310,31 @@ def _build_api_error(response):
                 f"Invalid market index: {message}",
                 response=response,
             )
+        identifier = details.get("identifier") or details.get("input")
+        if code in {"AMBIGUOUS_IDENTIFIER", "IDENTIFIER_AMBIGUOUS"}:
+            candidates = details.get("candidates", [])
+            candidate_text = ""
+            if candidates:
+                shown = candidates[:5]
+                candidate_text = f" Candidates: {shown}"
+            return SahmkAmbiguousIdentifierError(
+                f"Ambiguous identifier '{identifier or '?'}': {message}.{candidate_text}",
+                response=response,
+                identifier=identifier,
+                candidates=candidates,
+                details=details,
+                status_code=response.status_code,
+                error_code=code,
+            )
+        if code in {"UNKNOWN_IDENTIFIER", "IDENTIFIER_NOT_FOUND", "INVALID_SYMBOL"}:
+            return SahmkUnknownIdentifierError(
+                f"Unknown identifier '{identifier or '?'}': {message}",
+                response=response,
+                identifier=identifier,
+                details=details,
+                status_code=response.status_code,
+                error_code=code,
+            )
         return SahmkError(
             f"API error {response.status_code}: {message}",
             status_code=response.status_code,
@@ -280,38 +379,67 @@ def _market_params(self, limit=None, index=None):
     # Quotes
     # -------------------------------------------------------------------------
 
-    def quote(self, symbol):
+    def quote(self, identifier):
         """
-        Get a stock quote.
+        Get a stock quote by symbol or resolvable identifier.
 
         Args:
-            symbol: Stock symbol (e.g., "2222" for Aramco)
+            identifier: Stock symbol, Arabic name, English name, or alias
+                        (e.g., "2222", "أرامكو السعودية", "Aramco")
 
         Returns:
             Quote object (supports dict-style access via [] for backwards compat)
         """
         from .models import Quote
-        data = self._request("GET", f"/quote/{symbol}/")
+        data = self._request("GET", f"/quote/{identifier}/")
         return Quote.from_dict(data)
 
-    def quotes(self, symbols):
+    @staticmethod
+    def _is_legacy_quotes_param_error(exc):
+        """Detect old-backend validation errors when identifiers param is unknown."""
+        if not isinstance(exc, SahmkError) or exc.status_code != 400:
+            return False
+        if exc.error_code in {
+            "VALIDATION",
+            "MISSING_SYMBOLS",
+            "MISSING_PARAMETER",
+            "UNKNOWN_PARAMETER",
+        }:
+            return True
+        return "symbols" in str(exc).lower()
+
+    def quotes(self, identifiers):
         """
         Get batch quotes for multiple stocks (Starter+ plan).
 
         Args:
-            symbols: List of stock symbols (up to 50)
+            identifiers: List of symbols/names/aliases (up to 50). Existing
+                         symbol-only usage remains fully supported.
 
         Returns:
             BatchQuotesResponse with .quotes list and .count
         """
         from .models import BatchQuotesResponse
-        if not symbols:
+        if isinstance(identifiers, str):
+            identifiers = [identifiers]
+        if not identifiers:
             raise ValueError("At least one symbol is required")
-        if len(symbols) > 50:
+        if len(identifiers) > 50:
             raise SahmkError("Maximum 50 symbols per batch request")
-        data = self._request(
-            "GET", "/quotes/", params={"symbols": ",".join(symbols)}
-        )
+        joined = ",".join(str(identifier) for identifier in identifiers)
+
+        # Prefer the new backend contract first. If the backend is older and
+        # rejects `identifiers`, transparently fall back to `symbols`.
+        try:
+            data = self._request(
+                "GET",
+                "/quotes/",
+                params={"identifiers": joined},
+            )
+        except SahmkError as exc:
+            if not self._is_legacy_quotes_param_error(exc):
+                raise
+            data = self._request("GET", "/quotes/", params={"symbols": joined})
         return BatchQuotesResponse.from_dict(data)
 
     # -------------------------------------------------------------------------