triggerware 0.1.0__tar.gz

triggerware-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.3
+Name: triggerware
+Version: 0.1.0
+Summary: 
+Author: godofavacyn
+Author-email: godofavacyn <aidenmeyer@mailbox.org>
+Requires-Dist: jayson-rpc
+Requires-Dist: sphinx
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# python-client

triggerware-0.1.0/README.md

@@ -0,0 +1 @@
+# python-client

triggerware-0.1.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "triggerware"
+version = "0.1.0"
+description = ""
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{name = "godofavacyn", email = "aidenmeyer@mailbox.org"}]
+dependencies = [
+   "jayson-rpc",
+   "sphinx"
+]
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.11.0"]
+build-backend = "uv_build"

triggerware-0.1.0/src/triggerware/__init__.py

@@ -0,0 +1,6 @@
+from triggerware._triggerware_client import *
+from triggerware._interfaces import *
+from triggerware._queries import * 
+from triggerware._subscriptions import *
+from triggerware._result_set import *
+from triggerware._types import *

triggerware-0.1.0/src/triggerware/_external_connector.old

@@ -0,0 +1,130 @@
+from typing import Any, TYPE_CHECKING, Callable
+import threading
+import inspect
+import importlib
+
+if TYPE_CHECKING:
+    import triggerware as tw
+
+sql_types = {
+    "str": "casesensitive",
+    "int": "int",
+}
+
+
+class ConnectorManager:
+    def __init__(
+        self,
+        tw_client: "tw.TriggerwareClient",
+        external_address: str,
+        external_port: int,
+    ) -> None:
+        self._client: "tw.TriggerwareClient" = tw_client
+        self._address = external_address
+        self._port = external_port
+        self._lock = threading.Lock()
+        self._conn_names: set[str] = set()
+        self._gen_functions: dict[str, Callable[..., Any]] = {}
+        threading.Thread(target=self._run, daemon=True).start()
+
+    def create_schema(self, schema: str):
+        params = {"name": schema}
+        _ = self._client.json_rpc.call("create-sql-schema", params)
+
+    def add_connector(self, connector: "Connector"):
+        generators: list[dict] = []
+        with self._lock:
+            if connector.name in self._conn_names:
+                raise ValueError(
+                    f"Connector with name {connector.name} already exists."
+                )
+            self._conn_names.add(connector.name)
+            for gen_name, generator in connector.generators.items():
+                generators.append(
+                    {
+                        "name": gen_name,
+                        "cost": generator.cost,
+                        "inputs": generator.inputs,
+                    }
+                )
+                self._gen_functions[gen_name] = generator.func
+        params = {
+            "columns": connector.columns,
+            "generator": generators,
+            "host": self._address,
+            "port": self._port,
+            "schema": connector.schema,
+            "name": connector.name,
+        }
+        _ = self._client.json_rpc.call("define-external-jsonrpc-table", params)
+
+    def _run(self):
+        # for conn in TcpStreamConnection.serve(self._address, self._port):
+        async def handler(conn: JsonRpcStreamConnection):
+            @conn.method()
+            def generate(
+                inputs: list[Any] = [],
+                name: str = "",
+                limit=None,
+                notify_timelimit=None,
+            ):
+                with self._lock:
+                    if name in self._gen_functions:
+                        return self._gen_functions[name](*inputs)
+                    else:
+                        raise ValueError(f"'{name}' not found in connectors.")
+            await conn.wait_closed()
+
+    async def close(self):
+        with self._lock:
+            await self._client.close()
+
+    @property
+    def is_closed(self) -> bool:
+        with self._lock:
+            return self._client.is_closed
+
+
+class Generator:
+    def __init__(
+        self, name: str, func: Callable[..., Any], inputs: list[str], cost: int
+    ):
+        self.name = name
+        self.func = func
+        self.inputs = inputs
+        self.cost = cost
+
+
+class Connector:
+    def __init__(
+        self,
+        *,
+        name: str,
+        columns: list[tuple[str, str | type]],
+        schema: str = "DEMO",
+    ):
+        self.name = name
+        self.schema = schema
+        try:
+            type_name = lambda ty: (
+                sql_types[ty.__name__] if isinstance(ty, type) else ty
+            )
+            self.columns = [[name, type_name(ty)] for name, ty in columns]
+        except KeyError as e:
+            raise TypeError(f"Unsupported type in columns: {e}")
+        self.generators: dict[str, Generator] = {}
+        self.generator_count = 0
+
+    def generate(self, cost: int = 1):
+        def decorator(func: Callable[..., Any]):
+            gen_name = f"{self.name}__{self.generator_count}"
+            inputs = [
+                param.name for param in inspect.signature(func).parameters.values()
+            ]
+            self.generators[gen_name] = Generator(gen_name, func, inputs, cost)
+            self.generator_count += 1
+            return func
+
+        return decorator
+
+__all__ = ["ConnectorManager", "Connector", "Generator"]

