aspy21 0.2.0b0__tar.gz → 0.2.0b2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aspy21
-Version: 0.2.0b0
+Version: 0.2.0b2
 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.0b0 → aspy21-0.2.0b2}/src/aspy21/_version.py

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

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

@@ -12,6 +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
 
 if TYPE_CHECKING:
     from httpx import Auth
@@ -127,72 +128,9 @@ class AspenClient:
         """Close the HTTP client connection."""
         self._client.close()
 
-    def _generate_xml_query(
-        self,
-        tag: str,
-        start: str,
-        end: str,
-        read_type: ReaderType,
-        interval: int | None = None,
-        datasource: str = "",  # Empty string = use default datasource
-        max_rows: int = 100000,
-    ) -> str:
-        """Generate XML query for Aspen REST API.
-
-        Args:
-            tag: Tag name
-            start: Start timestamp (ISO format)
-            end: End timestamp (ISO format)
-            read_type: Type of read (RAW, INT, etc.)
-            interval: Interval in seconds (for aggregated reads)
-            datasource: Data source name (default: IP21)
-            max_rows: Maximum number of rows to return
-
-        Returns:
-            XML query string
-        """
-        # Convert ISO timestamps to milliseconds since epoch
-        start_dt = pd.to_datetime(start)
-        end_dt = pd.to_datetime(end)
-        start_ms = int(start_dt.timestamp() * 1000)
-        end_ms = int(end_dt.timestamp() * 1000)
-
-        # Map ReaderType to Aspen RT codes
-        rt_map = {
-            ReaderType.RAW: 0,
-            ReaderType.INT: 1,
-            ReaderType.SNAPSHOT: 2,  # Will use Attribute endpoint
-            ReaderType.AVG: 10,
-        }
-        rt_code = rt_map.get(read_type, 0)
-
-        # Build XML query
-        xml = '<Q f="d" allQuotes="1">'
-        xml += "<Tag>"
-        xml += f"<N><![CDATA[{tag}]]></N>"
-        # Only include datasource if specified
-        if datasource:
-            xml += f"<D><![CDATA[{datasource}]]></D>"
-        xml += "<F><![CDATA[VAL]]></F>"
-        xml += "<HF>0</HF>"  # History format: 0=Raw
-        xml += f"<St>{start_ms}</St>"
-        xml += f"<Et>{end_ms}</Et>"
-        xml += f"<RT>{rt_code}</RT>"
-        xml += f"<X>{max_rows}</X>"
-
-        # Add interval for aggregated reads
-        if interval and rt_code >= 10:
-            xml += f"<P>{interval}</P>"
-            xml += "<PU>3</PU>"  # Period unit: 3=seconds
-
-        xml += "</Tag>"
-        xml += "</Q>"
-
-        return xml
-
     def _parse_aspen_response(
         self, response: dict, tag_name: str, include_status: bool = True
-    ) -> pd.DataFrame:
+    ) -> tuple[pd.DataFrame, str]:
         """Parse Aspen REST API response into DataFrame.
 
         Args:
@@ -201,7 +139,7 @@ class AspenClient:
             include_status: Whether to include status column
 
         Returns:
-            DataFrame with timestamp index and tag data
+            Tuple of (DataFrame with timestamp index and tag data, tag description)
 
         Aspen API returns:
         {
@@ -220,11 +158,19 @@ class AspenClient:
             data = response.get("data", [])
             if not data or not isinstance(data, list):
                 logger.warning(f"No data array in response for tag {tag_name}")
-                return pd.DataFrame()
+                return pd.DataFrame(), ""
 
             # Get first element (should contain samples)
             tag_data = data[0] if len(data) > 0 else {}
 
+            # Extract description if available (from IP_DESCRIPTION field)
+            description = ""
+            if "l" in tag_data and isinstance(tag_data["l"], list) and len(tag_data["l"]) > 0:
+                # "l" contains list of field values, IP_DESCRIPTION is second field if requested
+                fields = tag_data["l"]
+                if len(fields) > 1:
+                    description = fields[1] if fields[1] is not None else ""
+
             # Check for errors in samples
             samples = tag_data.get("samples", [])
             if samples and isinstance(samples, list) and len(samples) > 0:
@@ -233,11 +179,11 @@ class AspenClient:
                 if "er" in first_sample and first_sample.get("er", 0) != 0:
                     error_msg = first_sample.get("es", "Unknown error")
                     logger.warning(f"API error for tag {tag_name}: {error_msg}")
-                    return pd.DataFrame()
+                    return pd.DataFrame(), description
 
             if not samples:
                 logger.warning(f"No samples found for tag {tag_name}")
-                return pd.DataFrame()
+                return pd.DataFrame(), description
 
             # Build DataFrame
             rows = []
@@ -256,18 +202,18 @@ class AspenClient:
 
             if not rows:
                 logger.warning(f"No valid data samples for tag {tag_name}")
-                return pd.DataFrame()
+                return pd.DataFrame(), description
 
             df = pd.DataFrame(rows)
             if not df.empty:
                 df = df.set_index("time")
 
-            return df
+            return df, description
 
         except Exception as e:
             logger.error(f"Error parsing response for tag {tag_name}: {e}")
             logger.debug(f"Response was: {response}")
-            return pd.DataFrame()
+            return pd.DataFrame(), ""
 
     @retry(wait=wait_exponential(multiplier=0.5, min=0.5, max=8), stop=stop_after_attempt(3))
     def _fetch(self, xml_query: str) -> dict:
@@ -323,7 +269,9 @@ class AspenClient:
         read_type: ReaderType = ReaderType.RAW,
         include_status: bool = True,
         max_rows: int = 100000,
-    ) -> pd.DataFrame:
+        as_json: bool = False,
+        with_description: bool = False,
+    ) -> pd.DataFrame | list[dict]:
         """Read historical data for multiple tags.
 
         Args:
@@ -334,12 +282,21 @@ class AspenClient:
             read_type: Type of data retrieval (RAW, INT, SNAPSHOT, AVG)
             include_status: Include status column in output (default: True)
             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.
 
         Returns:
-            pandas DataFrame with time index and columns for each tag.
-            If include_status=True, includes a 'status' column.
+            If as_json=False: pandas DataFrame with time index and columns for each tag.
+                             If include_status=True, includes a 'status' column.
+            If as_json=True: List of dictionaries, each containing:
+                            - timestamp: ISO format timestamp string
+                            - tag: Tag name
+                            - description: Tag description (from IP_DESCRIPTION field)
+                            - value: Tag value
 
         Example:
+            >>> # DataFrame output (default)
             >>> client = AspenClient("https://aspen.example.com/ProcessData")
             >>> df = client.read(
             ...     ["ATI111", "AP101.PV"],
@@ -348,13 +305,18 @@ class AspenClient:
             ...     read_type=ReaderType.RAW
             ... )
 
-            >>> # Get more rows if needed
-            >>> df = client.read(
+            >>> # JSON output with descriptions
+            >>> data = client.read(
             ...     ["ATI111"],
             ...     start="2025-01-01 00:00:00",
-            ...     end="2025-01-02 00:00:00",
-            ...     max_rows=500000
+            ...     end="2025-01-01 01:00:00",
+            ...     as_json=True
             ... )
+            >>> # Returns: [
+            >>> #   {"timestamp": "2025-01-01T00:00:00", "tag": "ATI111",
+            >>> #    "description": "Temperature sensor", "value": 25.5},
+            >>> #   ...
+            >>> # ]
         """
         tags_list = list(tags)
         logger.info(f"Reading {len(tags_list)} tag(s) from {start} to {end} (max_rows={max_rows})")
@@ -362,13 +324,14 @@ class AspenClient:
         logger.debug(f"Reader type: {read_type.value}, Interval: {interval}")
 
         frames: list[pd.DataFrame] = []
+        tag_descriptions: dict[str, str] = {}
 
         # 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 = self._generate_xml_query(
+            xml_query = build_read_query(
                 tag=tag,
                 start=start,
                 end=end,
@@ -376,20 +339,27 @@ class AspenClient:
                 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}")
 
             # Parse the Aspen-style response
-            df = self._parse_aspen_response(response, tag, include_status=include_status)
+            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)
+                if description:
+                    tag_descriptions[tag] = description
 
         if not frames:
             logger.warning("No data returned from API")
+            if as_json:
+                return []
             return pd.DataFrame()
 
         # Merge frames by index (time), combining columns for different tags
@@ -397,6 +367,35 @@ class AspenClient:
         out = out.sort_index()
 
         logger.info(f"Successfully retrieved {len(out)} rows for {len(out.columns)} column(s)")
+
+        # Convert to JSON format if requested
+        if as_json:
+            json_data: list[dict] = []
+            for idx, row in out.iterrows():
+                # Iterate through each tag (column) in this row
+                for tag in tags_list:
+                    if tag in row.index:
+                        value = row[tag]
+                        # Skip NaN values - use isinstance check to avoid Series.__bool__ issue
+                        if isinstance(value, (int, float, str)) and pd.notna(value):
+                            # idx is pandas Timestamp, which has isoformat method
+                            # type: ignore is needed because iterrows() returns Hashable for index
+                            ts = (
+                                idx.isoformat()  # type: ignore[union-attr]
+                                if hasattr(idx, "isoformat")
+                                else str(idx)
+                            )
+                            json_data.append(
+                                {
+                                    "timestamp": ts,
+                                    "tag": tag,
+                                    "description": tag_descriptions.get(tag, ""),
+                                    "value": value,
+                                }
+                            )
+            logger.debug(f"Converted to {len(json_data)} JSON records")
+            return json_data
+
         return out
 
     def _search_by_sql(
@@ -432,37 +431,12 @@ class AspenClient:
                 "AspenClient(base_url=..., datasource='your_datasource')"
             )
 
-        # Build SQL query - search for description pattern
-        # Note: SQL LIKE uses % as wildcard, not *
-        sql_pattern = description.replace("*", "%")
-        if not sql_pattern.startswith("%"):
-            sql_pattern = f"%{sql_pattern}%"
-
-        # Build WHERE clause - filter by both name and description in SQL
-        where_clauses = [f"d like '{sql_pattern}'"]
-
-        # Add name pattern filter if not wildcard
-        if tag_pattern != "*":
-            name_pattern = tag_pattern.replace("*", "%").replace("?", "_")
-            # Add wildcards to name pattern if not already present
-            if "%" not in name_pattern and "_" not in name_pattern:
-                name_pattern = f"%{name_pattern}%"
-            where_clauses.append(f"name like '{name_pattern}'")
-
-        where_clause = " and ".join(where_clauses)
-
-        sql_query = (
-            f"Select name, name->ip_description d, name->ip_input_value "
-            f"from all_records where {where_clause}"
-        )
-
-        # Build XML request for SQL endpoint
-        xml = (
-            f'<SQL g="aspy21_search" t="SQLplus" ds="{self.datasource}" '
-            f'dso="CHARINT=N;CHARFLOAT=N;CHARTIME=N;CONVERTERRORS=N" '
-            f'm="{max_results}" to="30" response="Original" s="1">'
-            f"<![CDATA[{sql_query}]]>"
-            f"</SQL>"
+        # Build XML query for SQL endpoint
+        xml = build_sql_search_query(
+            datasource=self.datasource,
+            description=description,
+            tag_pattern=tag_pattern,
+            max_results=max_results,
         )
 
         logger.debug(f"SQL query XML: {xml}")

aspy21-0.2.0b2/src/aspy21/query_builder.py

@@ -0,0 +1,130 @@
+"""XML query generation for Aspen InfoPlus.21 REST API."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from .models import ReaderType
+
+
+def build_read_query(
+    tag: str,
+    start: str,
+    end: str,
+    read_type: ReaderType,
+    interval: int | None = None,
+    datasource: str = "",
+    max_rows: int = 100000,
+    with_description: bool = False,
+) -> str:
+    """Generate XML query for Aspen REST API data read.
+
+    Args:
+        tag: Tag name
+        start: Start timestamp (ISO format)
+        end: End timestamp (ISO format)
+        read_type: Type of read (RAW, INT, etc.)
+        interval: Interval in seconds (for aggregated reads)
+        datasource: Data source name (default: IP21)
+        max_rows: Maximum number of rows to return
+        with_description: Include ip_description field in response
+
+    Returns:
+        XML query string
+    """
+    # Convert ISO timestamps to milliseconds since epoch
+    start_dt = pd.to_datetime(start)
+    end_dt = pd.to_datetime(end)
+    start_ms = int(start_dt.timestamp() * 1000)
+    end_ms = int(end_dt.timestamp() * 1000)
+
+    # Map ReaderType to Aspen RT codes
+    rt_map = {
+        ReaderType.RAW: 0,
+        ReaderType.INT: 1,
+        ReaderType.SNAPSHOT: 2,  # Will use Attribute endpoint
+        ReaderType.AVG: 10,
+    }
+    rt_code = rt_map.get(read_type, 0)
+
+    # Build XML query
+    xml = '<Q f="d" allQuotes="1">'
+    xml += "<Tag>"
+    xml += f"<N><![CDATA[{tag}]]></N>"
+    # Only include datasource if specified
+    if datasource:
+        xml += f"<D><![CDATA[{datasource}]]></D>"
+    xml += "<F><![CDATA[VAL]]></F>"
+
+    # Add description field if requested
+    if with_description:
+        xml += "<F><![CDATA[IP_DESCRIPTION]]></F>"
+
+    xml += "<HF>0</HF>"  # History format: 0=Raw
+    xml += f"<St>{start_ms}</St>"
+    xml += f"<Et>{end_ms}</Et>"
+    xml += f"<RT>{rt_code}</RT>"
+    xml += f"<X>{max_rows}</X>"
+
+    # Add interval for aggregated reads
+    if interval and rt_code >= 10:
+        xml += f"<P>{interval}</P>"
+        xml += "<PU>3</PU>"  # Period unit: 3=seconds
+
+    xml += "</Tag>"
+    xml += "</Q>"
+
+    return xml
+
+
+def build_sql_search_query(
+    datasource: str,
+    description: str,
+    tag_pattern: str = "*",
+    max_results: int = 10000,
+) -> str:
+    """Generate XML query for SQL-based tag search.
+
+    Args:
+        datasource: Aspen datasource name
+        description: Description pattern to search for (supports * wildcards)
+        tag_pattern: Tag name pattern (supports * and ? wildcards)
+        max_results: Maximum number of results
+
+    Returns:
+        XML query string for SQL endpoint
+    """
+    # Build SQL query - search for description pattern
+    # Note: SQL LIKE uses % as wildcard, not *
+    sql_pattern = description.replace("*", "%")
+    if not sql_pattern.startswith("%"):
+        sql_pattern = f"%{sql_pattern}%"
+
+    # Build WHERE clause - filter by both name and description in SQL
+    where_clauses = [f"d like '{sql_pattern}'"]
+
+    # Add name pattern filter if not wildcard
+    if tag_pattern != "*":
+        name_pattern = tag_pattern.replace("*", "%").replace("?", "_")
+        # Add wildcards to name pattern if not already present
+        if "%" not in name_pattern and "_" not in name_pattern:
+            name_pattern = f"%{name_pattern}%"
+        where_clauses.append(f"name like '{name_pattern}'")
+
+    where_clause = " and ".join(where_clauses)
+
+    sql_query = (
+        f"Select name, name->ip_description d, name->ip_input_value "
+        f"from all_records where {where_clause}"
+    )
+
+    # Build XML request for SQL endpoint
+    xml = (
+        f'<SQL g="aspy21_search" t="SQLplus" ds="{datasource}" '
+        f'dso="CHARINT=N;CHARFLOAT=N;CHARTIME=N;CONVERTERRORS=N" '
+        f'm="{max_results}" to="30" response="Original" s="1">'
+        f"<![CDATA[{sql_query}]]>"
+        f"</SQL>"
+    )
+
+    return xml

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aspy21
-Version: 0.2.0b0
+Version: 0.2.0b2
 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.0b0 → aspy21-0.2.0b2}/src/aspy21.egg-info/SOURCES.txt

