feat: added tables property to the PIAFDatabase

PIconnect/PIAF.py

@@ -4,6 +4,8 @@
 import warnings
 from typing import Any, Dict, List, Optional, Union, cast
 
+import pandas as pd
+
 from PIconnect import AF, PIAFAttribute, PIAFBase, PIConsts, _time
 from PIconnect._utils import InitialisationWarning
 from PIconnect.AFSDK import System
@@ -70,7 +72,7 @@ def _lookup_default_server() -> Optional[ServerSpec]:
 class PIAFDatabase(object):
     """Context manager for connections to the PI Asset Framework database."""
 
-    version = "0.2.0"
+    version = "0.3.0"
 
     servers: Dict[str, ServerSpec] = _lookup_servers()
     default_server: Optional[ServerSpec] = _lookup_default_server()
@@ -145,6 +147,11 @@ def children(self) -> Dict[str, "PIAFElement"]:
         """Return a dictionary of the direct child elements of the database."""
         return {c.Name: PIAFElement(c) for c in self.database.Elements}
 
+    @property
+    def tables(self) -> Dict[str, "PIAFTable"]:
+        """Return a dictionary of the tables in the database."""
+        return {t.Name: PIAFTable(t) for t in self.database.Tables}
+
     def descendant(self, path: str) -> "PIAFElement":
         """Return a descendant of the database from an exact path."""
         return PIAFElement(self.database.Elements.get_Item(path))
@@ -245,3 +252,34 @@ def parent(self) -> Optional["PIAFEventFrame"]:
     def children(self) -> Dict[str, "PIAFEventFrame"]:
         """Return a dictionary of the direct child event frames of the current event frame."""
         return {c.Name: self.__class__(c) for c in self.element.EventFrames}
+
+
+class PIAFTable:
+    """Container for PI AF Tables in the database."""
+
+    def __init__(self, table: AF.Asset.AFTable) -> None:
+        self._table = table
+
+    @property
+    def columns(self) -> List[str]:
+        """Return the names of the columns in the table."""
+        return [col.ColumnName for col in self._table.Table.Columns]
+
+    @property
+    def _rows(self) -> List[System.Data.DataRow]:
+        return self._table.Table.Rows
+
+    @property
+    def name(self) -> str:
+        """Return the name of the table."""
+        return self._table.Name
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        """Return the shape of the table."""
+        return (len(self._rows), len(self.columns))
+
+    @property
+    def data(self) -> pd.DataFrame:
+        """Return the data in the table as a pandas DataFrame."""
+        return pd.DataFrame([{col: row[col] for col in self.columns} for row in self._rows])

PIconnect/_typing/AF.py

@@ -34,6 +34,7 @@ class AFDatabase:
     def __init__(self, name: str) -> None:
         self.Name = name
         self.Elements = Asset.AFElements([Asset.AFElement("TestElement")])
+        self.Tables = Asset.AFTables([Asset.AFTable("TestTable")])
 
 
 class PISystem:

PIconnect/_typing/Asset.py

@@ -4,6 +4,7 @@
 
 from . import AF, Data, Generic
 from . import UnitsOfMeasure as UOM
+from . import dotnet as System
 from ._values import AFValue, AFValues
 
 __all__ = [
@@ -13,6 +14,8 @@
     "AFElement",
     "AFElements",
     "AFElementTemplate",
+    "AFTable",
+    "AFTables",
     "AFValue",
     "AFValues",
 ]
@@ -81,4 +84,16 @@ def __init__(
         self.PIPoint = pi_point
 
 
+class AFTable:
+    def __init__(self, name: str) -> None:
+        self.Name = name
+        self.Table: System.Data.DataTable
+
+
+class AFTables(List[AFTable]):
+    def __init__(self, elements: List[AFTable]) -> None:
+        self.Count: int
+        self._values = elements
+
+
 AttributeDict = Generic.Dictionary[str, AFAttribute]

PIconnect/_typing/dotnet/__init__.py

@@ -2,9 +2,15 @@
 
 from typing import Protocol
 
-from . import Net, Security
-
-__all__ = ["Net", "Security", "Exception", "TimeSpan"]
+from . import Data, Net, Security
+
+__all__ = [
+    "Data",
+    "Exception",
+    "Net",
+    "Security",
+    "TimeSpan",
+]
 
 
 class Exception:

docs/tutorials/piaf.rst

@@ -147,3 +147,25 @@ given server you can use the following code:
 
     import PIconnect as PI
     print(list(PI.PIAFDatabase.servers["ServerName"]["databases"].keys()))
+
+
+.. _piaf_tables:
+
+*********************************
+Accessing tables in the PI AF SDK
+*********************************
+
+It is possible to define custom SQL like tables in the PI AF SDK.
+These tables can be accessed using the :any:`PIAFDatabase.tables` attribute.
+This attribute is a dictionary of {name: table} pairs.
+The table can be loaded into a :any:`pandas.DataFrame` using the
+:any:`PIAFTable.data` property:
+
+.. code-block:: python
+
+    import PIconnect as PI
+
+    with PI.PIAFDatabase() as database:
+        table = database.tables["MyTable"]
+        df = table.data
+        print(df)