triggerware-0.1.0/src/triggerware/_interfaces.py

@@ -0,0 +1,26 @@
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    import triggerware as tw
+
+class TriggerwareObject:
+    """Anything that stores a connection to a triggerware client. Most of these objects have a handle,
+    but it is useful to represent certain handleless things, such as Views, as triggerware objects
+    since they need direct access to the triggerware client.
+    """
+    client:"tw.TriggerwareClient" 
+    handle: int | None = None
+
+
+class ResourceRestricted:
+    """Anything that requires resource limits, such as queries that need to be executed."""
+    row_limit: int | None = None
+    timeout: float | None = None
+
+
+class Query:
+    """Anything with a query, language, and schema."""
+    query: str
+    language: str
+    schema: str
+
+__all__ = ["TriggerwareObject", "ResourceRestricted", "Query"]

triggerware-0.1.0/src/triggerware/_queries.py

@@ -0,0 +1,403 @@
+from abc import ABC, abstractmethod
+from typing import Any, Callable, TYPE_CHECKING, Self
+
+from triggerware._types import InvalidQueryException, PreparedQueryException, PolledQueryControlParameters
+
+if TYPE_CHECKING:
+    import triggerware as tw
+
+from ._interfaces import Query, TriggerwareObject, ResourceRestricted
+from jayson_rpc import InternalErrorException, ServerErrorException, JsonRpcException
+from ._result_set import ResultSet
+
+
+class QueryRestriction(ResourceRestricted):
+    """A simple query restriction, supporting row limits and time limits."""
+
+    def __init__(self, row_limit: int | None = None, timeout: float | None = None):
+        self.row_limit = row_limit
+        self.timeout = timeout
+
+
+class FolQuery(Query):
+    """A query written in FOL for execution on the Triggerware server."""
+
+    def __init__(self, query: str, schema: str = "DEMO", /):
+        self.query = query
+        self.language = "fol"
+        self.schema = schema
+
+
+class SqlQuery(Query):
+    """A query written in SQL for execution on the Triggerware server."""
+
+    def __init__(self, query: str, schema: str = "DEMO", /):
+        self.query = query
+        self.language = "sql"
+        self.schema = schema
+
+
+class AbstractQuery[T](Query, ResourceRestricted, TriggerwareObject):
+    base_parameters: dict[str, Any]
+
+    def __init__(
+        self,
+        client: "tw.TriggerwareClient",
+        query: "tw.Query | str",
+        restriction: "tw.ResourceRestricted | None" = None,
+        /,
+    ):
+        self.client = client
+        if isinstance(query, str):
+            query = SqlQuery(query)
+
+        self.query = query.query
+        self.language = query.language
+        self.schema = query.schema
+        self.base_parameters = {
+            "query": self.query,
+            "language": self.language,
+            "schema": self.schema,
+        }
+
+        if client.default_fetch_size is not None:
+            self.row_limit = client.default_fetch_size
+        if client.default_timeout is not None:
+            self.timeout = client.default_timeout
+        if restriction is not None:
+            self.row_limit = restriction.row_limit or self.row_limit
+            self.timeout = restriction.timeout or self.timeout
+        if self.row_limit is not None:
+            self.base_parameters["limit"] = self.row_limit
+        if self.timeout is not None:
+            self.base_parameters["timelimit"] = self.timeout
+
+    async def validate(self) -> None:
+        """Validates the query on the server. Raises an exception if the query is invalid.
+
+        Raises:
+            InvalidQueryException: If the query is invalid.
+            InternalErrorException: If an internal error occurs.
+            ServerErrorException: If a server error occurs.
+        """
+
+        params = self.base_parameters.copy()
+
+        try:
+            await self.client.json_rpc.call("validate", params)
+        except InternalErrorException as e:
+            raise e
+        except ServerErrorException as e:
+            raise e
+        except JsonRpcException as e:
+            raise InvalidQueryException(e.message)
+
+
+class View[T](AbstractQuery[T]):
+    """
+    A simple reusable view of a query. May be executed any number of times. Unlike other queries,
+    A View's "handle" is always None - it is only stored locally.
+    """
+
+    def __init__(
+        self,
+        client: "tw.TriggerwareClient",
+        query: "tw.Query | str",
+        restriction: "tw.ResourceRestricted | None" = None,
+        /,
+    ):
+        """Initialize a View instance.
+
+        Args:
+            client: The Triggerware client.
+            query: The query to execute.
+            restriction: Optional restrictions to apply.
+        """
+        super().__init__(client, query, restriction)
+
+    async def execute(
+        self, restriction: "tw.ResourceRestricted | None" = None
+    ) -> "tw.ResultSet[T]":
+        """
+        Executes the query on the connected triggerware server and returns a result set.
+
+        Args:
+            restriction: Optional restrictions to apply to the query.
+
+        Raises:
+            ServerErrorException: If the server encounters an error while executing the query.
+            InvalidQueryException: If the query is invalid or cannot be executed.
+        """
+
+        params = self.base_parameters.copy()
+        if restriction is not None:
+            if restriction.row_limit is not None:
+                params["limit"] = restriction.row_limit
+            if restriction.timeout is not None:
+                params["timelimit"] = restriction.timeout
+
+        eq_result = None
+        try:
+            eq_result = await self.client.json_rpc.call("execute-query", params)
+        except ServerErrorException as e:
+            raise e
+        except JsonRpcException as e:
+            raise InvalidQueryException(e.message)
+        return ResultSet(self.client, eq_result)
+
+
+class PreparedQuery[T](AbstractQuery[T]):
+    prepared_params: list[Any]
+    input_signature_names: list[str]
+    input_signature_types: list[str]
+    uses_named_params: bool
+
+    _TYPE_MAP: dict[str, Callable[[str], bool]] = {
+        "double": lambda x: isinstance(x, float),
+        "integer": lambda x: isinstance(x, int),
+        "number": lambda x: isinstance(x, (int, float)),
+        "boolean": lambda x: isinstance(x, bool),
+        "stringcase": lambda x: isinstance(x, str),
+        "stringnocase": lambda x: isinstance(x, str),
+        "stringagnostic": lambda x: isinstance(x, str),
+        "date": lambda x: isinstance(x, str),
+        "time": lambda x: isinstance(x, str),
+        "timestamp": lambda x: isinstance(x, str),
+        "interval": lambda x: isinstance(x, str),
+    }
+
+    def __init__(
+        self,
+        client: "tw.TriggerwareClient",
+        query: "tw.Query | str",
+        restriction: "tw.ResourceRestricted | None" = None,
+        /,
+    ):
+        super().__init__(client, query, restriction)
+
+    async def register(self) -> Self:
+        """Registers this prepared query on the Triggerware server"""
+        registration = await self.client.json_rpc.call("prepare-query", self.base_parameters)
+        self.prepared_params = [None] * len(registration["inputSignature"])
+        self.handle = registration["handle"]
+        self.uses_named_params = registration["usesNamedParameters"]
+        self.input_signature_names = list(
+            map(lambda x: x["attribute"], registration["inputSignature"])
+        )
+        self.input_signature_types = list(
+            map(lambda x: x["type"], registration["inputSignature"])
+        )
+        if self.handle is not None:
+            self.client.register_handle(self.handle)
+        return self
+
+    def set_parameter(self, position: str | int, param: Any) -> None:
+        """Sets an unbound value in the query string to a specific value.
+
+        Args:
+            position: The name or position of the parameter to set.
+            param: The value to set the parameter to.
+        """
+
+        if not self.uses_named_params and isinstance(position, str):
+            raise PreparedQueryException("This query uses positional parameters.")
+
+        if self.uses_named_params and isinstance(position, int):
+            raise PreparedQueryException("This query uses named parameters.")
+
+        try:
+            index = (
+                self.input_signature_names.index(position)
+                if isinstance(position, str)
+                else position
+            )
+            expected_type = self.input_signature_types[index]
+        except Exception:
+            raise PreparedQueryException("Invalid parameter name or position.")
+
+        if self.language == "sql":
+            if not PreparedQuery._TYPE_MAP[expected_type](
+                param
+            ):  # Assuming type_map exists
+                raise PreparedQueryException(
+                    f"Expected type {expected_type}, got {type(param).__name__}"
+                )
+
+        self.prepared_params[index] = param
+
+    def get_parameter(self, position: str | int) -> Any:
+        """Gets the value of a parameter in the query string.
+
+        Args:
+            position: The name or position of the parameter to retrieve.
+        """
+
+        if not self.uses_named_params and isinstance(position, str):
+            raise PreparedQueryException("This query uses positional parameters.")
+
+        if self.uses_named_params and isinstance(position, int):
+            raise PreparedQueryException("This query uses named parameters.")
+
+        try:
+            index = (
+                self.input_signature_names.index(position)
+                if isinstance(position, str)
+                else position
+            )
+            parameter = self.prepared_params[index]
+        except Exception:
+            raise PreparedQueryException("Invalid parameter name or position.")
+
+        return parameter
+
+    def clone(self) -> "PreparedQuery[T]":
+        """Clones this prepared query with the same parameters."""
+        clone = PreparedQuery[T](self.client, self, self)
+        clone.prepared_params = self.prepared_params[:]
+        return clone
+
+    async def execute(
+        self, restriction: "tw.ResourceRestricted | None" = None
+    ) -> "tw.ResultSet[T]":
+        """Executes this query on the Triggerware server and returns a ResultSet.
+
+        Args:
+            restriction: Optional restrictions to apply to the query.
+        """
+
+        parameters = {
+            "handle": self.handle,
+            "inputs": self.prepared_params,
+        }
+        if restriction:
+            if restriction.row_limit is not None:
+                parameters["limit"] = restriction.row_limit
+            if restriction.timeout is not None:
+                parameters["timelimit"] = restriction.timeout
+
+        eq_result = await self.client.json_rpc.call("create-resultset", parameters)
+        return ResultSet[T](self.client, eq_result)
+
+
+class PolledQuery[T](ABC, AbstractQuery[T]):
+    """A PolledQuery is a query that is executed by the TW server on a set schedule.
+    As soon as a PolledQuery is created, it is executed by the server, and the response (a set of
+    "rows") establishes a "current state" of the query. For each succeeding execution (referred to as
+    polling the query):
+
+    - The new answer is compared with the current state, and the differences are sent to the
+      Triggerware client in a notification containing a RowsDelta value.
+    - The new answer then becomes the current state to be used for comparison with the result of the
+      next poll of the query.
+
+    Like any other query, a PolledQuery has a query string, a language (FOL or SQL), and a schema.
+
+    A polling operation may be performed at any time by executing the Poll method.
+    Some details of reporting and polling can be configured with a PolledQueryControlParameters
+    value that is supplied to the constructor of a PolledQuery.
+
+    An instantiable subclass of PolledQuery must provide a HandleNotification method to
+    handle notifications of changes to the current state. Errors can occur during a polling operation
+    (e.g., timeout, inability to contact a data source). When such an error occurs, the TW Server will
+    send an "error" notification. An instantiable subclass of PolledQuery may provide a
+    HandleError method to handle error notifications.
+
+    Polling may be terminated when Dispose is called.
+
+    If a polling operation is ready to start (whether due to its schedule or an explicit poll request)
+    and a previous poll of the query has not completed, the poll operation that is ready to start is
+    skipped, and an error notification is sent to the client.
+    """
+
+    method_name: str
+
+    def __init__(
+        self,
+        client: "tw.TriggerwareClient",
+        query: "tw.Query | str",
+        schedule: "tw.PolledQuerySchedule",
+        restriction: "tw.ResourceRestricted | None" = None,
+        controls: "tw.PolledQueryControlParameters | None" = None,
+    ) -> None:
+        """Initialize a PolledQuery instance.
+
+        Args:
+            client: The Triggerware client.
+            query: The query to execute.
+            restriction: Optional restrictions to apply.
+            controls: Control parameters for polling.
+            schedule: The polling schedule.
+        """
+
+        super().__init__(client, query, restriction)
+        self.method_name = "poll" + str(self.client._poll_counter)  # type: ignore
+        self.client._poll_counter += 1  # type: ignore
+
+        def notify_handler(delta: dict[str, Any] | list[Any], handle: int, timestamp: str, initialized: bool = False) -> None:
+            if "delta" in delta:
+                delta = delta["delta"]  # type: ignore
+            self.handle_notification(delta["added"], delta["deleted"])  # type: ignore
+        self.client.json_rpc.add_method(name=self.method_name, func=notify_handler)
+
+        def process_schedule(schedule: "tw.PolledQuerySchedule") -> Any:
+            if isinstance(schedule, int):
+                return schedule
+            if isinstance(schedule, list):
+                return [process_schedule(x) for x in schedule]
+
+            schedule.validate()
+            return schedule.__dict__
+
+        self.base_parameters["method"] = self.method_name
+        self.base_parameters["schedule"] = process_schedule(schedule)
+        if not controls:
+            controls = PolledQueryControlParameters(True, 'with delta', False)
+        self.base_parameters["report-initial"] = controls.report_initial
+        self.base_parameters["report-noops"] = controls.report_unchanged
+        self.base_parameters["delay-schedule"] = controls.delay
+
+    async def register(self) -> Self:
+        registration = await self.client.json_rpc.call(
+            "create-polled-query", self.base_parameters
+        )
+        self.handle = registration["handle"]
+        self.signature = []
+        if "signature" in registration:
+            self.signature = registration["signature"]
+        if self.handle is not None:
+            self.client.register_handle(self.handle)
+        return self
+
+
+    async def close(self) -> bool:
+        """Dispose of this polled query, stopping further polling and notifications."""
+        return await self.client.json_rpc.call("close-polled-query", [self.handle])
+
+    async def poll_now(self) -> None:
+        """Perform an on-demand poll of this query (temporarily disregarding the set schedule)."""
+        parameters: dict[str, Any] = {"handle": self.handle}
+        if self.timeout is not None:
+            parameters["timelimit"] = self.timeout
+        await self.client.json_rpc.call("poll-now", parameters)
+
+
+    @abstractmethod
+    def handle_notification(self, added: list[Any], deleted: list[Any]) -> None:
+        """Override this method to handle the polled query's changes in data. The polled query's
+            schedule determines when this method will be called.
+
+        Args:
+            added: Rows added since the last poll.
+            deleted: Rows deleted since the last poll.
+        """
+        pass
+
+__all__ = [
+    "QueryRestriction",
+    "FolQuery",
+    "SqlQuery",
+    "AbstractQuery",
+    "View",
+    "PreparedQuery",
+    "PolledQuery",
+]

