aspy21 0.1.1b8__py3-none-any.whl

aspy21/__init__.py

@@ -0,0 +1,17 @@
+"""
+aspy21 - Modern Python client for Aspen InfoPlus.21 (IP.21).
+
+A high-performance REST API client for accessing Aspen process data
+with pandas DataFrame output and flexible batching.
+"""
+
+from .client import AspenClient, configure_logging
+from .models import ReaderType
+
+try:
+    from ._version import __version__  # type: ignore[import-not-found]
+except ImportError:
+    # Development mode - no version file generated yet
+    __version__ = "0.0.0.dev0"
+
+__all__ = ["AspenClient", "ReaderType", "configure_logging", "__version__"]

aspy21/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.1b8'
+__version_tuple__ = version_tuple = (0, 1, 1, 'b8')
+
+__commit_id__ = commit_id = None

aspy21/cache.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+
+class SmartCache:
+    def __init__(self, db_path: Path):
+        self.db_path = Path(db_path)
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init()
+
+    def _init(self) -> None:
+        with sqlite3.connect(self.db_path) as conn:
+            conn.execute("CREATE TABLE IF NOT EXISTS meta (key TEXT PRIMARY KEY, value BLOB)")
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS hist (
+                  tag TEXT,
+                  ts  TEXT,
+                  value BLOB,
+                  status INTEGER,
+                  PRIMARY KEY (tag, ts)
+                )
+            """)
+
+    def put_meta(self, key: str, value: bytes) -> None:
+        with sqlite3.connect(self.db_path) as conn:
+            conn.execute("REPLACE INTO meta (key, value) VALUES (?,?)", (key, value))
+
+    def get_meta(self, key: str) -> bytes | None:
+        with sqlite3.connect(self.db_path) as conn:
+            cur = conn.execute("SELECT value FROM meta WHERE key=?", (key,))
+            row = cur.fetchone()
+            return row[0] if row else None

aspy21/client.py

@@ -0,0 +1,684 @@
+"""Main client for interacting with Aspen InfoPlus.21 REST API."""
+
+from __future__ import annotations
+
+import logging
+import os
+from collections.abc import Iterable
+from typing import TYPE_CHECKING
+
+import httpx
+import pandas as pd
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+from .models import ReaderType
+
+if TYPE_CHECKING:
+    from httpx import Auth
+
+logger = logging.getLogger(__name__)
+
+
+def configure_logging(level: str | None = None) -> None:
+    """Configure logging level for aspy21 library.
+
+    Args:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL).
+               If None, reads from ASPEN_LOG_LEVEL environment variable.
+               Defaults to WARNING if not set.
+    """
+    if level is None:
+        level = os.getenv("ASPEN_LOG_LEVEL", "WARNING")
+
+    numeric_level = getattr(logging, level.upper(), logging.WARNING)
+    logger.setLevel(numeric_level)
+
+    # Only add handler if logger doesn't have one already
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        formatter = logging.Formatter(
+            "%(asctime)s - %(name)s - %(levelname)s - %(message)s", datefmt="%Y-%m-%d %H:%M:%S"
+        )
+        handler.setFormatter(formatter)
+        logger.addHandler(handler)
+
+
+class AspenClient:
+    """Client for Aspen InfoPlus.21 REST API.
+
+    Provides methods to read historical and real-time process data from
+    Aspen IP.21 historian via REST API with automatic batching, retries,
+    and pandas DataFrame output.
+
+    Supports context manager protocol for automatic resource cleanup.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        auth: Auth | tuple[str, str] | None = None,
+        timeout: float = 30.0,
+        verify_ssl: bool = True,
+        datasource: str | None = None,
+    ) -> None:
+        """Initialize the Aspen client.
+
+        Args:
+            base_url: Base URL of the Aspen ProcessData REST API
+            auth: Authentication as (username, password) tuple or httpx Auth object.
+                  If None, no authentication is used.
+            timeout: Request timeout in seconds (default: 30.0)
+            verify_ssl: Whether to verify SSL certificates (default: True)
+            datasource: Aspen datasource name. If None, uses server default.
+
+        Example:
+            Using context manager with authentication:
+                >>> with AspenClient(
+                ...     base_url="https://aspen.example.com/ProcessData",
+                ...     auth=("user", "pass")
+                ... ) as client:
+                ...     df = client.read(["TAG1"], "2025-01-01", "2025-01-02")
+
+            Without authentication:
+                >>> with AspenClient(base_url="http://aspen.example.com/ProcessData") as client:
+                ...     df = client.read(["TAG1"], "2025-01-01", "2025-01-02")
+
+            With datasource for search:
+                >>> with AspenClient(
+                ...     base_url="https://aspen.example.com/ProcessData",
+                ...     auth=("user", "pass"),
+                ...     datasource="IP21"
+                ... ) as client:
+                ...     tags = client.search(tag="TEMP*")
+        """
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.verify_ssl = verify_ssl
+        self.datasource = datasource or ""  # Empty string = use server default
+        self.auth = auth
+
+        self._client = httpx.Client(timeout=timeout, verify=verify_ssl, auth=auth)
+
+        logger.info(f"Initialized AspenClient for {self.base_url}")
+        logger.debug(
+            f"Config: timeout={timeout}s, verify_ssl={verify_ssl}, datasource={datasource}"
+        )
+
+    def __enter__(self) -> AspenClient:
+        """Enter context manager.
+
+        Returns:
+            self for use in with statement
+        """
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Exit context manager and close connection.
+
+        Args:
+            exc_type: Exception type if an exception occurred
+            exc_val: Exception value if an exception occurred
+            exc_tb: Exception traceback if an exception occurred
+        """
+        self.close()
+
+    def close(self) -> None:
+        """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:
+        """Parse Aspen REST API response into DataFrame.
+
+        Args:
+            response: Response dict from Aspen API
+            tag_name: Name of the tag being queried
+            include_status: Whether to include status column
+
+        Returns:
+            DataFrame with timestamp index and tag data
+
+        Aspen API returns:
+        {
+          "data": [
+            {
+              "samples": [
+                {"t": timestamp_ms, "v": value, "s": status},
+                ...
+              ]
+            }
+          ]
+        }
+        """
+        try:
+            # Get data array
+            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()
+
+            # Get first element (should contain samples)
+            tag_data = data[0] if len(data) > 0 else {}
+
+            # Check for errors in samples
+            samples = tag_data.get("samples", [])
+            if samples and isinstance(samples, list) and len(samples) > 0:
+                first_sample = samples[0]
+                # Check if first sample contains an error
+                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()
+
+            if not samples:
+                logger.warning(f"No samples found for tag {tag_name}")
+                return pd.DataFrame()
+
+            # Build DataFrame
+            rows = []
+            for sample in samples:
+                # Skip error samples
+                if "er" in sample:
+                    continue
+
+                row = {
+                    "time": pd.to_datetime(sample["t"], unit="ms", utc=True).tz_convert(None),
+                    tag_name: sample.get("v"),
+                }
+                if include_status:
+                    row["status"] = sample.get("s", 0)
+                rows.append(row)
+
+            if not rows:
+                logger.warning(f"No valid data samples for tag {tag_name}")
+                return pd.DataFrame()
+
+            df = pd.DataFrame(rows)
+            if not df.empty:
+                df = df.set_index("time")
+
+            return df
+
+        except Exception as e:
+            logger.error(f"Error parsing response for tag {tag_name}: {e}")
+            logger.debug(f"Response was: {response}")
+            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:
+        """Fetch data from API endpoint with automatic retry.
+
+        Args:
+            xml_query: XML query string
+
+        Returns:
+            JSON response as dictionary
+
+        Raises:
+            httpx.HTTPError: If the request fails after retries
+        """
+        logger.debug(f"POST {self.base_url}")
+        logger.debug(f"Query XML: {xml_query}")
+
+        try:
+            # Try sending XML as POST body with correct content type
+            r = self._client.post(
+                self.base_url, content=xml_query, headers={"Content-Type": "text/xml"}
+            )
+            logger.debug(f"Response status: {r.status_code}")
+            logger.debug(f"Response headers: {dict(r.headers)}")
+
+            r.raise_for_status()
+            response_data = r.json()
+
+            logger.debug(
+                f"Response data keys: {list(response_data.keys()) if response_data else 'empty'}"
+            )
+            logger.debug(f"Full response: {response_data}")  # Show complete response for debugging
+
+            return response_data
+
+        except httpx.HTTPStatusError as e:
+            logger.error(f"HTTP {e.response.status_code} error for {self.base_url}")
+            logger.error(f"Response body: {e.response.text[:500]}")
+            raise
+        except httpx.RequestError as e:
+            logger.error(f"Request error: {type(e).__name__}: {e}")
+            raise
+        except Exception as e:
+            logger.error(f"Unexpected error: {type(e).__name__}: {e}")
+            raise
+
+    def read(
+        self,
+        tags: Iterable[str],
+        start: str,
+        end: str,
+        interval: int | None = None,
+        read_type: ReaderType = ReaderType.RAW,
+        include_status: bool = True,
+        max_rows: int = 100000,
+    ) -> pd.DataFrame:
+        """Read historical data for multiple tags.
+
+        Args:
+            tags: List of tag names to retrieve
+            start: Start timestamp (ISO format or compatible string)
+            end: End timestamp (ISO format or compatible string)
+            interval: Optional interval in seconds for aggregated data
+            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)
+
+        Returns:
+            pandas DataFrame with time index and columns for each tag.
+            If include_status=True, includes a 'status' column.
+
+        Example:
+            >>> client = AspenClient("https://aspen.example.com/ProcessData")
+            >>> df = client.read(
+            ...     ["ATI111", "AP101.PV"],
+            ...     start="2025-01-01 00:00:00",
+            ...     end="2025-01-01 01:00:00",
+            ...     read_type=ReaderType.RAW
+            ... )
+
+            >>> # Get more rows if needed
+            >>> df = client.read(
+            ...     ["ATI111"],
+            ...     start="2025-01-01 00:00:00",
+            ...     end="2025-01-02 00:00:00",
+            ...     max_rows=500000
+            ... )
+        """
+        tags_list = list(tags)
+        logger.info(f"Reading {len(tags_list)} tag(s) from {start} to {end} (max_rows={max_rows})")
+        logger.debug(f"Tags: {tags_list}")
+        logger.debug(f"Reader type: {read_type.value}, Interval: {interval}")
+
+        frames: list[pd.DataFrame] = []
+
+        # 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(
+                tag=tag,
+                start=start,
+                end=end,
+                read_type=read_type,
+                interval=interval,
+                datasource=self.datasource,
+                max_rows=max_rows,
+            )
+
+            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)
+            logger.debug(f"Parsed {len(df)} data points for tag {tag}")
+
+            if not df.empty:
+                frames.append(df)
+
+        if not frames:
+            logger.warning("No data returned from API")
+            return pd.DataFrame()
+
+        # Merge frames by index (time), combining columns for different tags
+        out = pd.concat(frames, axis=1)
+        out = out.sort_index()
+
+        logger.info(f"Successfully retrieved {len(out)} rows for {len(out.columns)} column(s)")
+        return out
+
+    def _search_by_sql(
+        self,
+        description: str,
+        tag_pattern: str = "*",
+        max_results: int = 10000,
+    ) -> list[dict[str, str]]:
+        """Search for tags by description using SQL endpoint.
+
+        This is an internal method that uses the Aspen SQL endpoint to search
+        by tag description (ip_description field).
+
+        Args:
+            description: Description pattern to search for (SQL LIKE pattern)
+            tag_pattern: Optional tag name pattern to filter by (default: "*")
+            max_results: Maximum number of results to return (default: 10000)
+
+        Returns:
+            List of dictionaries with 'name' and 'description' keys
+
+        Raises:
+            ValueError: If datasource is not configured
+        """
+        if not self.datasource:
+            raise ValueError(
+                "Datasource is required for SQL search. "
+                "Please set datasource when creating 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}%"
+
+        sql_query = (
+            f"Select name, name->ip_description d, name->ip_input_value "
+            f"from all_records where d like '{sql_pattern}'"
+        )
+
+        # 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>"
+        )
+
+        logger.debug(f"SQL query XML: {xml}")
+
+        sql_url = f"{self.base_url}/SQL"
+        logger.info(f"SQL request: POST {sql_url}")
+
+        try:
+            response = self._client.post(sql_url, content=xml, headers={"Content-Type": "text/xml"})
+
+            logger.debug(f"Response status: {response.status_code}")
+            response.raise_for_status()
+
+            data = response.json()
+            logger.debug(f"SQL response keys: {list(data.keys())}")
+
+            # Parse SQL response format
+            # Expected: {"data": [{"g": "...", "r": "D", "cols": [...], "rows": [{"fld": [...]}]}]}
+            if "data" not in data or not isinstance(data["data"], list):
+                logger.warning("Unexpected SQL response structure")
+                logger.debug(f"Full response: {data}")
+                return []
+
+            data_array = data["data"]
+            if not data_array or len(data_array) == 0:
+                logger.info("SQL search returned 0 results")
+                return []
+
+            # Get first result set
+            result_set = data_array[0]
+            if not isinstance(result_set, dict):
+                logger.warning("Unexpected result set structure")
+                return []
+
+            # Check for errors
+            if "result" in result_set:
+                result = result_set["result"]
+                if isinstance(result, dict) and result.get("er", 0) != 0:
+                    error_msg = result.get("es", "Unknown error")
+                    logger.error(f"API error from SQL endpoint: {error_msg}")
+                    raise ValueError(f"SQL API error: {error_msg}")
+
+            # Get rows array
+            rows = result_set.get("rows", [])
+            if not rows:
+                logger.info("SQL search returned 0 results")
+                return []
+
+            logger.debug(f"Found {len(rows)} rows in SQL response")
+
+            results = []
+            for row in rows:
+                if not isinstance(row, dict) or "fld" not in row:
+                    continue
+
+                # Extract field values: fld is array of {"i": index, "v": value}
+                fields = row["fld"]
+                if len(fields) < 2:
+                    continue
+
+                tag_name = fields[0].get("v", "")
+                tag_desc = fields[1].get("v", "")
+
+                # Apply tag pattern filter if specified
+                if tag_pattern != "*":
+                    # Convert wildcard pattern to regex for matching
+                    import re
+
+                    regex_pattern = tag_pattern.replace("*", ".*").replace("?", ".")
+                    if not re.match(f"^{regex_pattern}$", tag_name, re.IGNORECASE):
+                        continue
+
+                results.append({"name": tag_name, "description": tag_desc})
+
+            logger.info(f"Found {len(results)} matching tags via SQL")
+            return results[:max_results]
+
+        except Exception as e:
+            logger.error(f"Error in SQL search: {type(e).__name__}: {e}")
+            raise
+
+    def search(
+        self,
+        tag: str = "*",
+        description: str | None = None,
+        case_sensitive: bool = False,
+        max_results: int = 10000,
+    ) -> list[dict[str, str]]:
+        """Search for tags by name pattern and/or description.
+
+        Supports wildcards:
+        - '*' matches any number of characters
+        - '?' matches exactly one character
+
+        When description parameter is provided, uses SQL endpoint for more
+        efficient server-side filtering. Otherwise uses Browse endpoint.
+
+        Args:
+            tag: Tag name pattern with wildcards (e.g., "TEMP*", "?AI_10?", "*" for all tags).
+                 Defaults to "*" (all tags).
+            description: Description pattern to filter by (case-insensitive substring match).
+                         When provided, uses SQL endpoint for server-side search.
+            case_sensitive: Whether tag name matching should be case-sensitive (default: False).
+                           Only applies to Browse endpoint (tag-only search).
+            max_results: Maximum number of results to return (default: 10000)
+
+        Returns:
+            List of dictionaries with 'name' and 'description' keys
+
+        Raises:
+            ValueError: If datasource is not configured
+
+        Example:
+            >>> # Find all temperature tags
+            >>> tags = client.search(tag="TEMP*")
+            >>>
+            >>> # Find all tags
+            >>> tags = client.search(tag="*")
+            >>>
+            >>> # Search by description only
+            >>> tags = client.search(description="reactor")
+            >>>
+            >>> # Combine name and description
+            >>> tags = client.search(tag="*AI*", description="reactor")
+            >>>
+            >>> for tag in tags:
+            ...     print(f"{tag['name']}: {tag['description']}")
+        """
+        import urllib.parse
+
+        if not self.datasource:
+            raise ValueError(
+                "Datasource is required for search. "
+                "Please set datasource when creating AspenClient: "
+                "AspenClient(base_url=..., datasource='your_datasource')"
+            )
+
+        logger.info(f"Searching tags: pattern={tag}, description={description}")
+
+        # If description is provided, use SQL endpoint for efficient server-side search
+        if description:
+            return self._search_by_sql(
+                description=description, tag_pattern=tag, max_results=max_results
+            )
+
+        # Otherwise, use Browse endpoint for tag name search
+        # Initialize results list
+        results: list[dict[str, str]] = []
+
+        # Build query parameters
+        # Note: The key is "dataSource" (camelCase)
+        params = {
+            "dataSource": self.datasource,
+            "tag": tag,
+            "max": max_results,
+            "getTrendable": 0,
+        }
+
+        # Construct Browse endpoint URL with manually encoded query string
+        # We need to keep * unencoded for wildcard matching
+        # Following tagreader's approach: encode with safe="*"
+        encoded_params = urllib.parse.urlencode(params, safe="*", quote_via=urllib.parse.quote)
+        browse_url = f"{self.base_url}/Browse?{encoded_params}"
+
+        logger.info(f"Browse request: GET {browse_url}")
+        logger.debug(f"Query params: {params}")
+
+        try:
+            # Make GET request to Browse endpoint
+            # URL already contains query string, so don't pass params again
+            response = self._client.get(browse_url)
+
+            # Log the actual request details
+            logger.debug(f"Request URL: {response.request.url}")
+            logger.debug(f"Request method: {response.request.method}")
+            logger.debug(f"Response status: {response.status_code}")
+
+            response.raise_for_status()
+            data = response.json()
+
+            logger.debug(f"Browse response keys: {list(data.keys())}")
+
+            # Check for API error response
+            if "data" in data and isinstance(data["data"], dict):
+                data_obj = data["data"]
+                logger.debug(f"data['data'] keys: {list(data_obj.keys())}")
+
+                # Check for error in result
+                if "result" in data_obj:
+                    result = data_obj["result"]
+                    if isinstance(result, dict) and result.get("er", 0) != 0:
+                        error_msg = result.get("es", "Unknown error")
+                        logger.error(f"API error from Browse endpoint: {error_msg}")
+                        raise ValueError(f"Browse API error: {error_msg}")
+
+                # Check if tags key exists
+                if "tags" not in data_obj:
+                    logger.warning("No 'tags' key in response - search returned no results")
+                    logger.debug(f"Full response: {data}")
+                    return []
+
+                tags_data = data_obj["tags"]
+            else:
+                logger.error(f"Unexpected response structure: {data}")
+                return []
+
+            logger.debug(f"tags_data type: {type(tags_data)}, length: {len(tags_data)}")
+
+            if not tags_data:
+                logger.info("Search returned 0 tags")
+                return []
+
+            for tag_entry in tags_data:
+                tag_name = tag_entry.get("t", "")
+                # Response contains "m" (map type) like "IP_ANALOGMAP", "KPI_VALUEMAP"
+                # and optionally "n" (description). Use "n" if available, otherwise "m"
+                tag_desc = tag_entry.get("n", tag_entry.get("m", ""))
+
+                # Apply case-insensitive filtering if needed
+                if (
+                    not case_sensitive
+                    and tag
+                    and "*" not in tag
+                    and "?" not in tag
+                    and tag.lower() not in tag_name.lower()
+                ):
+                    continue
+
+                results.append({"name": tag_name, "description": tag_desc})
+
+            logger.info(f"Found {len(results)} matching tags")
+            return results[:max_results]
+
+        except Exception as e:
+            logger.error(f"Error searching tags: {type(e).__name__}: {e}")
+            raise

