Metadata-Version: 2.2
Name: hgraph
Version: 0.5.17
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.
Keywords: reactive,graph,fpg,forward propogating graph,time series,functional reactive programming,frp,functional,time-series
Author-Email: Howard Henson <howard@henson.me.uk>, Alexander Balabin <balabin@me.com>, Simon Young <whepstead@gmail.com>, Tope Olukemi <tolukemi@gmail.com>
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Project-URL: Homepage, https://github.com/hhenson/hgraph
Project-URL: Documentation, https://github.com/hhenson/hgraph/blob/main/docs/index.md
Project-URL: Repository, https://github.com/hhenson/hgraph.git
Project-URL: Issues, https://github.com/hhenson/hgraph/blob/main/ISSUES.md
Project-URL: Changelog, https://github.com/hhenson/hgraph/blob/main/CHANGELOG.md
Requires-Python: <3.15,>=3.12
Requires-Dist: frozendict>=2.3.10
Requires-Dist: sortedcontainers>=2.4.0
Requires-Dist: ordered-set>=4.1.0
Requires-Dist: numpy>=1.23
Requires-Dist: polars>=1.0
Requires-Dist: sqlalchemy
Requires-Dist: duckdb
Requires-Dist: pyarrow>=16.1.0
Requires-Dist: multimethod
Requires-Dist: psutil
Requires-Dist: typing-extensions
Requires-Dist: pycurl
Requires-Dist: black>=25.1.0
Requires-Dist: pytz
Provides-Extra: web
Requires-Dist: perspective-python<4.0.0; extra == "web"
Requires-Dist: tornado; extra == "web"
Requires-Dist: requests; extra == "web"
Requires-Dist: pandas; extra == "web"
Requires-Dist: pycurl; extra == "web"
Provides-Extra: messaging
Requires-Dist: kafka-python>=2.1.5; extra == "messaging"
Provides-Extra: notebook
Requires-Dist: matplotlib; extra == "notebook"
Provides-Extra: docs
Requires-Dist: sphinx>=7.4; extra == "docs"
Requires-Dist: sphinx_rtd_theme>=2.0.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=2.3.0; extra == "docs"
Requires-Dist: sphinxcontrib-plantuml>=0.30; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex; extra == "docs"
Requires-Dist: pybtex-apa-style>=1.3; extra == "docs"
Requires-Dist: setuptools; extra == "docs"
Requires-Dist: myst-parser>=2.0.0; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid>=0.9.0; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: mypy; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: coverage; extra == "test"
Requires-Dist: pytest-xdist; extra == "test"
Requires-Dist: black; extra == "test"
Provides-Extra: dev
Requires-Dist: nanobind==2.12.0; extra == "dev"
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, evaluate_graph, GraphConfiguration, const, debug_print

@graph
def main():
    a = const(1)
    c = a + 2
    debug_print("a + 2", c)

evaluate_graph(main, GraphConfiguration())
```
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 [uv](https://github.com/astral-sh/uv) for dependency management. 
Take a look at the website to see how best to install the tool.

Here are some useful commands:

First, create a virtual environment in the project directory:

```bash
uv venv
```

Then use the following command to install the project and its dependencies:

```bash
# Install the project with all dependencies
uv pip install -e .

# Install with optional dependencies
uv pip install -e ".[docs,web,notebook]"

# Install with all optional dependencies
uv pip install -e ".[docs,web,notebook,test]"
```

PyCharm can make use of the virtual environment created by uv to ``setup`` the project.

### Run Tests

```bash
# No Coverage
python -m pytest
```

```bash
# Generate Coverage Report
python -m pytest --cov=hgraph --cov-report=xml
```


## Indexing with Context7 MCP

This repository includes a baseline configuration for Context7 MCP to improve code search and retrieval quality.

- See docs/context7_indexing.md for guidance.
- The root-level context7.yaml config sets sensible include/exclude rules, priorities, and summarization hints.


## Packaging, CI, and Releases

This project uses scikit-build-core and cibuildwheel to build and publish cross-platform wheels, with uv as the package/venv manager.

- Local build (PEP 517):
  ```bash
  # Build a wheel into dist/
  uv build -v
  # Optionally build sdist too
  uv build -v --sdist
  ```

- Optional Conan (developer builds only):
  ```bash
  # Conan is not required for packaging but may be used in local builds
  uv tool install conan
  # Example of enabling Conan provider for a local build
  CMAKE_ARGS="-DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=conan_provider.cmake" uv build -v
  ```

- macOS notes:
  - Wheels target Apple Silicon (arm64) and require a macOS deployment target high enough for libc++ floating-point `to_chars` used by `std::format`.
  - The build system enforces `MACOSX_DEPLOYMENT_TARGET=15.0` (arm64) during Release Wheels and sets a default in CMake if unset.
  - You can override locally via:
    ```bash
    CMAKE_ARGS="-DCMAKE_OSX_DEPLOYMENT_TARGET=15.0 -DCMAKE_OSX_ARCHITECTURES=arm64" uv build -v
    ```

- Windows notes:
  - Build uses MSVC (Visual Studio 2022, x64). No MinGW.
  - If stack traces via backward-cpp are enabled, Windows links `Dbghelp` and `Imagehlp` automatically.

- Linux notes:
  - Release wheels are built inside manylinux containers; optional `backward-cpp` integrations are disabled there for portability.

### CI summary
- `.github/workflows/ci.yml` builds wheels on Linux/macOS/Windows for smoke validation, runs tests on Linux only (fast path), and repairs Linux wheels with auditwheel.
- `.github/workflows/release-wheels.yml` builds publish-grade wheels with cibuildwheel (Linux manylinux, macOS arm64, Windows AMD64), builds an sdist, validates with twine, and publishes to PyPI via Trusted Publishing.

### Releasing (tag-driven)
Releases are automated via GitHub Actions with PyPI Trusted Publishing.

Prerequisites:
- Enable Trusted Publishing for this GitHub repository in the PyPI project settings (Project → Settings → Trusted Publishers). No API token is needed once OIDC is configured.
- Ensure `pyproject.toml` `[project].version` matches the tag you plan to push (e.g., `0.4.112`).

Steps:
```bash
# Update version in pyproject.toml to match your release
# Then tag and push the tag to trigger the release workflow

git tag -a v_0.4.112 -m "release 0.4.112"
git push origin v_0.4.112
```

The workflow will:
- Build wheels for Linux (manylinux), macOS (arm64, macOS 15.0 target), and Windows (AMD64, MSVC)
- Build an sdist
- Validate with `twine check`
- Publish all distributions to PyPI (skips existing files)

Artifacts are uploaded for inspection as part of the workflow run.

### CLion configuration tips
- Use the project venv Python for nanobind discovery:
  - CMake option: `-DPython_EXECUTABLE=${PROJECT_ROOT}/.venv/bin/python`
- If you need Conan, use the preamble to ensure Python/nanobind are discovered first, then the Conan provider:
  - CMake option: `-DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=${PROJECT_ROOT}/conan_preamble.cmake;${PROJECT_ROOT}/conan_provider.cmake`
- Select the `_hgraph` target to build the extension.

### Troubleshooting
- Nanobind not found / Python ordering in CMake:
  - Pass `-DPython_EXECUTABLE=...` (or `-DPython3_EXECUTABLE=...`) and, if using Conan, use the `conan_preamble.cmake` before `conan_provider.cmake`.
- I also find it helpful to perform an uv sync with at least --all-groups
  before setting up the cmake.