triggerware-0.1.0/src/triggerware/_result_set.py

@@ -0,0 +1,86 @@
+from typing import Any, TYPE_CHECKING
+if TYPE_CHECKING:
+    import triggerware as tw
+
+from ._interfaces import TriggerwareObject, ResourceRestricted
+
+class ResultSet[T](TriggerwareObject, ResourceRestricted):
+    """Represents a result set from the server after executing a query. Result sets are iterable and
+    can fetch new rows using next(resultset), or, for multiple rows, resultset.pull(n). Each 'row'
+    is a tuple of values determined by the signature of the executed query.
+    """
+    cache: list[T]
+    cache_idx: int
+    exhausted: bool
+
+    def __init__(
+        self,
+        client: "tw.TriggerwareClient",
+        eq_result: dict[str, Any],
+        row_limit: int | None = None,
+        timeout: float | None = None,
+    ) -> None:
+        """Initialize a ResultSet instance.
+
+        Args:
+            client: The Triggerware client.
+            eq_result: The result dictionary from the server.
+            row_limit: The row limit for fetching results.
+            timeout: The timeout for fetching results.
+        """
+        self.client = client
+        self.handle = None if 'handle' not in eq_result else eq_result['handle']
+        self.row_limit = row_limit if row_limit is not None else client.default_fetch_size
+        self.timeout = timeout if timeout is not None else client.default_timeout
+        self.signature = []
+        self.cache = []
+        self.cache_idx = 0
+        self.exhausted = False
+        if 'signature' in eq_result:
+            self.signature = eq_result['signature']
+        if 'batch' in eq_result:
+            if 'tuples' in eq_result['batch']:
+                self.cache = eq_result['batch']['tuples']
+                self.exhausted = self.handle == None
+
+    def __aiter__(self) -> "ResultSet[T]":
+        return self
+    
+    async def __anext__(self) -> T:
+        if self.cache_idx >= len(self.cache):
+            if self.exhausted:
+                raise StopAsyncIteration
+
+            result = await self.client.json_rpc.call("next-resultset-batch", [self.handle, self.row_limit, self.timeout])
+            self.cache = result["batch"]["tuples"]
+            self.cache_idx = 0
+            self.exhausted = result["batch"]["exhausted"]
+
+            if not self.cache:
+                raise StopAsyncIteration
+
+        value = self.cache[self.cache_idx]
+        self.cache_idx += 1
+        return value
+
+    async def pull(self, n: int) -> list[T]:
+        """Fetches the next n rows from the result set.
+
+        Args:
+            n: The number of rows to fetch. Will fetch fewer if the result set is exhausted.
+        """
+        items = []
+        for _ in range(n):
+            try:
+                items.append(await anext(self))
+            except StopIteration:
+                break
+        return items
+
+__all__ = ["ResultSet"]
+
+
+
+
+
+

