# Deephaven Python Client
Deephaven Python Client is a Python package created by Deephaven Data Labs. It is a client API that allows Python applications to remotely access Deephaven data servers.
## Source Directory
### From the deephaven-core repository root
(clone from https://github.com/deephaven/deephaven-core)
## Change to the py/client directory inside the deephaven-core repository
``` shell
$ cd py/client
```
## Dev environment setup
``` shell
$ pip3 install -r requirements-dev.txt
```
## Build
``` shell
$ DEEPHAVEN_VERSION=$(../../gradlew :printVersion -q) python3 setup.py bdist_wheel
```
## Run tests
``` shell
$ python3 -m unittest discover tests
```
## Run examples
``` shell
$ python3 -m examples.demo_table_ops
$ python3 -m examples.demo_query
$ python3 -m examples.demo_run_script
$ python3 -m examples.demo_merge_tables
$ python3 -m examples.demo_asof_join
```
## Install
Note the actual name of the `.whl` file may be different depending on system details.
``` shell
$ pip3 install dist/pydeephaven-<x.y.z>-py3-none-any.whl
```
## Quick start
```python
>>> from pydeephaven import Session
>>> session = Session() # assuming Deephaven Community Edition is running locally with the default configuration
>>> table1 = session.time_table(period=1000000000).update(formulas=["Col1 = i % 2"])
>>> df = table1.to_arrow().to_pandas()
>>> print(df)
Timestamp Col1
0 1629681525690000000 0
1 1629681525700000000 1
2 1629681525710000000 0
3 1629681525720000000 1
4 1629681525730000000 0
... ... ...
1498 1629681540670000000 0
1499 1629681540680000000 1
1500 1629681540690000000 0
1501 1629681540700000000 1
1502 1629681540710000000 0
>>> session.close()
```
## Initialize
The `Session` class is your connection to Deephaven. This is what allows your Python code to interact with a Deephaven server.
```
from pydeephaven import Session
session = Session()
```
## Ticking table
The `Session` class has many methods that create tables. This example creates a ticking time table and binds it to Deephaven.
```
from pydeephaven import Session
session = Session()
table = session.time_table(period=1000000000).update(formulas=["Col1 = i % 2"])
session.bind_table(name="my_table", table=table)
```
This is the general flow of how the Python client interacts with Deephaven. You create a table (new or existing), execute some operations on it, and then bind it to Deephaven. Binding the table gives it a named reference on the Deephaven server, so that it can be used from the Web API or other Sessions.
## Execute a query on a table
`table.update()` can be used to execute an update on a table. This updates a table with a query string.
```
from pydeephaven import Session
session = Session()
# Create a table with no columns and 3 rows
table = session.empty_table(3)
# Create derived table having a new column MyColumn populated with the row index "i"
table = table.update(["MyColumn = i"])
# Update the Deephaven Web Console with this new table
session.bind_table(name="my_table", table=table)
```
## Sort a table
`table.sort()` can be used to sort a table. This example sorts a table by one of its columns.
```
from pydeephaven import Session
session = Session()
table = session.empty_table(5)
table = table.update(["SortColumn = 4-i"])
table = table.sort(["SortColumn"])
session.bind_table(name="my_table", table=table)
```
## Filter a table
`table.where()` can be used to filter a table. This example filters a table using a filter string.
```
from pydeephaven import Session
session = Session()
table = session.empty_table(5)
table = table.update(["Values = i"])
table = table.where(["Values % 2 == 1"])
session.bind_table(name="my_table", table=table)
```
## Query objects
Query objects are a way to create and manage a sequence of Deephaven query operations as a single unit. Query objects have the potential to perform better than the corresponding individual queries, because the query object can be transmitted to the server in one request rather than several, and because the system can perform certain optimizations when it is able to see the whole sequence of queries at once. They are similar in spirit to prepared statements in SQL.
The general flow of using a query object is to construct a query with a table, call the table operations (sort, filter, update, etc.) on the query object, and then assign your table to the return value of `query.exec()`.
Any operation that can be executed on a table can also be executed on a query object. This example shows two operations that compute the same result, with the first one using the table updates and the second one using a query object.
```
from pydeephaven import Session
session = Session()
table = session.empty_table(10)
# executed immediately
table1= table.update(["MyColumn = i"]).sort(["MyColumn"]).where(["MyColumn > 5"]);
# create Query Object (execution is deferred until the "exec" statement)
query_obj = session.query(table).update(["MyColumn = i"]).sort(["MyColumn"]).where(["MyColumn > 5"]);
# Transmit the QueryObject to the server and execute it
table2 = query_obj.exec();
session.bind_table(name="my_table1", table=table1)
session.bind_table(name="my_table2", table=table2)
```
## Join two tables
`table.join()` is one of many operations that can join two tables, as shown below.
```
from pydeephaven import Session
session = Session()
table1 = session.empty_table(5)
table1 = table1.update(["Values1 = i", "Group = i"])
table2 = session.empty_table(5)
table2 = table2.update(["Values2 = i + 10", "Group = i"])
table = table1.join(table2, on=["Group"])
session.bind_table(name="my_table", table=table)
```
## Perform aggregations on a table
Aggregations can be applied on tables in the Python client. This example creates an aggregation that averages
the `Count` column of a table, and aggregates it by the `Group` column.
```
from pydeephaven import Session, agg
session = Session()
table = session.empty_table(10)
table = table.update(["Count = i", "Group = i % 2"])
my_agg = agg.avg(["Count"])
table = table.agg_by(aggs=[my_agg], by=["Group"])
session.bind_table(name="my_table", table=table)
```
## Convert a PyArrow table to a Deephaven table
Deephaven natively supports [PyArrow tables](https://arrow.apache.org/docs/python/index.html). This example converts between a PyArrow table and a Deephaven table.
```
import pyarrow as pa
from pydeephaven import Session
session = Session()
arr = pa.array([4,5,6], type=pa.int32())
pa_table = pa.Table.from_arrays([arr], names=["Integers"])
table = session.import_table(pa_table)
session.bind_table(name="my_table", table=table)
#Convert the Deephaven table back to a pyarrow table
pa_table = table.to_arrow()
```
## Execute a script server side
`session.run_script()` can be used to execute code on the Deephaven server. This is useful when operations cannot be done on the client-side, such as creating a dynamic table writer. This example shows how to execute a script server-side and retrieve a table generated from the script.
```
from pydeephaven import Session
session = Session()
script = """
from deephaven import empty_table
table = empty_table(8).update(["Index = i"])
"""
session.run_script(script)
table = session.open_table("table")
print(table.to_arrow())
```
## Error handling
The `DHError` is thrown whenever the client package encounters an error. This example shows how to catch a `DHError`.
```
from pydeephaven import Session, DHError
try:
session = Session(host="invalid_host")
except DHError as e:
print("Deephaven error when connecting to session")
print(e)
except Exception as e:
print("Unknown error")
print(e)
```
## Related documentation
* https://deephaven.io/
* https://arrow.apache.org/docs/python/index.html
## API Reference
[start here] https://deephaven.io/core/client-api/python/
Raw data
{
"_id": null,
"home_page": "https://deephaven.io/",
"name": "pydeephaven",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Deephaven Data Labs",
"author_email": "python@deephaven.io",
"download_url": null,
"platform": null,
"description": "\n# Deephaven Python Client \n\nDeephaven Python Client is a Python package created by Deephaven Data Labs. It is a client API that allows Python applications to remotely access Deephaven data servers.\n\n## Source Directory\n\n### From the deephaven-core repository root\n(clone from https://github.com/deephaven/deephaven-core)\n\n## Change to the py/client directory inside the deephaven-core repository\n``` shell\n$ cd py/client\n```\n\n## Dev environment setup\n``` shell\n$ pip3 install -r requirements-dev.txt\n```\n\n## Build\n``` shell\n$ DEEPHAVEN_VERSION=$(../../gradlew :printVersion -q) python3 setup.py bdist_wheel\n```\n\n## Run tests\n``` shell\n$ python3 -m unittest discover tests\n\n```\n## Run examples\n``` shell\n$ python3 -m examples.demo_table_ops\n$ python3 -m examples.demo_query\n$ python3 -m examples.demo_run_script\n$ python3 -m examples.demo_merge_tables\n$ python3 -m examples.demo_asof_join\n\n```\n## Install\n\nNote the actual name of the `.whl` file may be different depending on system details.\n\n``` shell\n$ pip3 install dist/pydeephaven-<x.y.z>-py3-none-any.whl\n```\n## Quick start\n\n```python \n >>> from pydeephaven import Session\n >>> session = Session() # assuming Deephaven Community Edition is running locally with the default configuration\n >>> table1 = session.time_table(period=1000000000).update(formulas=[\"Col1 = i % 2\"])\n >>> df = table1.to_arrow().to_pandas()\n >>> print(df)\n Timestamp Col1\n 0 1629681525690000000 0\n 1 1629681525700000000 1\n 2 1629681525710000000 0\n 3 1629681525720000000 1\n 4 1629681525730000000 0\n ... ... ...\n 1498 1629681540670000000 0\n 1499 1629681540680000000 1\n 1500 1629681540690000000 0\n 1501 1629681540700000000 1\n 1502 1629681540710000000 0\n\n >>> session.close()\n\n```\n\n## Initialize\n\nThe `Session` class is your connection to Deephaven. This is what allows your Python code to interact with a Deephaven server.\n\n```\nfrom pydeephaven import Session\n\nsession = Session()\n```\n\n## Ticking table\n\nThe `Session` class has many methods that create tables. This example creates a ticking time table and binds it to Deephaven.\n\n```\nfrom pydeephaven import Session\n\nsession = Session()\n\ntable = session.time_table(period=1000000000).update(formulas=[\"Col1 = i % 2\"])\nsession.bind_table(name=\"my_table\", table=table)\n```\n\nThis is the general flow of how the Python client interacts with Deephaven. You create a table (new or existing), execute some operations on it, and then bind it to Deephaven. Binding the table gives it a named reference on the Deephaven server, so that it can be used from the Web API or other Sessions.\n\n## Execute a query on a table\n\n`table.update()` can be used to execute an update on a table. This updates a table with a query string.\n\n```\nfrom pydeephaven import Session\n\nsession = Session()\n\n# Create a table with no columns and 3 rows\ntable = session.empty_table(3)\n# Create derived table having a new column MyColumn populated with the row index \"i\"\ntable = table.update([\"MyColumn = i\"])\n# Update the Deephaven Web Console with this new table\nsession.bind_table(name=\"my_table\", table=table)\n```\n\n## Sort a table\n\n`table.sort()` can be used to sort a table. This example sorts a table by one of its columns.\n\n```\nfrom pydeephaven import Session\n\nsession = Session()\n\ntable = session.empty_table(5)\ntable = table.update([\"SortColumn = 4-i\"])\n\ntable = table.sort([\"SortColumn\"])\nsession.bind_table(name=\"my_table\", table=table)\n```\n\n## Filter a table\n\n`table.where()` can be used to filter a table. This example filters a table using a filter string.\n\n```\nfrom pydeephaven import Session\n\nsession = Session()\n\ntable = session.empty_table(5)\ntable = table.update([\"Values = i\"])\n\ntable = table.where([\"Values % 2 == 1\"])\nsession.bind_table(name=\"my_table\", table=table)\n```\n\n## Query objects\n\nQuery objects are a way to create and manage a sequence of Deephaven query operations as a single unit. Query objects have the potential to perform better than the corresponding individual queries, because the query object can be transmitted to the server in one request rather than several, and because the system can perform certain optimizations when it is able to see the whole sequence of queries at once. They are similar in spirit to prepared statements in SQL.\n\nThe general flow of using a query object is to construct a query with a table, call the table operations (sort, filter, update, etc.) on the query object, and then assign your table to the return value of `query.exec()`.\n\nAny operation that can be executed on a table can also be executed on a query object. This example shows two operations that compute the same result, with the first one using the table updates and the second one using a query object.\n\n```\nfrom pydeephaven import Session\n\nsession = Session()\n\ntable = session.empty_table(10)\n\n# executed immediately\ntable1= table.update([\"MyColumn = i\"]).sort([\"MyColumn\"]).where([\"MyColumn > 5\"]);\n\n# create Query Object (execution is deferred until the \"exec\" statement)\nquery_obj = session.query(table).update([\"MyColumn = i\"]).sort([\"MyColumn\"]).where([\"MyColumn > 5\"]);\n# Transmit the QueryObject to the server and execute it\ntable2 = query_obj.exec();\n\nsession.bind_table(name=\"my_table1\", table=table1)\nsession.bind_table(name=\"my_table2\", table=table2)\n```\n\n## Join two tables\n\n`table.join()` is one of many operations that can join two tables, as shown below.\n\n```\nfrom pydeephaven import Session\n\nsession = Session()\n\ntable1 = session.empty_table(5)\ntable1 = table1.update([\"Values1 = i\", \"Group = i\"])\ntable2 = session.empty_table(5)\ntable2 = table2.update([\"Values2 = i + 10\", \"Group = i\"])\n\ntable = table1.join(table2, on=[\"Group\"])\nsession.bind_table(name=\"my_table\", table=table)\n```\n\n## Perform aggregations on a table\n\nAggregations can be applied on tables in the Python client. This example creates an aggregation that averages \nthe `Count` column of a table, and aggregates it by the `Group` column.\n\n```\nfrom pydeephaven import Session, agg\n\nsession = Session()\n\ntable = session.empty_table(10)\ntable = table.update([\"Count = i\", \"Group = i % 2\"])\n\nmy_agg = agg.avg([\"Count\"])\n\ntable = table.agg_by(aggs=[my_agg], by=[\"Group\"])\nsession.bind_table(name=\"my_table\", table=table)\n```\n\n## Convert a PyArrow table to a Deephaven table\n\nDeephaven natively supports [PyArrow tables](https://arrow.apache.org/docs/python/index.html). This example converts between a PyArrow table and a Deephaven table.\n\n```\nimport pyarrow as pa\nfrom pydeephaven import Session\n\nsession = Session()\n\narr = pa.array([4,5,6], type=pa.int32())\npa_table = pa.Table.from_arrays([arr], names=[\"Integers\"])\n\ntable = session.import_table(pa_table)\nsession.bind_table(name=\"my_table\", table=table)\n\n#Convert the Deephaven table back to a pyarrow table\npa_table = table.to_arrow()\n```\n\n## Execute a script server side\n\n`session.run_script()` can be used to execute code on the Deephaven server. This is useful when operations cannot be done on the client-side, such as creating a dynamic table writer. This example shows how to execute a script server-side and retrieve a table generated from the script.\n\n```\nfrom pydeephaven import Session\n\nsession = Session()\n\nscript = \"\"\"\nfrom deephaven import empty_table\n\ntable = empty_table(8).update([\"Index = i\"])\n\"\"\"\n\nsession.run_script(script)\n\ntable = session.open_table(\"table\")\nprint(table.to_arrow())\n```\n\n## Error handling\n\nThe `DHError` is thrown whenever the client package encounters an error. This example shows how to catch a `DHError`.\n\n```\nfrom pydeephaven import Session, DHError\n\ntry:\n session = Session(host=\"invalid_host\")\nexcept DHError as e:\n print(\"Deephaven error when connecting to session\")\n print(e)\nexcept Exception as e:\n print(\"Unknown error\")\n print(e)\n```\n\n## Related documentation\n* https://deephaven.io/\n* https://arrow.apache.org/docs/python/index.html\n\n## API Reference\n[start here] https://deephaven.io/core/client-api/python/\n",
"bugtrack_url": null,
"license": "Deephaven Community License Agreement Version 1.0",
"summary": "The Deephaven Python Client",
"version": "0.36.1",
"project_urls": {
"Homepage": "https://deephaven.io/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ef61ff01bd53d1063695a7174892b3769e7bac654c4274282d12203d9381ed64",
"md5": "b9967a8b3719da5b37d3f53c958a40f9",
"sha256": "0c1ca7ad40278ff414e7e107b1f101efc5816e3c7ae5fc110159fffcbcabf82e"
},
"downloads": -1,
"filename": "pydeephaven-0.36.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b9967a8b3719da5b37d3f53c958a40f9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 107275,
"upload_time": "2024-08-23T20:42:01",
"upload_time_iso_8601": "2024-08-23T20:42:01.195538Z",
"url": "https://files.pythonhosted.org/packages/ef/61/ff01bd53d1063695a7174892b3769e7bac654c4274282d12203d9381ed64/pydeephaven-0.36.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-23 20:42:01",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pydeephaven"
}
JSON