aspy21 0.2.0b2__tar.gz → 0.2.0b4__tar.gz

{aspy21-0.2.0b2 → aspy21-0.2.0b4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aspy21
-Version: 0.2.0b2
+Version: 0.2.0b4
 Summary: Modern Python client for Aspen InfoPlus.21 (IP.21) with pandas DataFrame output, tag search, and automatic retry logic
 Author: bazdalaz
 Maintainer-email: bazdalaz <bazdalaz@users.noreply.github.com>

{aspy21-0.2.0b2 → aspy21-0.2.0b4}/examples/search_and_read.py

@@ -3,6 +3,7 @@
 import os
 from pathlib import Path
 
+import pandas as pd
 from dotenv import load_dotenv
 
 from aspy21 import AspenClient, ReaderType, configure_logging
@@ -50,17 +51,25 @@ try:
         print("Searching for temperature tags...")
 
         # Get list of tag names matching pattern
-        tag_names = client.search(tag="TEMP*", return_desc=False, max_results=5)
+        tag_names_result = client.search(tag="TEMP*", return_desc=False, max_results=5)
+        # Type narrowing: return_desc=False guarantees list[str]
+        assert isinstance(tag_names_result, list) and (
+            not tag_names_result or isinstance(tag_names_result[0], str)
+        )
+        tag_names: list[str] = tag_names_result  # type: ignore[assignment]
         print(f"Found {len(tag_names)} tags: {tag_names}")
 
         if tag_names:
             print("\nReading last hour of data...")
-            df = client.read(
+            result = client.read(
                 tags=tag_names,
                 start="2025-01-31 08:00:00",
                 end="2025-01-31 09:00:00",
                 read_type=ReaderType.RAW,
             )
+            # Type narrowing: as_json=False (default) guarantees pd.DataFrame
+            assert isinstance(result, pd.DataFrame)
+            df: pd.DataFrame = result
 
             print(f"Data shape: {df.shape}")
             print(f"\nFirst few rows:\n{df.head()}")
@@ -72,7 +81,12 @@ try:
         print("Searching for reactor tags...")
 
         # Get tags with descriptions for display/logging
-        tags = client.search(tag="*", description="reactor", max_results=5)
+        tags_result = client.search(tag="*", description="reactor", max_results=5)
+        # Type narrowing: return_desc=True (default) guarantees list[dict[str, str]]
+        assert isinstance(tags_result, list) and (
+            not tags_result or isinstance(tags_result[0], dict)
+        )
+        tags: list[dict[str, str]] = tags_result  # type: ignore[assignment]
 
         print(f"Found {len(tags)} tags:")
         for tag in tags:
@@ -80,16 +94,19 @@ try:
 
         if tags:
             # Extract just the names for reading
-            tag_names = [tag["name"] for tag in tags]
+            tag_names_list = [tag["name"] for tag in tags]
 
             print("\nReading 10-minute averages...")
-            df = client.read(
-                tags=tag_names,
+            result = client.read(
+                tags=tag_names_list,
                 start="2025-01-31 08:00:00",
                 end="2025-01-31 09:00:00",
                 read_type=ReaderType.AVG,
                 interval=600,  # 10 minute averages
             )
+            # Type narrowing: as_json=False (default) guarantees pd.DataFrame
+            assert isinstance(result, pd.DataFrame)
+            df: pd.DataFrame = result
 
             print(f"Data shape: {df.shape}")
             print(f"\nFirst few rows:\n{df.head()}")
@@ -101,18 +118,26 @@ try:
         print("Searching for all V1-01 tags...")
 
         # Find all tags related to V1-01
-        tag_names = client.search(description="V1-01", return_desc=False, max_results=10)
-        print(f"Found {len(tag_names)} tags: {tag_names[:5]}...")
-
-        if tag_names:
+        tag_names_result2 = client.search(description="V1-01", return_desc=False, max_results=10)
+        # Type narrowing: return_desc=False guarantees list[str]
+        assert isinstance(tag_names_result2, list) and (
+            not tag_names_result2 or isinstance(tag_names_result2[0], str)
+        )
+        tag_names_v101: list[str] = tag_names_result2  # type: ignore[assignment]
+        print(f"Found {len(tag_names_v101)} tags: {tag_names_v101[:5]}...")
+
+        if tag_names_v101:
             print("\nReading hourly averages...")
-            df = client.read(
-                tags=tag_names[:5],  # Limit to first 5 tags for demo
+            result = client.read(
+                tags=tag_names_v101[:5],  # Limit to first 5 tags for demo
                 start="2025-01-31 00:00:00",
                 end="2025-01-31 12:00:00",
                 read_type=ReaderType.AVG,
                 interval=3600,  # 1 hour averages
             )
+            # Type narrowing: as_json=False (default) guarantees pd.DataFrame
+            assert isinstance(result, pd.DataFrame)
+            df: pd.DataFrame = result
 
             print(f"Data shape: {df.shape}")
             print(f"\nFirst few rows:\n{df.head()}")
@@ -124,7 +149,12 @@ try:
         print("Searching for all G* tags with V1-01 in description...")
 
         # Search broadly
-        all_tags = client.search(tag="G*", description="V1-01", max_results=20)
+        all_tags_result = client.search(tag="G*", description="V1-01", max_results=20)
+        # Type narrowing: return_desc=True (default) guarantees list[dict[str, str]]
+        assert isinstance(all_tags_result, list) and (
+            not all_tags_result or isinstance(all_tags_result[0], dict)
+        )
+        all_tags: list[dict[str, str]] = all_tags_result  # type: ignore[assignment]
         print(f"Found {len(all_tags)} tags total")
 
         # Filter to only temperature and pressure tags
@@ -140,12 +170,15 @@ try:
 
         if selected_tags:
             print("\nReading raw data...")
-            df = client.read(
+            result = client.read(
                 tags=selected_tags[:3],  # Limit to first 3 for demo
                 start="2025-01-31 08:00:00",
                 end="2025-01-31 09:00:00",
                 read_type=ReaderType.RAW,
             )
+            # Type narrowing: as_json=False (default) guarantees pd.DataFrame
+            assert isinstance(result, pd.DataFrame)
+            df: pd.DataFrame = result
 
             print(f"Data shape: {df.shape}")
             print(f"\nFirst few rows:\n{df.head()}")

{aspy21-0.2.0b2 → aspy21-0.2.0b4}/examples/search_tags.py

@@ -47,7 +47,10 @@ try:
         # Example 1: Search by tag name pattern with wildcards
         print("Example 1: Search all tags starting with 'TEMP'")
         print("-" * 80)
-        tags = client.search(tag="TEMP*", max_results=10)
+        tags_raw = client.search(tag="TEMP*", max_results=10)
+        # Type narrowing: return_desc=True (default) guarantees list[dict[str, str]]
+        assert isinstance(tags_raw, list) and (not tags_raw or isinstance(tags_raw[0], dict))
+        tags: list[dict[str, str]] = tags_raw  # type: ignore[assignment]
         print(f"Found {len(tags)} tags:\n")
         for tag in tags[:5]:  # Show first 5
             print(f"  {tag['name']:30} - {tag['description']}")
@@ -56,7 +59,10 @@ try:
         # Example 2: Search by description only (uses SQL endpoint)
         print("Example 2: Search all tags with description containing 'V1-01'")
         print("-" * 80)
-        tags = client.search(description="V1-01", max_results=10)
+        tags_raw = client.search(description="V1-01", max_results=10)
+        # Type narrowing: return_desc=True (default) guarantees list[dict[str, str]]
+        assert isinstance(tags_raw, list) and (not tags_raw or isinstance(tags_raw[0], dict))
+        tags: list[dict[str, str]] = tags_raw  # type: ignore[assignment]
         print(f"Found {len(tags)} tags:\n")
         for tag in tags[:5]:
             print(f"  {tag['name']:30} - {tag['description']}")
@@ -65,7 +71,10 @@ try:
         # Example 3: Combine tag pattern and description
         print("Example 3: Search 'AI*' tags with 'temperature' in description")
         print("-" * 80)
-        tags = client.search(tag="AI*", description="temperature", max_results=10)
+        tags_raw = client.search(tag="AI*", description="temperature", max_results=10)
+        # Type narrowing: return_desc=True (default) guarantees list[dict[str, str]]
+        assert isinstance(tags_raw, list) and (not tags_raw or isinstance(tags_raw[0], dict))
+        tags: list[dict[str, str]] = tags_raw  # type: ignore[assignment]
         print(f"Found {len(tags)} tags:\n")
         for tag in tags[:5]:
             print(f"  {tag['name']:30} - {tag['description']}")
@@ -83,7 +92,10 @@ try:
         # Example 5: Case-insensitive search (default)
         print("Example 5: Case-insensitive search (lowercase query)")
         print("-" * 80)
-        tags = client.search(tag="*", description="reactor", max_results=5)
+        tags_raw = client.search(tag="*", description="reactor", max_results=5)
+        # Type narrowing: return_desc=True (default) guarantees list[dict[str, str]]
+        assert isinstance(tags_raw, list) and (not tags_raw or isinstance(tags_raw[0], dict))
+        tags: list[dict[str, str]] = tags_raw  # type: ignore[assignment]
         print(f"Found {len(tags)} tags (matches 'Reactor', 'REACTOR', etc.):\n")
         for tag in tags[:5]:
             print(f"  {tag['name']:30} - {tag['description']}")

{aspy21-0.2.0b2 → aspy21-0.2.0b4}/src/aspy21/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.0b2'
-__version_tuple__ = version_tuple = (0, 2, 0, 'b2')
+__version__ = version = '0.2.0b4'
+__version_tuple__ = version_tuple = (0, 2, 0, 'b4')
 
-__commit_id__ = commit_id = 'gfe38a9fe3'
+__commit_id__ = commit_id = 'gb96f5454a'

{aspy21-0.2.0b2 → aspy21-0.2.0b4}/src/aspy21/client.py

@@ -12,7 +12,7 @@ import pandas as pd
 from tenacity import retry, stop_after_attempt, wait_exponential
 
 from .models import ReaderType
-from .query_builder import build_read_query, build_sql_search_query
+from .query_builder import build_history_sql_query, build_read_query, build_sql_search_query
 
 if TYPE_CHECKING:
     from httpx import Auth
@@ -128,6 +128,56 @@ class AspenClient:
         """Close the HTTP client connection."""
         self._client.close()
 
+    def _parse_sql_history_response(
+        self, response: list[dict], tag_name: str
+    ) -> tuple[pd.DataFrame, str]:
+        """Parse SQL history response into DataFrame.
+
+        Args:
+            response: SQL response as list of record dictionaries
+            tag_name: Name of the tag being queried
+
+        Returns:
+            Tuple of (DataFrame with timestamp index and tag data, tag description)
+
+        SQL response format:
+        [
+            {"ts": "2025-11-02T00:00:00.000000Z", "name": "TAG",
+             "name->ip_description": "desc", "value": 22.85},
+            ...
+        ]
+        """
+        try:
+            if not response or not isinstance(response, list):
+                logger.warning(f"No data in SQL response for tag {tag_name}")
+                return pd.DataFrame(), ""
+
+            # Extract description from first record if available
+            description = ""
+            if response and "name->ip_description" in response[0]:
+                description = response[0]["name->ip_description"] or ""
+
+            # Build DataFrame from records
+            rows = []
+            for record in response:
+                timestamp = pd.to_datetime(record["ts"])
+                value = record["value"]
+                rows.append({"time": timestamp, tag_name: value})
+
+            if not rows:
+                logger.warning(f"No valid data in SQL response for tag {tag_name}")
+                return pd.DataFrame(), description
+
+            df = pd.DataFrame(rows)
+            df = df.set_index("time")
+
+            return df, description
+
+        except Exception as e:
+            logger.error(f"Error parsing SQL response for tag {tag_name}: {e}")
+            logger.debug(f"Response was: {response}")
+            return pd.DataFrame(), ""
+
     def _parse_aspen_response(
         self, response: dict, tag_name: str, include_status: bool = True
     ) -> tuple[pd.DataFrame, str]:
@@ -284,7 +334,7 @@ class AspenClient:
             max_rows: Maximum number of rows to return per tag (default: 100000)
             as_json: Return data as list of dictionaries instead of DataFrame (default: False)
             with_description: Include tag descriptions in response (default: False).
-                             Automatically enabled when as_json=True.
+                             Note: Some Aspen servers may not support this field.
 
         Returns:
             If as_json=False: pandas DataFrame with time index and columns for each tag.
@@ -326,30 +376,67 @@ class AspenClient:
         frames: list[pd.DataFrame] = []
         tag_descriptions: dict[str, str] = {}
 
+        # Determine if we should use SQL endpoint (for RAW/INT with datasource configured)
+        use_sql = read_type in (ReaderType.RAW, ReaderType.INT) and self.datasource
+
+        if use_sql:
+            logger.debug(f"Using SQL endpoint for {read_type.value} read")
+        else:
+            logger.debug(f"Using XML endpoint for {read_type.value} read")
+
         # Process each tag individually (Aspen API queries one tag at a time)
         for tag_idx, tag in enumerate(tags_list, 1):
             logger.debug(f"Processing tag {tag_idx}/{len(tags_list)}: {tag}")
 
-            # Generate XML query for this tag
-            xml_query = build_read_query(
-                tag=tag,
-                start=start,
-                end=end,
-                read_type=read_type,
-                interval=interval,
-                datasource=self.datasource,
-                max_rows=max_rows,
-                with_description=with_description or as_json,  # Request description if needed
-            )
-
-            response = self._fetch(xml_query)
-            logger.debug(f"Received response for tag: {tag}")
+            if use_sql:
+                # Use SQL endpoint for historical data
+                xml_query = build_history_sql_query(
+                    tag=tag,
+                    start=start,
+                    end=end,
+                    datasource=self.datasource,
+                    max_rows=max_rows,
+                    with_description=with_description or as_json,
+                )
+
+                sql_url = f"{self.base_url}/SQL"
+                logger.debug(f"POST {sql_url}")
+                logger.debug(f"SQL query XML: {xml_query}")
+
+                response = self._client.post(
+                    sql_url, content=xml_query, headers={"Content-Type": "text/xml"}
+                )
+                response.raise_for_status()
+                sql_response = response.json()
+
+                logger.debug(f"SQL response type: {type(sql_response)}")
+                logger.debug(f"SQL response: {sql_response}")
+
+                # Parse SQL response (simple JSON array)
+                df, description = self._parse_sql_history_response(sql_response, tag)
+                logger.debug(f"Parsed {len(df)} data points for tag {tag}")
 
-            # Parse the Aspen-style response
-            df, description = self._parse_aspen_response(
-                response, tag, include_status=include_status
-            )
-            logger.debug(f"Parsed {len(df)} data points for tag {tag}")
+            else:
+                # Use original XML endpoint for other read types
+                xml_query = build_read_query(
+                    tag=tag,
+                    start=start,
+                    end=end,
+                    read_type=read_type,
+                    interval=interval,
+                    datasource=self.datasource,
+                    max_rows=max_rows,
+                    with_description=with_description,
+                )
+
+                response = self._fetch(xml_query)
+                logger.debug(f"Received response for tag: {tag}")
+
+                # Parse the Aspen-style response
+                df, description = self._parse_aspen_response(
+                    response, tag, include_status=include_status
+                )
+                logger.debug(f"Parsed {len(df)} data points for tag {tag}")
 
             if not df.empty:
                 frames.append(df)

{aspy21-0.2.0b2 → aspy21-0.2.0b4}/src/aspy21/query_builder.py

@@ -77,6 +77,57 @@ def build_read_query(
     return xml
 
 
+def build_history_sql_query(
+    tag: str,
+    start: str,
+    end: str,
+    datasource: str,
+    max_rows: int = 100000,
+    with_description: bool = True,
+) -> str:
+    """Generate SQL query for historical data read.
+
+    Args:
+        tag: Tag name
+        start: Start timestamp (ISO format)
+        end: End timestamp (ISO format)
+        datasource: Aspen datasource name
+        max_rows: Maximum number of rows to return
+        with_description: Include ip_description field in response
+
+    Returns:
+        XML query string for SQL endpoint
+    """
+    # Convert timestamps to Aspen SQL format (DD-MMM-YY)
+    start_dt = pd.to_datetime(start)
+    end_dt = pd.to_datetime(end)
+    start_sql = start_dt.strftime("%d-%b-%y")
+    end_sql = end_dt.strftime("%d-%b-%y")
+
+    # Build SELECT clause
+    if with_description:
+        select_fields = "ts, name, name->ip_description, value"
+    else:
+        select_fields = "ts, name, value"
+
+    # Build SQL query
+    sql_query = (
+        f"Select {select_fields} from history "
+        f"where name = '{tag}' and ts between '{start_sql}' and '{end_sql}'"
+    )
+
+    # Build XML request for SQL endpoint
+    xml = (
+        f'<SQL g="aspy21_history" t="SQLplus" ds="{datasource}" '
+        f'dso="CHARINT=N;CHARFLOAT=N;CHARTIME=N;CONVERTERRORS=N" '
+        f'm="{max_rows}" to="30" response="Record" s="1">'
+        f"<![CDATA[{sql_query}]]>"
+        f"</SQL>"
+    )
+
+    return xml
+
+
 def build_sql_search_query(
     datasource: str,
     description: str,

{aspy21-0.2.0b2 → aspy21-0.2.0b4}/src/aspy21.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aspy21
-Version: 0.2.0b2
+Version: 0.2.0b4
 Summary: Modern Python client for Aspen InfoPlus.21 (IP.21) with pandas DataFrame output, tag search, and automatic retry logic
 Author: bazdalaz
 Maintainer-email: bazdalaz <bazdalaz@users.noreply.github.com>

{aspy21-0.2.0b2 → aspy21-0.2.0b4}/tests/test_client.py

@@ -214,12 +214,19 @@ def test_aggregated_read_with_interval(mock_api):
 
 
 def test_datasource_parameter(mock_api):
-    """Test that datasource parameter is included in XML."""
-    route = mock_api.post("https://aspen.local/ProcessData/AtProcessDataREST.dll")
+    """Test that datasource parameter is included in SQL query for RAW reads."""
+    # RAW reads with datasource use SQL endpoint
+    route = mock_api.post("https://aspen.local/ProcessData/AtProcessDataREST.dll/SQL")
     route.mock(
         return_value=httpx.Response(
             200,
-            json={"data": [{"samples": [{"t": 1750406400000, "v": 1.0, "s": 8}]}]},
+            json=[
+                {
+                    "ts": "2025-06-20T08:00:00",
+                    "name": "TAG1",
+                    "value": 1.0,
+                }
+            ],
         )
     )
 
@@ -237,12 +244,12 @@ def test_datasource_parameter(mock_api):
         read_type=ReaderType.RAW,
     )
 
-    # Verify datasource is in the XML
+    # Verify datasource is in the SQL query XML
     assert route.called
     request = route.calls.last.request
     request_body = request.content.decode("utf-8")
 
-    assert "<D><![CDATA[MY_DATASOURCE]]></D>" in request_body
+    assert 'ds="MY_DATASOURCE"' in request_body
     assert isinstance(df, pd.DataFrame)
     c.close()
 
@@ -302,7 +309,10 @@ def test_search_by_tag_pattern(mock_api):
     )
 
     # Search with wildcard
-    results = c.search(tag="TEMP*")
+    results_raw = c.search(tag="TEMP*")
+    # Type narrowing: return_desc=True (default) guarantees list[dict[str, str]]
+    assert isinstance(results_raw, list) and (not results_raw or isinstance(results_raw[0], dict))
+    results: list[dict[str, str]] = results_raw  # type: ignore[assignment]
 
     assert isinstance(results, list)
     assert len(results) == 3
@@ -358,7 +368,10 @@ def test_search_by_description(mock_api):
     )
 
     # Search by description - should use SQL endpoint
-    results = c.search(description="reactor")
+    results_raw = c.search(description="reactor")
+    # Type narrowing: return_desc=True (default) guarantees list[dict[str, str]]
+    assert isinstance(results_raw, list) and (not results_raw or isinstance(results_raw[0], dict))
+    results: list[dict[str, str]] = results_raw  # type: ignore[assignment]
 
     assert len(results) == 2
     assert results[0]["name"] == "TEMP_101"
@@ -416,7 +429,10 @@ def test_search_combined_filters(mock_api):
     )
 
     # Search with both filters - SQL WHERE clause filters server-side
-    results = c.search(tag="AI_1*", description="reactor")
+    results_raw = c.search(tag="AI_1*", description="reactor")
+    # Type narrowing: return_desc=True (default) guarantees list[dict[str, str]]
+    assert isinstance(results_raw, list) and (not results_raw or isinstance(results_raw[0], dict))
+    results: list[dict[str, str]] = results_raw  # type: ignore[assignment]
 
     assert len(results) == 2
     assert all("AI_1" in tag["name"] for tag in results)
@@ -470,7 +486,10 @@ def test_search_case_insensitive(mock_api):
     )
 
     # Search with lowercase description (should use SQL endpoint)
-    results = c.search(description="REACTOR")
+    results_raw = c.search(description="REACTOR")
+    # Type narrowing: return_desc=True (default) guarantees list[dict[str, str]]
+    assert isinstance(results_raw, list) and (not results_raw or isinstance(results_raw[0], dict))
+    results: list[dict[str, str]] = results_raw  # type: ignore[assignment]
 
     assert len(results) == 2  # Case-insensitive match
     c.close()
@@ -525,7 +544,10 @@ def test_search_return_desc_false(mock_api):
     )
 
     # Search with return_desc=False - should return list of strings
-    results = c.search(tag="TEMP*", return_desc=False)
+    results_raw = c.search(tag="TEMP*", return_desc=False)
+    # Type narrowing: return_desc=False guarantees list[str]
+    assert isinstance(results_raw, list) and (not results_raw or isinstance(results_raw[0], str))
+    results: list[str] = results_raw  # type: ignore[assignment]
 
     assert isinstance(results, list)
     assert len(results) == 2
@@ -561,7 +583,10 @@ def test_search_by_tag_only(mock_api):
     )
 
     # Search by tag only (should use Browse endpoint, not SQL)
-    results = c.search(tag="AI*")
+    results_raw = c.search(tag="AI*")
+    # Type narrowing: return_desc=True (default) guarantees list[dict[str, str]]
+    assert isinstance(results_raw, list) and (not results_raw or isinstance(results_raw[0], dict))
+    results: list[dict[str, str]] = results_raw  # type: ignore[assignment]
 
     assert len(results) == 2
     assert results[0]["name"] == "AI_101"