hgraph 0.3.26__tar.gz

hgraph-0.3.26/LICENSE

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

hgraph-0.3.26/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.1
+Name: hgraph
+Version: 0.3.26
+Summary:  A functional reactive platform used to process time-series streams. Provides support for backtest (simulation) and realtime time-series processing. Using a forward propagation graph with a microtask scheduler for the runtime engine. 
+License: MIT
+Keywords: reactive,graph,fpg,forward propogating graph,time series,functional reactive programming,frp,functional,time-series
+Author: Howard Henson
+Author-email: howard@henson.me.uk
+Requires-Python: >=3.11
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Provides-Extra: web
+Requires-Dist: duckdb
+Requires-Dist: frozendict (>=2.3.10)
+Requires-Dist: multimethod
+Requires-Dist: numpy (>=1.23)
+Requires-Dist: ordered-set (>=4.1.0)
+Requires-Dist: perspective-python (<3.0.0) ; extra == "web"
+Requires-Dist: polars (>=1.0)
+Requires-Dist: pyarrow (>=16.1.0)
+Requires-Dist: requests ; extra == "web"
+Requires-Dist: sortedcontainers (>=2.4.0)
+Requires-Dist: sphinx (>=7.4)
+Requires-Dist: sphinx-autodoc-typehints (>=2.3.0)
+Requires-Dist: sphinx_rtd_theme (>=2.0.0)
+Requires-Dist: sphinxcontrib-plantuml (>=0.30)
+Requires-Dist: sqlalchemy
+Requires-Dist: tornado ; extra == "web"
+Project-URL: Changelog, https://github.com/hhenson/hgraph/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/hhenson/hgraph/blob/main/docs/index.md
+Project-URL: Homepage, https://github.com/hhenson/hgraph
+Project-URL: Issues, https://github.com/hhenson/hgraph/blob/main/ISSUES.md
+Project-URL: Repository, https://github.com/hhenson/hgraph.git
+Description-Content-Type: text/markdown
+
+# hgraph
+A functional reactive programming engine with a Python front-end.
+
+This provides a DSL and runtime to support the computation of results over time, featuring
+a graph based directed acyclic dependency graph and the concept of time-series properties.
+The language is function-based, and promotes composition to extend behaviour.
+
+Here is a simple example:
+
+```python
+from hgraph import graph, run_graph, const
+from hgraph.nodes import debug_print
+
+@graph
+def main():
+    a = const(1)
+    c = a + 2
+    debug_print("a + 2", c)
+
+run_graph(main)
+```
+Results in:
+```
+[1970-01-01 00:00:00.000385][1970-01-01 00:00:00.000001] a + 2: 3
+```
+
+See [this](https://hgraph.readthedocs.io/en/latest/) for more information.
+
+## Development
+
+The project is currently configured to make use of [Poetry](https://python-poetry.org) for dependency management. 
+Take a look at the website to see how best to install the tool.
+
+Here are some useful commands:
+
+First, this will cause the virtual environment to be installed in the same folder as the project (in .venv folder)
+
+```bash
+poetry config virtualenvs.in-project true
+```
+
+Use this command to set the version of Python to make use of if you want a specific version of Python.
+
+```bash
+poetry env use 3.11
+```
+
+Then use the following command to install the project and its dependencies. Note that the ``--with docs`` installs
+the dependencies to build the documentation set which is not required otherwise, also the ``--all-extras`` is only
+required for the adaptors.
+
+```bash
+poetry install --with docs --all-extras
+```
+
+If you did not use the first command, you can find the location of the installation using:
+
+```bash
+poetry env info
+```
+
+PyCharm can make use of poetry to ``setup`` the project.
+
+### Run Tests
+
+```bash
+# No Coverage
+poetry run pytest
+```
+
+```bash
+# Generate Coverage Report
+poetry run pytest --cov=your_package_name --cov-report=xml
+```
+

hgraph-0.3.26/README.md

@@ -0,0 +1,74 @@
+# hgraph
+A functional reactive programming engine with a Python front-end.
+
+This provides a DSL and runtime to support the computation of results over time, featuring
+a graph based directed acyclic dependency graph and the concept of time-series properties.
+The language is function-based, and promotes composition to extend behaviour.
+
+Here is a simple example:
+
+```python
+from hgraph import graph, run_graph, const
+from hgraph.nodes import debug_print
+
+@graph
+def main():
+    a = const(1)
+    c = a + 2
+    debug_print("a + 2", c)
+
+run_graph(main)
+```
+Results in:
+```
+[1970-01-01 00:00:00.000385][1970-01-01 00:00:00.000001] a + 2: 3
+```
+
+See [this](https://hgraph.readthedocs.io/en/latest/) for more information.
+
+## Development
+
+The project is currently configured to make use of [Poetry](https://python-poetry.org) for dependency management. 
+Take a look at the website to see how best to install the tool.
+
+Here are some useful commands:
+
+First, this will cause the virtual environment to be installed in the same folder as the project (in .venv folder)
+
+```bash
+poetry config virtualenvs.in-project true
+```
+
+Use this command to set the version of Python to make use of if you want a specific version of Python.
+
+```bash
+poetry env use 3.11
+```
+
+Then use the following command to install the project and its dependencies. Note that the ``--with docs`` installs
+the dependencies to build the documentation set which is not required otherwise, also the ``--all-extras`` is only
+required for the adaptors.
+
+```bash
+poetry install --with docs --all-extras
+```
+
+If you did not use the first command, you can find the location of the installation using:
+
+```bash
+poetry env info
+```
+
+PyCharm can make use of poetry to ``setup`` the project.
+
+### Run Tests
+
+```bash
+# No Coverage
+poetry run pytest
+```
+
+```bash
+# Generate Coverage Report
+poetry run pytest --cov=your_package_name --cov-report=xml
+```

hgraph-0.3.26/pyproject.toml

@@ -0,0 +1,143 @@
+[tool.poetry]
+name = "hgraph"
+version = "0.3.26"
+description = """ \
+A functional reactive platform used to process time-series streams. \
+Provides support for backtest (simulation) and realtime time-series processing. \
+Using a forward propagation graph with a microtask scheduler for the runtime engine. \
+"""
+readme = "README.md"
+license = "MIT"
+authors = [
+    "Howard Henson <howard@henson.me.uk>",
+    "Alexander Balabin <balabin@me.com>",
+    "Simon Young <whepstead@gmail.com>",
+    "Tope Olukemi <tolukemi@gmail.com>"
+]
+keywords = [
+    "reactive", "graph", "fpg", "forward propogating graph",
+    "time series", "functional reactive programming",
+    "frp", "functional", "time-series"
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: Implementation :: CPython",
+]
+packages = [
+    { include = "hgraph", from = "src" },
+]
+
+[tool.poetry.dependencies]
+    python = ">=3.11"
+    frozendict = ">=2.3.10"
+    sortedcontainers = ">=2.4.0"
+    ordered-set = ">=4.1.0"
+    numpy = ">=1.23"
+    polars = ">=1.0"
+    sqlalchemy = "*"
+    duckdb = "*"
+    pyarrow = ">=16.1.0"
+    multimethod = "*"
+    tornado = { version = "*", optional = true }
+    perspective-python = {version = "<3.0.0", optional=true}
+    requests = { version = "*", optional = true }
+    sphinx = { version = ">=7.4", optional = true }
+    sphinx_rtd_theme = { version = ">=2.0.0", optional = true  }
+    sphinx-autodoc-typehints = { version = ">=2.3.0", optional = true }
+    sphinxcontrib-plantuml = { version = ">=0.30", optional = true }
+
+
+[tool.poetry.extras]
+web = [
+    "perspective-python",
+    "tornado",
+    "requests"
+]
+
+[tool.poetry.group.docs]
+optional = true
+
+[tool.poetry.group.docs.dependencies]
+    sphinx = "*"
+    sphinx_rtd_theme = "*"
+    sphinx-autodoc-typehints = "*"
+    sphinxcontrib-plantuml = "*"
+
+[tool.poetry.urls]
+Homepage = "https://github.com/hhenson/hgraph"
+Documentation = "https://github.com/hhenson/hgraph/blob/main/docs/index.md"
+Repository = "https://github.com/hhenson/hgraph.git"
+Issues = "https://github.com/hhenson/hgraph/blob/main/ISSUES.md"
+Changelog = "https://github.com/hhenson/hgraph/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.group.test.dependencies]
+pytest = "*"
+mypy = "*"
+pytest-cov = "*"
+coverage = "*"
+pytest-xdist = "*"
+
+
+# Configure pytest
+[tool.pytest.ini_options]
+minversion = "7.4.3"
+addopts = "-n auto -ra -q --dist=loadscope" # " --cov=hgraph --cov-report=term-missing --cov-report=xml"
+testpaths = [
+    "tests",
+]
+markers = [
+    "serial: mark test to run serially (not in parallel with xdist)",
+]
+
+# Configure coverage
+[tool.coverage.run]
+source_pkgs = ["hgraph",]
+branch = true
+parallel = true
+omit = [
+    "tests/*",
+    "examples/*",
+    "docs/*",
+    "src/hgraph/notebook/*",
+    "src/hgraph/debug/*"
+]
+
+[tool.coverage.paths]
+hg = ["src/hgraph",]
+tests = ["tests",]
+
+[tool.coverage.report]
+fail_under = 80
+exclude_lines = [
+    "no cov",
+    "if __name__ == .__main__.:",
+    "if TYPE_CHECKING:",
+]
+
+[tool.black]
+line-length = 120
+target-version = ['py311']
+unstable = true
+include = '\.pyi?$'
+# 'extend-exclude' excludes files or directories in addition to the defaults
+extend-exclude = '''
+# A regex preceded with ^/ will apply only to files and directories
+# in the root of the project.
+(
+  ^/foo.py    # exclude a file named foo.py in the root of the project
+  | .*_pb2.py  # exclude autogenerated Protocol Buffer files anywhere in the project
+)
+'''
+
+[tool.mypy]
+files = ["src",]
+
+[tool.poetry.scripts]
+build-docs = "sphinx.cmd.build:main"

hgraph-0.3.26/src/hgraph/__init__.py

@@ -0,0 +1,7 @@
+from hgraph._builder import *
+from hgraph._operators import *
+from hgraph._runtime import *
+from hgraph._types import *
+from hgraph._wiring import *
+from hgraph._impl import *
+

hgraph-0.3.26/src/hgraph/_builder/__init__.py

@@ -0,0 +1,7 @@
+from hgraph._builder._builder import *
+from hgraph._builder._graph_builder import *
+from hgraph._builder._input_builder import *
+from hgraph._builder._node_builder import *
+from hgraph._builder._output_builder import *
+from hgraph._builder._scalar_builder import *
+from hgraph._builder._ts_builder import *

hgraph-0.3.26/src/hgraph/_builder/_builder.py

@@ -0,0 +1,28 @@
+from abc import ABC, abstractmethod
+from typing import TypeVar, Generic
+
+ITEM = TypeVar("ITEM")
+
+__all__ = ("Builder",)
+
+
+class Builder(ABC, Generic[ITEM]):
+    """
+    The builder is responsible for constructing and initialising the item type it is responsible for.
+    It is also responsible for destroying and cleaning up the resources associated to the item.
+    These can be thought of as life-cycle methods.
+    """
+
+    @abstractmethod
+    def make_instance(self, **kwargs) -> ITEM:
+        """
+        Create a new instance of the item.
+        And additional attributes required for construction are passed in as kwargs.
+        Actual instance of the builder will fix these args for all instances of builder for the type.
+        """
+
+    @abstractmethod
+    def release_instance(self, item: ITEM):
+        """
+        Release the item and it's resources.
+        """

hgraph-0.3.26/src/hgraph/_builder/_graph_builder.py

@@ -0,0 +1,92 @@
+import typing
+from abc import abstractmethod
+from dataclasses import dataclass
+from typing import Iterable
+
+from hgraph._builder._builder import Builder
+
+if typing.TYPE_CHECKING:
+    from hgraph._runtime._graph import Graph
+    from hgraph._runtime._node import Node
+    from hgraph._builder._node_builder import NodeBuilder
+    from hgraph._types._scalar_types import SCALAR
+
+__all__ = ("Edge", "GraphBuilder", "GraphBuilderFactory")
+
+
+@dataclass(frozen=True)
+class Edge:
+    src_node: int
+    output_path: tuple["SCALAR", ...]
+    dst_node: int
+    input_path: tuple["SCALAR", ...]
+
+
+@dataclass(frozen=True)
+class GraphBuilder(Builder["Graph"]):
+    node_builders: tuple["NodeBuilder", ...]
+    edges: tuple[Edge, ...]
+
+    @abstractmethod
+    def make_instance(self, graph_id: tuple[int, ...], parent_node: "Node" = None, label: str = None) -> "Graph":
+        """
+        Construct an instance of a graph. The id provided is the id for the graph instance to be constructed.
+        """
+
+    @abstractmethod
+    def make_and_connect_nodes(self, graph_id: tuple[int, ...], first_node_ndx: int) -> Iterable["Node"]:
+        """
+        Make the nodes described in the node builders and connect the edges as described in the edges.
+        Return the iterable of newly constructed and wired nodes.
+        This can be used to feed into a new graph instance or to extend (or re-initialise) an existing graph.
+        """
+
+    @abstractmethod
+    def release_instance(self, item: "Graph"):
+        """
+        Release resources constructed during the build process, plus the graph.
+        """
+
+
+class GraphBuilderFactory:
+
+    _graph_builder_class: typing.Optional[typing.Type[GraphBuilder]] = None
+
+    @staticmethod
+    def default():
+        from hgraph._impl._builder._graph_builder import PythonGraphBuilder
+
+        return PythonGraphBuilder
+
+    @staticmethod
+    def is_declared() -> bool:
+        return GraphBuilderFactory._graph_builder_class is not None
+
+    @staticmethod
+    def declared() -> typing.Type[GraphBuilder]:
+        if GraphBuilderFactory._graph_builder_class is None:
+            raise RuntimeError("No graph builder type has been declared")
+        return GraphBuilderFactory._graph_builder_class
+
+    @staticmethod
+    def declare(cls: typing.Type[GraphBuilder]):
+        if GraphBuilderFactory._graph_builder_class is not None:
+            raise RuntimeError("A graph builder type has already been declared")
+        GraphBuilderFactory._graph_builder_class = cls
+
+    @staticmethod
+    def un_declare():
+        GraphBuilderFactory._graph_builder_class = None
+
+    @staticmethod
+    def make(node_builders: tuple["NodeBuilder", ...], edges: tuple[Edge, ...]) -> GraphBuilder:
+        """
+        Make a graph builder instance. If no graph builder class is declared, the default builder will be used.
+        :param node_builders: The node builders to use
+        :param edges: The edges to use for binding the node outputs to inputs.
+        :return: The GraphBuilder instance.
+        """
+        if GraphBuilderFactory.is_declared():
+            return GraphBuilderFactory.declared()(node_builders=node_builders, edges=edges)
+        else:
+            return GraphBuilderFactory.default()(node_builders=node_builders, edges=edges)

hgraph-0.3.26/src/hgraph/_builder/_input_builder.py

@@ -0,0 +1,19 @@
+import typing
+
+from hgraph._builder._builder import Builder
+
+if typing.TYPE_CHECKING:
+    from hgraph._types._time_series_types import TimeSeriesInput
+    from hgraph._runtime._node import Node
+
+__all__ = ("InputBuilder",)
+
+
+class InputBuilder(Builder["TimeSeriesInput"]):
+
+    def make_instance(self, owning_node: "Node" = None, owning_input: "TimeSeriesInput" = None) -> "TimeSeriesInput":
+        """One of owning_node or owning_input must be defined."""
+        raise NotImplementedError()
+
+    def release_instance(self, item: "TimeSeriesInput"):
+        raise NotImplementedError()

hgraph-0.3.26/src/hgraph/_builder/_node_builder.py

@@ -0,0 +1,39 @@
+from abc import abstractmethod
+from dataclasses import dataclass
+from typing import Optional, Any, Mapping, TypeVar
+
+from hgraph._builder._builder import Builder
+from hgraph._builder._input_builder import InputBuilder
+from hgraph._builder._output_builder import OutputBuilder
+from hgraph._runtime._node import NodeSignature, Node
+
+__all__ = ("NodeBuilder",)
+
+
+NODE = TypeVar("NODE", bound=Node)
+
+
+@dataclass(frozen=True)
+class NodeBuilder(Builder[NODE]):
+    signature: NodeSignature
+    scalars: Mapping[str, Any]
+    input_builder: Optional[InputBuilder] = None
+    output_builder: Optional[OutputBuilder] = None
+    error_builder: Optional[OutputBuilder] = None
+    recordable_state_builder: Optional[OutputBuilder] = None
+
+    @abstractmethod
+    def make_instance(self, owning_graph_id: tuple[int, ...], node_ndx) -> NODE:
+        """
+        Construct an instance of a node. The id provided is the id for the node instance to be constructed.
+        """
+
+    @abstractmethod
+    def release_instance(self, item: NODE):
+        """
+        Release any resources constructed during the build process, plus the node.
+        """
+
+
+# TODO: Need to ensure that each type of NodeBuilder is described in the abstract and a factory is provided
+#       to provide instances of the builder to allow us to support multiple engines.

hgraph-0.3.26/src/hgraph/_builder/_output_builder.py

@@ -0,0 +1,20 @@
+from typing import TYPE_CHECKING
+
+from hgraph._builder._builder import Builder
+
+if TYPE_CHECKING:
+    from hgraph._runtime._node import Node
+    from hgraph._types._time_series_types import TimeSeriesOutput
+
+
+__all__ = ("OutputBuilder",)
+
+
+class OutputBuilder(Builder["TimeSeriesOutput"]):
+
+    def make_instance(self, owning_node: "Node" = None, owning_output: "TimeSeriesOutput" = None) -> "TimeSeriesOutput":
+        """One of owning_node or owning_output must be defined."""
+        raise NotImplementedError()
+
+    def release_instance(self, item: "TimeSeriesOutput"):
+        raise NotImplementedError()

hgraph-0.3.26/src/hgraph/_builder/_scalar_builder.py

@@ -0,0 +1,19 @@
+from typing import TYPE_CHECKING
+
+from hgraph._builder._builder import Builder
+
+if TYPE_CHECKING:
+    from hgraph._types._scalar_value import ScalarValue
+
+
+__all__ = ("ScalarValueBuilder",)
+
+
+class ScalarValueBuilder(Builder["ScalarValue"]):
+
+    def make_instance(self) -> "ScalarValue":
+        """A scalar value is a basic type"""
+        raise NotImplementedError()
+
+    def release_instance(self, item: "ScalarValue"):
+        raise NotImplementedError()