aspy21/models.py

@@ -0,0 +1,19 @@
+"""Data models for Aspen InfoPlus.21 client."""
+
+from enum import Enum
+
+
+class ReaderType(str, Enum):
+    """Reader types for Aspen IP.21 data retrieval.
+
+    Attributes:
+        RAW: Raw data points as stored in the historian
+        INT: Interpolated values at specified intervals
+        SNAPSHOT: Current snapshot of tag values
+        AVG: Average values over specified intervals
+    """
+
+    RAW = "RAW"
+    INT = "INT"
+    SNAPSHOT = "SNAPSHOT"
+    AVG = "AVG"

aspy21/utils.py

@@ -0,0 +1,27 @@
+"""Utility functions for the Aspen client."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from itertools import islice
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def chunked(iterable: Iterable[T], size: int) -> Iterable[list[T]]:
+    """Split an iterable into chunks of specified size.
+
+    Args:
+        iterable: The input iterable to be chunked
+        size: Maximum size of each chunk
+
+    Yields:
+        Lists of items, each containing up to 'size' elements
+    """
+    it = iter(iterable)
+    while True:
+        batch = list(islice(it, size))
+        if not batch:
+            return
+        yield batch

aspy21-0.1.1b8.dist-info/METADATA

@@ -0,0 +1,358 @@
+Metadata-Version: 2.4
+Name: aspy21
+Version: 0.1.1b8
+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>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/bazdalaz/aspy21
+Project-URL: Repository, https://github.com/bazdalaz/aspy21
+Project-URL: Issues, https://github.com/bazdalaz/aspy21/issues
+Keywords: aspen,ip21,historian,process data,industrial,ot,scada,aspentech
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Manufacturing
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Monitoring
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: pandas>=2.0
+Requires-Dist: tenacity>=9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Requires-Dist: pyright>=1.1.389; extra == "dev"
+Requires-Dist: types-python-dateutil; extra == "dev"
+Requires-Dist: pre-commit>=3.5; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: python-dotenv>=1.0; extra == "examples"
+Dynamic: license-file
+
+
+# Aspy21
+
+**Python Client for Aspen InfoPlus.21 (IP.21)**
+
+[![PyPI version](https://img.shields.io/pypi/v/aspy21.svg)](https://pypi.org/project/aspy21/)
+[![Python versions](https://img.shields.io/pypi/pyversions/aspy21.svg)](https://pypi.org/project/aspy21/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Tests](https://github.com/bazdalaz/aspy21/actions/workflows/tests.yml/badge.svg)](https://github.com/bazdalaz/aspy21/actions)
+
+> **Note**: This is an independent, unofficial client library. Not affiliated with AspenTech.
+
+---
+
+## Overview
+
+**aspy21** is a modern, high-performance Python client for Aspen InfoPlus.21 (IP.21) built on the AspenOne ProcessData REST API. It provides unified access to process historian data with pandas DataFrame output, automatic batching, and intelligent retry logic.
+
+### Key Capabilities
+
+- REST-based communication with Aspen IP.21 historian
+- Basic HTTP authentication (cross-platform compatible)
+- Tag search with wildcards and description filtering
+- Unified interface for analog, discrete, and text tags
+- Support for RAW, INT, SNAPSHOT, and AVG reader types
+- Pandas DataFrame output with optional status columns
+- Configurable row limits and query parameters
+- Built-in retry logic with exponential backoff
+- Type-annotated and fully tested
+
+### Use Cases
+
+- Industrial data analysis and reporting
+- Integration with data analytics pipelines
+- Process monitoring and dashboard development
+- Time-series data extraction and transformation
+
+---
+
+## Installation
+
+Install via pip:
+
+```bash
+pip install aspy21
+```
+
+### Requirements
+
+- Python 3.9+
+- httpx >= 0.27
+- pandas >= 2.0
+- tenacity >= 9.0
+
+---
+
+## Quick Start
+
+### Basic Usage with Context Manager
+
+```python
+from aspy21 import AspenClient, ReaderType
+
+# Initialize client using context manager (recommended)
+with AspenClient(
+    base_url="https://aspen.myplant.local/ProcessData",
+    auth=("user", "password")
+) as client:
+    # Read historical data
+    df = client.read(
+        tags=["ATI111", "AP101.PV"],
+        start="2025-06-20 08:00:00",
+        end="2025-06-20 09:00:00",
+        interval=600,
+        read_type=ReaderType.RAW
+    )
+
+    print(df)
+    # Connection automatically closed
+```
+
+---
+
+## Authentication
+
+### HTTP Basic Authentication
+
+```python
+with AspenClient(
+    base_url="https://aspen.example.com/ProcessData",
+    auth=("user", "password")
+) as client:
+    # Your code here
+    pass
+```
+
+### No Authentication
+
+For public or internal endpoints:
+
+```python
+with AspenClient(
+    base_url="http://aspen.example.com/ProcessData"
+) as client:
+    # Your code here
+    pass
+```
+
+---
+
+## API Reference
+
+### AspenClient
+
+**Constructor Parameters** (all except `base_url` are keyword-only):
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `base_url` | str | required | Base URL of Aspen ProcessData REST API |
+| `auth` | Auth\|tuple\|None | None | Authentication as (username, password) tuple or httpx Auth object |
+| `timeout` | float | 30.0 | Request timeout in seconds |
+| `verify_ssl` | bool | True | Whether to verify SSL certificates |
+| `datasource` | str\|None | None | Aspen datasource name (required for search) |
+
+### read() Method
+
+**Parameters**:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `tags` | Iterable[str] | required | List of tag names to retrieve |
+| `start` | str | required | Start timestamp (ISO format) |
+| `end` | str | required | End timestamp (ISO format) |
+| `interval` | int\|None | None | Interval in seconds for aggregated data |
+| `read_type` | ReaderType | RAW | Data retrieval mode |
+| `include_status` | bool | True | Include status column in output |
+| `max_rows` | int | 100000 | Maximum rows to return per tag |
+
+**Returns**: pandas.DataFrame with time index and columns for each tag.
+
+### search() Method
+
+**Parameters**:
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `tag` | str | required | Tag name pattern with wildcards (`*`, `?`). Use `"*"` for all tags. |
+| `description` | str\|None | None | Description filter (case-insensitive substring) |
+| `case_sensitive` | bool | False | Whether tag matching is case-sensitive |
+| `max_results` | int | 10000 | Maximum number of results to return |
+
+**Returns**: List of dicts with 'name' and 'description' keys.
+
+**Requirements**:
+- `tag` parameter is required
+- `datasource` must be configured in AspenClient
+
+**Wildcards**:
+- `*` - Matches any number of characters
+- `?` - Matches exactly one character
+
+**Examples**:
+```python
+# Find all temperature tags
+tags = client.search(tag="TEMP*")
+
+# Search all tags by description
+tags = client.search(tag="*", description="reactor")
+
+# Combine filters
+tags = client.search(tag="AI_1*", description="pressure")
+```
+
+### ReaderType Enum
+
+Available reader types:
+
+- `ReaderType.RAW` - Raw data points as stored
+- `ReaderType.INT` - Interpolated values at intervals
+- `ReaderType.SNAPSHOT` - Current snapshot of tag values
+- `ReaderType.AVG` - Average values over intervals
+
+---
+
+## Configuration
+
+### Connection Settings
+
+```python
+with AspenClient(
+    base_url="https://aspen.example.com/ProcessData",
+    auth=("user", "password"),
+    timeout=60.0,           # Request timeout (seconds)
+    verify_ssl=True,        # SSL certificate verification
+    datasource="IP21"       # Required for search operations
+) as client:
+    # Your code here
+    pass
+```
+
+### Retry Behavior
+
+The client automatically retries failed requests with exponential backoff:
+
+- Maximum attempts: 3
+- Initial delay: 0.5 seconds
+- Maximum delay: 8 seconds
+
+---
+
+## Error Handling
+
+```python
+from aspy21 import AspenClient
+import httpx
+
+try:
+    with AspenClient(
+        base_url="https://aspen.example.com/ProcessData",
+        auth=("user", "password")
+    ) as client:
+        df = client.read(
+            tags=["ATI111"],
+            start="2025-06-20 08:00:00",
+            end="2025-06-20 09:00:00"
+        )
+except httpx.HTTPStatusError as e:
+    print(f"HTTP error: {e.response.status_code}")
+except httpx.RequestError as e:
+    print(f"Connection error: {e}")
+```
+
+---
+
+## Development
+
+### Running Tests
+
+```bash
+# Install development dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run with coverage
+pytest --cov=src/aspy21 --cov-report=html
+```
+
+### Type Checking
+
+```bash
+pyright
+```
+
+### Code Formatting
+
+```bash
+ruff format
+```
+
+---
+
+## Dependencies
+
+### Core Dependencies
+
+- **httpx** (>= 0.27) - HTTP client with async support
+- **pandas** (>= 2.0) - DataFrame output and date parsing
+- **tenacity** (>= 9.0) - Retry logic with exponential backoff
+
+### Development Dependencies
+
+- pytest, pytest-cov - Testing framework
+- respx - HTTP mocking for tests
+- ruff - Code formatting and linting
+- pyright - Static type checking
+- pre-commit - Git hooks
+
+---
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) file for details.
+
+---
+
+## Contributing
+
+Contributions are welcome. Please ensure:
+
+1. All tests pass (`pytest`)
+2. Code is formatted (`ruff format`)
+3. Type checking passes (`pyright`)
+4. Coverage remains above 75%
+
+---
+
+## Support
+
+For issues, questions, or feature requests, please open an issue on [GitHub](https://github.com/bazdalaz/aspy21/issues).
+
+---
+
+## Disclaimer
+
+This project is an independent open-source client library and is not affiliated with, endorsed by, or sponsored by AspenTech. "Aspen InfoPlus.21", "IP.21", and "AspenTech" are trademarks or registered trademarks of Aspen Technology, Inc.
+
+This software interacts with Aspen InfoPlus.21 systems through their documented REST API endpoints. Users must have appropriate licenses and authorization to access AspenTech systems.
+
+Users are responsible for compliance with their AspenTech license agreements and applicable terms of service. This library merely provides a technical interface and does not grant any rights to AspenTech software or services.

aspy21-0.1.1b8.dist-info/RECORD

@@ -0,0 +1,11 @@
+aspy21/__init__.py,sha256=ClsPhRKAP51Ne01EeSNPxz45pYPKranPX5g5Jlfjmfw,534
+aspy21/_version.py,sha256=Kq5TYovpH5dQ4g5K3qTstRlYHf54jgTfsA0GNDsUyPc,712
+aspy21/cache.py,sha256=pRIaxaI3yNJcOZ7SiLI_KNBRdMqbFq1sDPW7y-ezqtU,1158
+aspy21/client.py,sha256=OP5D7IhWHTWv_kmrBT-1qnE3KijnGNwgBrPswj6AnFs,24941
+aspy21/models.py,sha256=IXHAB2e0xB_lBmWZ7Z0bmSilejFjUzRpDKNJPdRgByk,468
+aspy21/utils.py,sha256=7BFx1O1zGaN3fxqdYC_-vYx91ARDFmSHuxdMblxmmUc,646
+aspy21-0.1.1b8.dist-info/licenses/LICENSE,sha256=N4WQNfHzhpXKz7lrcW0D94maukUHJ8dHgCDpykLvmSI,1065
+aspy21-0.1.1b8.dist-info/METADATA,sha256=Ej_MiU3XmKojzWFZaa0-Ap0wtIgXsk3xKxJ06-3iP7I,10011
+aspy21-0.1.1b8.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+aspy21-0.1.1b8.dist-info/top_level.txt,sha256=Xc09Tx1mB3tpPre7oO14j05v2BZvjeyvkwYFpy6TMrQ,7
+aspy21-0.1.1b8.dist-info/RECORD,,

aspy21-0.1.1b8.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aspy21-0.1.1b8.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 bazdalaz
+
+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.

aspy21-0.1.1b8.dist-info/top_level.txt

@@ -0,0 +1 @@
+aspy21