triggerware-0.1.0/src/triggerware/_subscriptions.py

@@ -0,0 +1,232 @@
+# from abc import ABC, abstractmethod
+#
+# from typing import TYPE_CHECKING
+# if TYPE_CHECKING:
+#     import triggerware as tw
+#
+# from ._queries import AbstractQuery
+# from ._interfaces import TriggerwareObject
+# from ._types import SubscriptionException
+# from ._triggerware_client import TriggerwareClient
+#
+# class Subscription[T](ABC, AbstractQuery[T]):
+#     """
+#     A Subscription represents some future change to the data managed by the TW server about which
+#     a client would like to be notified. Once created, this subscription will accept notifications from
+#     the server when a change occurs, then call the overridden method handle_notification.
+#
+#     By default, subscriptions are **active** when they are created—they are immediately registered
+#     with the server and start receiving notifications. This behavior may be changed upon construction,
+#     or by calling either the activate or deactivate methods.
+#
+#     Subscriptions may either be created by passing in a TriggerwareClient, in which case they
+#     are immediately registered with the server, OR by passing in a BatchSubscription. See
+#     BatchSubscription documentation for more information.
+#     """
+#     _batch: "BatchSubscription | None"
+#     label: str
+#     _active: bool
+#
+#     @property
+#     def active(self) -> bool:
+#         return self._active
+#
+#     @property
+#     def part_of_batch(self) -> bool:
+#         return self._batch is not None
+#
+#     def __init__(
+#         self,
+#         client_or_batch: "tw.TriggerwareClient | tw.BatchSubscription",
+#         query: "tw.Query",
+#         active: bool = True
+#     ):
+#         """
+#         Initialize a Subscription instance.
+#
+#         Args:
+#             client_or_batch (tw.TriggerwareClient | tw.BatchSubscription): The client or batch to register with.
+#             query (tw.Query): The query to subscribe to.
+#             active (bool, optional): Whether the subscription should be active upon creation. Defaults to True.
+#         """
+#         client = client_or_batch if isinstance(client_or_batch, TriggerwareClient) else client_or_batch.client
+#         super().__init__(client, query)
+#         self._active = False
+#         self._batch = None
+#         self.label = "sub" + str(client._sub_counter) # type: ignore
+#         client._sub_counter += 1 # type: ignore
+#         self.base_parameters["label"] = self.label
+#
+#
+#         if isinstance(client_or_batch, TriggerwareClient):
+#             if active:
+#                 self.activate()
+#         else:
+#             self.add_to_batch(client_or_batch)
+#
+#     def activate(self):
+#         """
+#         Activates the subscription, enabling notifications to be sent from the server.
+#
+#         Raises:
+#             SubscriptionException: If the subscription is already active or is part of a batch.
+#         """
+#         from triggerware.types import SubscriptionException
+#         if self._batch:
+#             raise SubscriptionException("Cannot activate subscription that is part of a batch.")
+#
+#         if self._active:
+#             raise SubscriptionException("Subscription is already active.")
+#
+#         params = {**self.base_parameters, "method": self.label, "combine": False}
+#         await self.client.json_rpc.call("subscribe", params)
+#         def handler(x):
+#             self.handle_notification(x['tuple'])
+#         self.client.json_rpc.add_method(name=self.label, func=handler)
+#         self._active = True
+#
+#     def deactivate(self):
+#         """
+#         Deactivates the subscription, disabling notifications from the server.
+#
+#         Raises:
+#             SubscriptionException: If the subscription is already inactive or is part of a batch.
+#         """
+#         if self._batch:
+#             raise SubscriptionException("Cannot deactivate a subscription that is part of a batch.")
+#
+#         if not self._active:
+#             raise SubscriptionException("Subscription is already inactive.")
+#
+#         params = {**self.base_parameters, "method": self.label, "combine": False}
+#         self.client.json_rpc.call("unsubscribe", params)
+#         self.client.json_rpc.remove_method(self.label)
+#         self._active = False
+#
+#     def add_to_batch(self, batch: "BatchSubscription"):
+#         """
+#         Adds the subscription to the provided batch. Alternatively, you may call a batch's 
+#         add_subscription method.
+#
+#         Args:
+#             batch (BatchSubscription): The batch to add this subscription to.
+#
+#         Raises:
+#             SubscriptionException: If the subscription is already active, already part of a batch, or registered with a different client.
+#         """
+#         if self._active:
+#             raise SubscriptionException("Cannot add active subscription to a batch.")
+#
+#         if self._batch:
+#             raise SubscriptionException("Subscription is already part of another batch.")
+#
+#         if not self.client is batch.client:
+#             raise SubscriptionException("Subscription and batch registered with different clients.")
+#
+#         params = {**self.base_parameters, "method": batch.method_name, "combine": True}
+#         self.client.json_rpc.call("subscribe", params)
+#         batch._subscriptions[self.label] = self # type: ignore
+#         self._batch = batch
+#
+#     def remove_from_batch(self):
+#         """
+#         Removes the subscription from its current batch. Alternatively, you may call a batch's
+#         remove_subscription method.
+#
+#         Raises:
+#             SubscriptionException: If the subscription is not part of a batch.
+#         """
+#         if not self._batch:
+#             raise SubscriptionException("Subscription is not part of a batch.")
+#
+#         params = {**self.base_parameters, "method": self._batch.method_name, "combine": True}
+#         self.client.json_rpc.call("unsubscribe", params)
+#         if self.label in self._batch._subscriptions: # type: ignore
+#             del self._batch._subscriptions[self.label] # type: ignore
+#         self._batch = None
+#
+#     def _handle_notification_from_batch(self, data: list[T]):
+#         """
+#         Handles notifications from a batch subscription and dispatches them to the handler.
+#
+#         Args:
+#             data (list[T]): The data received in the notification.
+#         """
+#         for d in data:
+#             self.handle_notification(d)
+#     
+#     @abstractmethod
+#     def handle_notification(self, data: T):
+#         """
+#         Overload this function in an inheriting class to handle notifications that triggering the
+#         query will cause this function to activate.
+#
+#         Args:
+#             data (T): The data received in the notification.
+#         """
+#         pass
+#
+#
+# class BatchSubscription(TriggerwareObject):
+#     """
+#     A BatchSubscription groups one or more Subscription instances. Over time, new instances
+#     may be added to the BatchSubscription, and/or existing members may be removed. This is useful
+#     because a single transaction of a change in data on the triggerware server may be associated with
+#     multiple subscriptions.
+#
+#     By grouping these subscriptions, notifications may be properly handled by as many Subscription
+#     instances as necessary.
+#     """
+#
+#     def __init__(self, client: "tw.TriggerwareClient"):
+#         """
+#         Initialize a BatchSubscription instance.
+#
+#         Args:
+#             client (tw.TriggerwareClient): The Triggerware client.
+#         """
+#         self.client = client
+#         self.method_name = "batch" + str(client._batch_sub_counter) # type: ignore
+#         client._batch_sub_counter += 1 # type: ignore
+#         self._subscriptions: dict[str, Subscription] = {}
+#
+#         @self.client.json_rpc.method(self.method_name)
+#         def notify_handler(message):
+#             for match in message['matches']:
+#                 subscription = self._subscriptions.get(match['label'])
+#                 if subscription:
+#                     subscription._handle_notification_from_batch(match['tuples']) # type: ignore
+#
+#
+#     def add_subscription(self, subscription: Subscription):
+#         """
+#         Adds a subscription to the batch. Alternatively, you may call a subscription's
+#         add_to_batch method.
+#
+#         Args:
+#             subscription (Subscription): The subscription to add.
+#         """
+#         subscription.add_to_batch(self)
+#
+#     def remove_subscription(self, subscription: Subscription):
+#         """
+#         Removes a subscription from the batch. Alternatively, you may call a subscription's
+#         remove_from_batch method.
+#
+#         Args:
+#             subscription (Subscription): The subscription to remove.
+#
+#         Raises:
+#             SubscriptionException: If the subscription is not part of this batch.
+#         """
+#         if subscription.label not in self._subscriptions:
+#             raise SubscriptionException("Subscription is not part of this batch.")
+#
+#         subscription.remove_from_batch()
+#
+# __all__ = ["Subscription", "BatchSubscription"]
+#
+#
+#
+#
+#