@@ -23,6 +23,7 @@ src/aspy21/_version.py
 src/aspy21/cache.py
 src/aspy21/client.py
 src/aspy21/models.py
+src/aspy21/query_builder.py
 src/aspy21/utils.py
 src/aspy21.egg-info/PKG-INFO
 src/aspy21.egg-info/SOURCES.txt

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

@@ -655,3 +655,232 @@ def test_context_manager_returns_self():
     assert returned is client
 
     client.close()
+
+
+def test_read_as_json_basic(mock_api):
+    """Test reading data with as_json=True returns list of dictionaries."""
+    mock_api.post("https://aspen.local/ProcessData/AtProcessDataREST.dll").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "data": [
+                    {
+                        "l": ["VAL", "Temperature sensor"],  # Field values including description
+                        "samples": [
+                            {"t": 1704110400000, "v": 25.5, "s": 8},  # 2024-01-01 12:00:00
+                            {"t": 1704114000000, "v": 26.0, "s": 8},  # 2024-01-01 13:00:00
+                        ],
+                    }
+                ]
+            },
+        )
+    )
+
+    with AspenClient(
+        base_url="https://aspen.local/ProcessData/AtProcessDataREST.dll",
+        timeout=2,
+        verify_ssl=False,
+    ) as client:
+        data = client.read(
+            tags=["TAG1"],
+            start="2024-01-01 12:00:00",
+            end="2024-01-01 13:00:00",
+            read_type=ReaderType.RAW,
+            as_json=True,
+        )
+
+        # Verify it's a list of dicts
+        assert isinstance(data, list)
+        assert len(data) == 2
+
+        # Verify structure of first record
+        assert "timestamp" in data[0]
+        assert "tag" in data[0]
+        assert "description" in data[0]
+        assert "value" in data[0]
+
+        # Verify values
+        assert data[0]["tag"] == "TAG1"
+        assert data[0]["description"] == "Temperature sensor"
+        assert data[0]["value"] == 25.5
+        assert isinstance(data[0]["timestamp"], str)
+
+        assert data[1]["value"] == 26.0
+
+
+def test_read_with_description_dataframe(mock_api):
+    """Test reading data with with_description=True still returns DataFrame."""
+    route = mock_api.post("https://aspen.local/ProcessData/AtProcessDataREST.dll")
+    route.mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "data": [
+                    {
+                        "l": ["VAL", "Pressure sensor"],  # Field values including description
+                        "samples": [
+                            {"t": 1704110400000, "v": 101.3, "s": 8},
+                        ],
+                    }
+                ]
+            },
+        )
+    )
+
+    with AspenClient(
+        base_url="https://aspen.local/ProcessData/AtProcessDataREST.dll",
+        timeout=2,
+        verify_ssl=False,
+    ) as client:
+        df = client.read(
+            tags=["PRESS1"],
+            start="2024-01-01 12:00:00",
+            end="2024-01-01 13:00:00",
+            read_type=ReaderType.RAW,
+            with_description=True,
+        )
+
+        # Should still return DataFrame when as_json=False
+        assert isinstance(df, pd.DataFrame)
+        assert not df.empty
+        assert "PRESS1" in df.columns
+
+        # Verify IP_DESCRIPTION field was requested in XML
+        request = route.calls.last.request
+        request_body = request.content.decode("utf-8")
+        assert "<F><![CDATA[IP_DESCRIPTION]]></F>" in request_body
+
+
+def test_read_as_json_multiple_tags(mock_api):
+    """Test as_json with multiple tags."""
+
+    def response_handler(request):
+        # Return different data based on which tag is requested
+        body = request.content.decode("utf-8")
+        if "TAG1" in body:
+            return httpx.Response(
+                200,
+                json={
+                    "data": [
+                        {
+                            "l": ["VAL", "Temperature sensor"],
+                            "samples": [
+                                {"t": 1704110400000, "v": 25.5, "s": 8},
+                            ],
+                        }
+                    ]
+                },
+            )
+        else:  # TAG2
+            return httpx.Response(
+                200,
+                json={
+                    "data": [
+                        {
+                            "l": ["VAL", "Pressure sensor"],
+                            "samples": [
+                                {"t": 1704110400000, "v": 101.3, "s": 8},
+                            ],
+                        }
+                    ]
+                },
+            )
+
+    mock_api.post("https://aspen.local/ProcessData/AtProcessDataREST.dll").mock(
+        side_effect=response_handler
+    )
+
+    with AspenClient(
+        base_url="https://aspen.local/ProcessData/AtProcessDataREST.dll",
+        timeout=2,
+        verify_ssl=False,
+    ) as client:
+        data = client.read(
+            tags=["TAG1", "TAG2"],
+            start="2024-01-01 12:00:00",
+            end="2024-01-01 13:00:00",
+            read_type=ReaderType.RAW,
+            as_json=True,
+        )
+
+        # Should have 2 records (one per tag, same timestamp)
+        assert isinstance(data, list)
+        assert len(data) == 2
+
+        # Verify both tags are present
+        tags = {record["tag"] for record in data}
+        assert tags == {"TAG1", "TAG2"}
+
+        # Verify descriptions
+        tag1_record = next(r for r in data if r["tag"] == "TAG1")
+        tag2_record = next(r for r in data if r["tag"] == "TAG2")
+
+        assert tag1_record["description"] == "Temperature sensor"
+        assert tag1_record["value"] == 25.5
+
+        assert tag2_record["description"] == "Pressure sensor"
+        assert tag2_record["value"] == 101.3
+
+
+def test_read_as_json_empty_response(mock_api):
+    """Test as_json=True with empty response returns empty list."""
+    mock_api.post("https://aspen.local/ProcessData/AtProcessDataREST.dll").mock(
+        return_value=httpx.Response(
+            200,
+            json={"data": [{"samples": []}]},
+        )
+    )
+
+    with AspenClient(
+        base_url="https://aspen.local/ProcessData/AtProcessDataREST.dll",
+        timeout=2,
+        verify_ssl=False,
+    ) as client:
+        data = client.read(
+            tags=["TAG1"],
+            start="2024-01-01 12:00:00",
+            end="2024-01-01 13:00:00",
+            read_type=ReaderType.RAW,
+            as_json=True,
+        )
+
+        # Should return empty list
+        assert isinstance(data, list)
+        assert len(data) == 0
+
+
+def test_read_as_json_without_description(mock_api):
+    """Test as_json=True when description is not available in response."""
+    mock_api.post("https://aspen.local/ProcessData/AtProcessDataREST.dll").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "data": [
+                    {
+                        # No "l" field - description not available
+                        "samples": [
+                            {"t": 1704110400000, "v": 25.5, "s": 8},
+                        ],
+                    }
+                ]
+            },
+        )
+    )
+
+    with AspenClient(
+        base_url="https://aspen.local/ProcessData/AtProcessDataREST.dll",
+        timeout=2,
+        verify_ssl=False,
+    ) as client:
+        data = client.read(
+            tags=["TAG1"],
+            start="2024-01-01 12:00:00",
+            end="2024-01-01 13:00:00",
+            read_type=ReaderType.RAW,
+            as_json=True,
+        )
+
+        # Should still work, but description should be empty string
+        assert len(data) == 1
+        assert data[0]["description"] == ""
+        assert data[0]["value"] == 25.5