wiz-trader 0.30.0__py3-none-any.whl → 0.31.0__py3-none-any.whl

wiz_trader/__init__.py

@@ -3,6 +3,6 @@
 from .quotes import QuotesClient
 from .apis import WizzerClient
 
-__version__ = "0.30.0"
+__version__ = "0.31.0"
 
 __all__ = ["QuotesClient", "WizzerClient"]

wiz_trader/apis/client.py

@@ -205,7 +205,11 @@ class WizzerClient:
     "indices.filter": "/datahub/indices/filter",
     "instruments.filter": "/datahub/instruments/filter",
     "instruments.filter_with_index": "/datahub/indices/{id}/instruments",
-    "instruments.filter_by_derivatives": "/datahub/instruments/filter-by-derivatives"
+    "instruments.filter_by_derivatives": "/datahub/instruments/filter-by-derivatives",
+    
+    # Screener API endpoints
+    "screener.run": "/datahub/screener",
+    "screener.fields": "/datahub/screener/metadata"
   }
   
   def __init__(
@@ -1709,9 +1713,47 @@ class WizzerClient:
     logger.debug(f"Filtering instruments by derivatives with payload: {data}")
     return self._make_request("POST", endpoint, json=data)
 
+  def run_screener(
+    self,
+    filters: Dict[str, Any],
+    sort: Optional[List[Dict[str, int]]] = None,
+    limit: Optional[int] = None,
+  ) -> List[Dict[str, Any]]:
+    """
+    Run an instrument screener with specified filters.
+
+    Args:
+      filters (Dict[str, Any]): The filter conditions for the screener.
+      sort (Optional[List[Dict[str, int]]]): The sort order for the results.
+      limit (Optional[int]): The maximum number of results to return.
+      
+    Returns:
+      List[Dict[str, Any]]: A list of instruments that match the screener criteria.
+    """
+    endpoint = self._routes["screener.run"]
+    data = {"filters": filters}
+    if sort is not None:
+        data["sort"] = sort
+    if limit is not None:
+        data["limit"] = limit
+        
+    logger.debug(f"Running screener with payload: {data}")
+    return self._make_request("POST", endpoint, json=data)
+
+  def get_screener_fields(self) -> List[Dict[str, Any]]:
+    """
+    Get the list of available fields and supported operations for the screener.
+
+    Returns:
+      List[Dict[str, Any]]: A list of available screener fields.
+    """
+    endpoint = self._routes["screener.fields"]
+    logger.debug("Fetching screener fields.")
+    return self._make_request("GET", endpoint)
+
   def _make_request(
-    self, 
-    method: str, 
+    self,
+    method: str,
     endpoint: str, 
     params: Optional[Dict[str, str]] = None, 
     json: Optional[Dict[str, Any]] = None,

{wiz_trader-0.30.0.dist-info → wiz_trader-0.31.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wiz_trader
-Version: 0.30.0
+Version: 0.31.0
 Summary: A Python SDK for connecting to the Wizzer.
 Home-page: https://bitbucket.org/wizzer-tech/quotes_sdk.git
 Author: Pawan Wagh
@@ -543,6 +543,152 @@ fno_stocks = client.filter_instruments_by_derivatives(hasOptions=True, hasFuture
 all_derivative_stocks = client.filter_instruments_by_derivatives()
 ```
 
+### Instrument Screener
+
+The SDK provides a powerful instrument screener to filter and sort instruments based on a wide range of criteria using a simple and expressive Domain Specific Language (DSL).
+
+#### `get_screener_fields()`
+
+This method returns a list of all available filterable fields and their supported operations.
+
+```python
+# Get all available screener fields
+fields = client.get_screener_fields()
+print(json.dumps(fields, indent=2))
+```
+
+#### `run_screener(filters, sort=None, limit=None, as_of=None)`
+
+This is the main method for the instrument screener. It accepts a dictionary with a `filters` object to define the screening criteria.
+
+**Arguments:**
+
+*   `filters` (dict, required): An object containing the filter conditions.
+*   `sort` (list, optional): A list of objects to define the sort order.
+*   `limit` (int, optional): The maximum number of results to return.
+
+#### Filter DSL (Domain Specific Language)
+
+The `filters` object uses a simple DSL to define the screening criteria.
+
+##### Operators
+
+| Operator  | Description              | Example                               |
+| :-------- | :----------------------- | :------------------------------------ |
+| `$eq`     | Equal to                 | `{ "sector": { "$eq": "Finance" } }`  |
+| `$ne`     | Not equal to             | `{ "sector": { "$ne": "Finance" } }`  |
+| `$gt`     | Greater than             | `{ "roe": { "$gt": 0.15 } }`          |
+| `$gte`    | Greater than or equal to | `{ "roe": { "$gte": 0.15 } }`         |
+| `$lt`     | Less than                | `{ "roe": { "$lt": 0.15 } }`          |
+| `$lte`    | Less than or equal to    | `{ "roe": { "$lte": 0.15 } }`         |
+| `$in`     | In a list of values    | `{ "sector": { "$in": ["Information Technology", "Finance"] } }` |
+| `$nin`    | Not in a list of values| `{ "sector": { "$nin": ["Information Technology", "Finance"] } }` |
+| `$like`   | Like (case-sensitive)    | `{ "companyName": { "$like": "%Bank%" } }` |
+| `$nlike`  | Not like (case-sensitive)| `{ "companyName": { "$nlike": "%Bank%" } }` |
+| `$ilike`  | Like (case-insensitive)  | `{ "companyName": { "$ilike": "%bank%" } }` |
+| `$between`| Between two values       | `{ "roe": { "$between": [0.10, 0.20] } }` |
+
+##### Logical Operators
+
+*   `$and`: A list of filter conditions that must all be true.
+*   `$or`: A list of filter conditions where at least one must be true.
+
+#### Screener Examples
+
+##### Basic Filters
+
+1.  **Find all instruments in the 'Finance' sector.**
+    ```python
+    client.run_screener(filters={"sector": {"$eq": "Finance"}})
+    ```
+
+2.  **Find all instruments on the 'NSE' exchange.**
+    ```python
+    client.run_screener(filters={"exchange": {"$eq": "NSE"}})
+    ```
+
+3.  **Find all instruments with a Return on Equity (ROE) greater than 15%.**
+    ```python
+    client.run_screener(filters={"roe": {"$gt": 0.15}})
+    ```
+
+##### Set and Range Operators
+
+4.  **Find all instruments in the 'Energy' or 'Healthcare' sectors.**
+    ```python
+    client.run_screener(filters={"sector": {"$in": ["Energy", "Healthcare"]}})
+    ```
+
+5.  **Find instruments with a PAT Margin between 5% and 10%.**
+    ```python
+    client.run_screener(filters={"patMargin": {"$between": [0.05, 0.10]}})
+    ```
+
+##### Pattern Matching
+
+6.  **Find all instruments with 'Bank' in their name (case-insensitive).**
+    ```python
+    client.run_screener(filters={"companyName": {"$ilike": "%bank%"}})
+    ```
+
+##### Logical Combinations
+
+7.  **Find instruments in the 'IT' sector with a ROE greater than 20%.**
+    ```python
+    client.run_screener(
+        filters={
+            "$and": [
+                {"sector": {"$eq": "Information Technology"}},
+                {"roe": {"$gt": 0.20}}
+            ]
+        }
+    )
+    ```
+
+8.  **Complex Nested Query:** Find instruments in the 'Automobile' sector that have (a ROE > 18% AND a low Debt/Equity) OR have a high Asset Turnover.
+    ```python
+    client.run_screener(
+        filters={
+            "$and": [
+                {"sector": {"$eq": "Automobile"}},
+                {
+                    "$or": [
+                        {
+                            "$and": [
+                                {"roe": {"$gt": 0.18}},
+                                {"debtEquity": {"$lt": 0.3}}
+                            ]
+                        },
+                        {"assetTurnover": {"$gt": 1.5}}
+                    ]
+                }
+            ]
+        }
+    )
+    ```
+
+##### Sort and Limit
+
+9.  **Find the top 10 companies by highest ROE.**
+    ```python
+    client.run_screener(
+        filters={},
+        sort=[{"roe": -1}],
+        limit=10
+    )
+    ```
+
+10. **Find companies in the 'Pharmaceuticals' sector, sort them by the highest PAT margin, and then by the lowest Debt-to-Equity ratio.**
+    ```python
+    client.run_screener(
+        filters={"sector": {"$eq": "Pharmaceuticals"}},
+        sort=[
+            {"patMargin": -1},
+            {"debtEquity": 1}
+        ]
+    )
+    ```
+
 #### Get Historical OHLCV Data
 ## Overview
 
@@ -3132,3 +3278,89 @@ All supported environment variables:
 |  |  |  | Multi Utilities |
 |  |  |  | Other Utilities |
 | Diversified | Diversified | Diversified | Diversified |
+
+## Available Screener Fields
+
+The screener supports filtering instruments using various financial, technical, and fundamental data points. Use `client.get_screener_fields()` to get the complete list of available fields with their metadata.
+
+### Instrument Properties
+
+| Field | Description | Data Type | Supported Operations |
+|-------|-------------|-----------|---------------------|
+| `exchange` | Stock exchange where the instrument is traded | String | `$eq`, `$ne`, `$in`, `$nin`, `$like`, `$nlike`, `$ilike` |
+| `tradingSymbol` | Trading symbol of the instrument | String | `$eq`, `$ne`, `$in`, `$nin`, `$like`, `$nlike`, `$ilike` |
+| `macroEconomicSector` | Macro economic sector classification | String | `$eq`, `$ne`, `$in`, `$nin`, `$like`, `$nlike`, `$ilike` |
+| `sector` | Sector classification | String | `$eq`, `$ne`, `$in`, `$nin`, `$like`, `$nlike`, `$ilike` |
+| `industry` | Industry classification | String | `$eq`, `$ne`, `$in`, `$nin`, `$like`, `$nlike`, `$ilike` |
+| `basicIndustry` | Basic industry classification | String | `$eq`, `$ne`, `$in`, `$nin`, `$like`, `$nlike`, `$ilike` |
+| `indices` | List of indices the instrument belongs to | Array(String) | `$in`, `$nin` |
+
+### Financial Data
+
+| Field | Description | Data Type | Unit | Supported Operations |
+|-------|-------------|-----------|------|---------------------|
+| `reportDate` | Date of the financial report | Date | - | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `companyName` | Company name | String | - | `$eq`, `$ne`, `$like`, `$nlike`, `$ilike` |
+| `period` | Financial reporting period (Q1, Q2, Q3, Q4, FY) | String | - | `$eq`, `$ne`, `$in`, `$nin` |
+| `filingDate` | Date when the report was filed | Date | - | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `natureOfReport` | Type of financial report (Annual, Quarterly, etc.) | String | - | `$eq`, `$ne`, `$in`, `$nin` |
+| `auditedUnaudited` | Audited or Unaudited status of the financial report | String | - | `$eq`, `$ne`, `$in`, `$nin` |
+
+### Financial Ratios
+
+| Field | Description | Data Type | Unit | Supported Operations |
+|-------|-------------|-----------|------|---------------------|
+| `roe` | Return on Equity | Float | % | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `patMargin` | Profit After Tax Margin | Float | % | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `debtEquity` | Debt to Equity Ratio | Float | ratio | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `ocfPat` | Operating Cash Flow to PAT Ratio | Float | ratio | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `gnpaPct` | Gross Non-Performing Assets Percentage | Float | % | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `interestCov` | Interest Coverage Ratio | Float | ratio | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `assetTurnover` | Asset Turnover Ratio | Float | ratio | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `netCash` | Net Cash Position | Float | currency | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `currentRatio` | Current Ratio | Float | ratio | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+
+### Historical Market Data
+
+| Field | Description | Data Type | Unit | Supported Operations |
+|-------|-------------|-----------|------|---------------------|
+| `hmdOpen` | Opening price of the trading session | Float | currency | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `hmdHigh` | Highest price during the trading session | Float | currency | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `hmdLow` | Lowest price during the trading session | Float | currency | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `hmdClose` | Closing price of the trading session | Float | currency | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `hmdLtp` | Last Traded Price | Float | currency | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `hmdPrevClose` | Previous day closing price | Float | currency | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `hmdVolume` | Trading volume (number of shares traded) | UInt64 | shares | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `hmdTurnover` | Trading turnover (total value of shares traded) | Float | currency | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `hmdTotalTrades` | Total number of trades executed | UInt64 | count | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `hmdPriceBandLower` | Lower price band limit | Float | currency | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `hmdPriceBandUpper` | Upper price band limit | Float | currency | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+| `hmdDate` | Trading date | Date | - | `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$between` |
+
+### Supported Operations
+
+- **Comparison**: `$eq` (equal), `$ne` (not equal), `$gt` (greater than), `$gte` (greater than or equal), `$lt` (less than), `$lte` (less than or equal)
+- **Range**: `$between` (between two values)
+- **Array**: `$in` (in array), `$nin` (not in array)
+- **Pattern**: `$like` (case-sensitive pattern), `$nlike` (case-sensitive not pattern), `$ilike` (case-insensitive pattern)
+- **Logical**: `$and` (all conditions must be true), `$or` (at least one condition must be true)
+
+### Example Usage
+
+```python
+# Get all available screener fields
+fields = client.get_screener_fields()
+print(json.dumps(fields, indent=2))
+
+# Screen for high ROE companies in Finance sector
+results = client.run_screener(
+    filters={
+        "$and": [
+            {"sector": {"$eq": "Finance"}},
+            {"roe": {"$gt": 0.15}}
+        ]
+    },
+    sort=[{"roe": -1}],
+    limit=10
+)
+```

wiz_trader-0.31.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+wiz_trader/__init__.py,sha256=JENNr-G__7-zFCQkA3DrG98uvCmkOU8rssu31GnJxgA,183
+wiz_trader/apis/__init__.py,sha256=6sUr1nzmplNdld0zryMrQSt0jHT2GhOiFYgKKVHzk8U,133
+wiz_trader/apis/client.py,sha256=WzsKxrNi9T-xbtXWBT2J41bJ-sz0KsGFYV5Oyddo3gg,65487
+wiz_trader/quotes/__init__.py,sha256=RF9g9CNP6bVWlmCh_ad8krm3-EWOIuVfLp0-H9fAeEM,108
+wiz_trader/quotes/client.py,sha256=aZ5LVlrj0mKfgHgFxERmk2HDZraB6RMaormTOMlqWZc,14915
+wiz_trader-0.31.0.dist-info/METADATA,sha256=egRqWuYOGalAtWDGOlsjfxkl5RTg86--hDaJO8mjUTc,110671
+wiz_trader-0.31.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+wiz_trader-0.31.0.dist-info/top_level.txt,sha256=lnYS_g8LlA6ryKYnvY8xIQ6K2K-xzOsd-99AWgnW6VY,11
+wiz_trader-0.31.0.dist-info/RECORD,,

wiz_trader-0.30.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-wiz_trader/__init__.py,sha256=DqIoZxsr_Z6oAU4tha4WcQHVr0KmX5cSc8W_9z6JHt4,183
-wiz_trader/apis/__init__.py,sha256=6sUr1nzmplNdld0zryMrQSt0jHT2GhOiFYgKKVHzk8U,133
-wiz_trader/apis/client.py,sha256=gWTv6GW0zFyQCNGo0Q_vAfF91H6Ec84AWDVHQZPXdq8,64100
-wiz_trader/quotes/__init__.py,sha256=RF9g9CNP6bVWlmCh_ad8krm3-EWOIuVfLp0-H9fAeEM,108
-wiz_trader/quotes/client.py,sha256=aZ5LVlrj0mKfgHgFxERmk2HDZraB6RMaormTOMlqWZc,14915
-wiz_trader-0.30.0.dist-info/METADATA,sha256=-7GKukzGeoecYLN6oLeLa3q0PylFwqQzh6VLnduwhc8,99947
-wiz_trader-0.30.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-wiz_trader-0.30.0.dist-info/top_level.txt,sha256=lnYS_g8LlA6ryKYnvY8xIQ6K2K-xzOsd-99AWgnW6VY,11
-wiz_trader-0.30.0.dist-info/RECORD,,