triggerware-0.1.0/src/triggerware/_triggerware_client.py

@@ -0,0 +1,115 @@
+from typing import TYPE_CHECKING
+
+from jayson_rpc import JsonRpcConnection, JsonRpcStreamConnection, JsonRpcWebSocketConnection
+from ._queries import View
+
+if TYPE_CHECKING:
+    import triggerware as tw
+
+class TriggerwareClient:
+    """A TriggerwareClient provides a connection to a triggerware server. A client contains methods for
+    issuing a few specific requests that are supported by any Triggerware server. Classes that extend
+    TriggerwareClient for specific applications will implement their own application-specific methods
+    to make requests that are idiosyncratic to a Triggerware server for that application.
+
+    A TriggerwareClient can also manage Subscriptions. By subscribing to certain kinds of changes,
+    the client arranges to be notified when these changes occur in the data accessible to the server.
+    """
+
+    def __init__(self, json_rpc: JsonRpcConnection):
+        self.json_rpc = json_rpc
+
+        self._batch_sub_counter = 0
+        self._sub_counter = 0
+        self._poll_counter = 0
+        self._handles: list[int] = []
+
+        self.sql_mode: str = "fol"
+        self.default_fol_schema: str | None = None
+        self.default_sql_schema: str | None = None
+        self.default_fetch_size: int | None = None
+        self.default_timeout: float | None = None
+
+    @classmethod
+    async def connect_tcp(cls, host: str, port: int) -> "TriggerwareClient":
+        """Connect to a Triggerware server over TCP.
+
+        Args:
+            host: The server host.
+            port: The server port.
+        """
+        json_rpc = await JsonRpcStreamConnection.connect(host, port)
+        return cls(json_rpc)
+
+    @classmethod
+    async def connect_ws(cls, instance: str, api_key: str) -> "TriggerwareClient":
+        """Connect to a Triggerware server over WebSocket.
+
+        Args:
+            uri: The WebSocket URI to connect to.
+        """
+        uri = "ws://tw-instance-load-balancer-194323221.us-east-2.elb.amazonaws.com"
+        json_rpc = await JsonRpcWebSocketConnection.connect(
+            uri,
+            headers={
+                "TW-Instance": instance,
+                "Authorization": f"Bearer {api_key}",
+            }
+        )
+        return cls(json_rpc)
+
+    async def execute_query(
+        self,
+        query: "tw.Query | str",
+        restriction: "tw.ResourceRestricted | None" = None,
+    ) -> "tw.ResultSet":
+        """Executes a query on the connected server.
+
+        Args:
+            query: The query to execute.
+            restriction: Optional restrictions to apply to the query.
+
+        Returns:
+            tw.ResultSet: The result set from the server.
+
+        Raises:
+            InvalidQueryException: If the query is invalid.
+            InternalErrorException: If an internal error occurs.
+            ServerErrorException: If a server error occurs.
+        """
+        view = View(self, query, restriction)
+        return await view.execute()
+
+    async def validate_query(self, query: "tw.Query | str"):
+        """Validate a query string on the server. This method will raise an InvalidQueryException if
+        the query contains errors.
+
+        Args:
+            query: The query to validate.
+
+        Raises:
+            InvalidQueryException: If the query is invalid.
+            InternalErrorException: If an internal error occurs.
+            ServerErrorException: If a server error occurs.
+        """
+        return await View(self, query).validate()
+
+    async def close(self):
+        """
+        Closes the connection to the server.
+        """
+        await self.json_rpc.close()
+
+    @property
+    def is_closed(self) -> bool:
+        return self.json_rpc.is_closed
+
+    def register_handle(self, handle: int):
+        """Register a handle with this client. Not meant for external use.
+
+        Args:
+            handle (int): The handle to register.
+        """
+        self._handles.append(handle)
+
+__all__ = ["TriggerwareClient"]

triggerware-0.1.0/src/triggerware/_types.py

@@ -0,0 +1,103 @@
+import re
+from typing import Literal
+
+
+class TriggerwareClientException(Exception):
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.message = message
+    pass
+
+
+class InvalidQueryException(TriggerwareClientException):
+    pass
+
+
+class PolledQueryException(TriggerwareClientException):
+    pass
+
+
+class PreparedQueryException(TriggerwareClientException):
+    pass
+
+
+class SubscriptionException(TriggerwareClientException):
+    pass
+
+
+class PolledQueryControlParameters:
+    report_unchanged: bool 
+    report_initial: str
+    delay: bool
+
+    def __init__(
+        self,
+        report_unchanged: bool = False,
+        report_initial: Literal["none"] | Literal["with delta"] | Literal["without delta"] = "none",
+        delay: bool = False,
+    ):
+        self.report_unchanged = report_unchanged
+        self.report_initial = report_initial
+        self.delay = delay
+
+
+class PolledQueryCalendarSchedule:
+    days: str
+    hours: str
+    minutes: str
+    months: str
+    timezone: str
+    weekdays: str
+    _TIMEZONE_REGEX = re.compile(r"^[A-Za-z]+(?:_[A-Za-z]+)*(?:/[A-Za-z]+(?:_[A-Za-z]+)*)*$")
+
+    def __init__(
+        self,
+        days: str = "*",
+        hours: str = "*",
+        minutes: str = "*",
+        months: str = "*",
+        timezone: str = "UTC",
+        weekdays: str = "*",
+    ):
+        self.days = days
+        self.hours = hours
+        self.minutes = minutes
+        self.months = months
+        self.timezone = timezone
+        self.weekdays = weekdays
+
+    @staticmethod
+    def _validate_time(unit: str, value: str, min: int, max: int):
+        if value == "*":
+            return
+
+        parts = [y for x in re.split(",", value) for y in re.split("-", x)]
+        for part in parts:
+            try:
+                parsed = int(part)
+            except ValueError:
+                raise PolledQueryException(f"Invalid {unit} value: {part}")
+            if parsed < min or parsed > max:
+                raise PolledQueryException(f"{unit} value out of range: {part}")
+
+    def validate(self):
+        self._validate_time("day", self.days, 1, 31)
+        self._validate_time("hour", self.hours, 0, 23)
+        self._validate_time("minute", self.minutes, 0, 59)
+        self._validate_time("month", self.months, 1, 12)
+        self._validate_time("weekday", self.weekdays, 0, 6)
+        if not self._TIMEZONE_REGEX.match(self.timezone):
+            raise PolledQueryException("Invalid timezone format")
+
+type PolledQuerySchedule = int | PolledQueryCalendarSchedule | list[PolledQuerySchedule]
+
+__all__ = [
+    "TriggerwareClientException",
+    "InvalidQueryException",
+    "PolledQueryException",
+    "PreparedQueryException",
+    "SubscriptionException",
+    "PolledQueryControlParameters",
+    "PolledQueryCalendarSchedule",
+    "PolledQuerySchedule",
+]