Skip to content

HaxallClient

open_haxall_client 

open_haxall_client(uri, username, password, ssl_context=None)

Context manager for opening and closing a session with a Haxall application. May help prevent accidentially leaving a session with the server open.

open_haxall_client can be directly imported as follows:

from phable import open_haxall_client

Example:

from phable import open_haxall_client

uri = "http://localhost:8080/api/demo"
with open_haxall_client(uri, "su", "password") as client:
    print(client.about())

Note: This context manager uses Project Haystack's close op, which was later introduced. Therefore the context manager may not work with earlier versions of Haxall.

Parameters:

Name Type Description Default
uri str

URI of endpoint such as "http://host/api/myProj/".

 required
username str

Username for the API user.

 required
password str

Password for the API user.

 required
ssl_context ssl.SSLContext | None

Optional SSL context. If not provided, a SSL context with default settings is created and used.

 None
Source code in phable/haxall_client.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
@contextmanager
def open_haxall_client(
    uri: str, username: str, password: str, ssl_context: SSLContext | None = None
) -> Generator[HaxallClient, None, None]:
    """Context manager for opening and closing a session with a
    [Haxall](https://haxall.io/) application. May help prevent accidentially leaving a
    session with the server open.

    `open_haxall_client` can be directly imported as follows:

    ```python
    from phable import open_haxall_client
    ```

    **Example:**

    ```python
    from phable import open_haxall_client

    uri = "http://localhost:8080/api/demo"
    with open_haxall_client(uri, "su", "password") as client:
        print(client.about())
    ```

    **Note:** This context manager uses Project Haystack's
    [close op](https://project-haystack.org/doc/docHaystack/Ops#close), which was
    later introduced. Therefore the context manager may not work with earlier versions
    of Haxall.

    Parameters:
        uri: URI of endpoint such as "http://host/api/myProj/".
        username: Username for the API user.
        password: Password for the API user.
        ssl_context:
            Optional SSL context. If not provided, a SSL context with default
            settings is created and used.
    """

    client = HaxallClient.open(uri, username, password, ssl_context=ssl_context)
    yield client
    client.close()

HaxallClient

Bases: phable.haystack_client.HaystackClient

A superset of HaystackClient with support for Haxall specific operations.

Learn more about Haxall here.

Source code in phable/haxall_client.py 
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
class HaxallClient(HaystackClient):
    """A superset of `HaystackClient` with support for Haxall specific operations.

    Learn more about Haxall [here](https://haxall.io/).
    """

    def commit_add(self, recs: dict[str, Any] | list[dict[str, Any]] | Grid) -> Grid:
        """Adds one or more new records to the database.

        As a general rule you should not have an `id` column in your commit grid.
        However if you wish to predefine the id of the records, you can specify an `id`
        column in the commit grid.

        Commit access requires the API user to have admin permission.

        **Errors**

        After the request `Grid` is successfully read by the server, the server
        may respond with a `Grid` that triggers one of the following errors to be
        raised:

        1. `ErrorGridError` if the operation fails
        2. `IncompleteDataError` if incomplete data is being returned

        **Additional info**

        See Haxall's Commit operation docs for more details
        [here](https://haxall.io/doc/lib-hx/op~commit).

        **Example:**

        ```python
        from phable import Marker, open_haxall_client

        # define these settings specific to your use case
        uri = "http://localhost:8080/api/demo"
        username = "<username>"
        password = "<password>"

        # define the rec to add
        rec = [{"dis": "TestRec", "testing": Marker(), "pytest": Marker()}]

        with open_haxall_client(uri, username, password) as client:
            # commit the rec and capture response
            rec_added_grid = client.commit_add(rec)
        ```

        Parameters:
            recs: Records to be added to the database.

        Returns:
            The full tag definitions for each of the newly added records.
        """
        meta = {"commit": "add"}
        if isinstance(recs, Grid):
            recs = recs.rows
        return self.call("commit", Grid.to_grid(recs, meta))

    def commit_update(self, recs: dict[str, Any] | list[dict[str, Any]] | Grid) -> Grid:
        """Updates one or more existing records within the database.

        Commit access requires the API user to have admin permission.

        **Errors**

        After the request `Grid` is successfully read by the server, the server
        may respond with a `Grid` that triggers one of the following errors to be
        raised:

        1. `ErrorGridError` if the operation fails
        2. `IncompleteDataError` if incomplete data is being returned

        **Additional info**

        See Haxall's Commit operation docs for more details
        [here](https://haxall.io/doc/lib-hx/op~commit).

        **Example:**

        ```python
        from phable import Ref, open_haxall_client

        # define these settings specific to your use case
        uri = "http://localhost:8080/api/demo"
        username = "<username>"
        password = "<password>"

        with open_haxall_client(uri, username, password) as client:
            # query entire rec we want to modify to get the mod tag
            rec = client.read_by_id(Ref("2e9ab42e-c9822ff9"))

            # define new tag to add to rec
            rec["foo"] = "new tag"

            # commit update to rec and capture response
            rec_modified_grid = client.commit_update(rec)
        ```

        Parameters:
            recs:
                Existing records within the database to be updated. Each record (or
                row) must at minimum have tags for the rec's existing `id` and `mod`
                columns (defined by the server) and the columns being updated (defined
                by the client).

        Returns:
            The latest full tag definitions for each of the updated records.
        """
        meta = {"commit": "update"}
        if isinstance(recs, Grid):
            recs = recs.rows
        return self.call("commit", Grid.to_grid(recs, meta))

    def commit_remove(self, recs: dict[str, Any] | list[dict[str, Any]] | Grid) -> Grid:
        """Removes one or more records from the database.

        Commit access requires the API user to have admin permission.

        **Errors**

        An `ErrorGridError` is raised if any of the recs do not exist on
        the server.

        Also, after the request `Grid` is successfully read by the server, the server
        may respond with a `Grid` that triggers one of the following errors to be
        raised:

        1. `ErrorGridError` if the operation fails
        2. `IncompleteDataError` if incomplete data is being returned

        **Additional info**

        See Haxall's Commit operation docs for more details
        [here](https://haxall.io/doc/lib-hx/op~commit).

        **Example:**

        ```python
        from phable import Ref, open_haxall_client

        # define these settings specific to your use case
        uri = "http://localhost:8080/api/demo"
        username = "<username>"
        password = "<password>"

        with open_haxall_client(uri, username, password) as client:
            # query entire rec you want to delete to get the mod tag
            rec = client.read_by_id(Ref("2e9ab42e-c9822ff9"))

            # delete the rec
            client.commit_remove(rec)
        ```

        Parameters:
            recs:
                Records to be removed from the database. Each record (or row) must at
                minimum define `id` and `mod` columns.

        Returns:
            An empty `Grid`.
        """
        meta = {"commit": "remove"}
        if isinstance(recs, Grid):
            recs = recs.rows
        return self.call("commit", Grid.to_grid(recs, meta))

    def eval(self, expr: str) -> Grid:
        """Evaluates an Axon string expression.

        **Errors**

        After the request `Grid` is successfully read by the server, the server
        may respond with a `Grid` that triggers one of the following errors to be
        raised:

        1. `ErrorGridError` if the operation fails
        2. `IncompleteDataError` if incomplete data is being returned

        **Additional info**

        See Haxall's Eval operation docs for more details
        [here](https://haxall.io/doc/lib-hx/op~eval).

        **Example:**

        ```python
        from phable import open_haxall_client

        # define these settings specific to your use case
        uri = "http://localhost:8080/api/demo"
        username = "<username>"
        password = "<password>"

        # define an axon expression to evaluate on the server
        axon_expr = "read(power and point and equipRef->siteMeter).hisRead(lastMonth)"

        with open_haxall_client(uri, username, password) as client:
            his_grid = client.eval(axon_expr)

        his_df_meta, his_df = his_grid.to_polars_all()
        ```

        Parameters:
            expr: Axon string expression.

        Returns:
            `Grid` with the server's response.
        """

        return self.call("eval", Grid.to_grid({"expr": expr}))

commit_add 

commit_add(recs)

Adds one or more new records to the database.

As a general rule you should not have an id column in your commit grid. However if you wish to predefine the id of the records, you can specify an id column in the commit grid.

Commit access requires the API user to have admin permission.

Errors

After the request Grid is successfully read by the server, the server may respond with a Grid that triggers one of the following errors to be raised:

  1. ErrorGridError if the operation fails
  2. IncompleteDataError if incomplete data is being returned

Additional info

See Haxall's Commit operation docs for more details here.

Example:

from phable import Marker, open_haxall_client

# define these settings specific to your use case
uri = "http://localhost:8080/api/demo"
username = "<username>"
password = "<password>"

# define the rec to add
rec = [{"dis": "TestRec", "testing": Marker(), "pytest": Marker()}]

with open_haxall_client(uri, username, password) as client:
    # commit the rec and capture response
    rec_added_grid = client.commit_add(rec)

Parameters:

Name Type Description Default
recs dict[str, typing.Any] | list[dict[str, typing.Any]] | phable.kinds.Grid

Records to be added to the database.

 required

Returns:

Type Description
phable.kinds.Grid

The full tag definitions for each of the newly added records.
Source code in phable/haxall_client.py 
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
def commit_add(self, recs: dict[str, Any] | list[dict[str, Any]] | Grid) -> Grid:
    """Adds one or more new records to the database.

    As a general rule you should not have an `id` column in your commit grid.
    However if you wish to predefine the id of the records, you can specify an `id`
    column in the commit grid.

    Commit access requires the API user to have admin permission.

    **Errors**

    After the request `Grid` is successfully read by the server, the server
    may respond with a `Grid` that triggers one of the following errors to be
    raised:

    1. `ErrorGridError` if the operation fails
    2. `IncompleteDataError` if incomplete data is being returned

    **Additional info**

    See Haxall's Commit operation docs for more details
    [here](https://haxall.io/doc/lib-hx/op~commit).

    **Example:**

    ```python
    from phable import Marker, open_haxall_client

    # define these settings specific to your use case
    uri = "http://localhost:8080/api/demo"
    username = "<username>"
    password = "<password>"

    # define the rec to add
    rec = [{"dis": "TestRec", "testing": Marker(), "pytest": Marker()}]

    with open_haxall_client(uri, username, password) as client:
        # commit the rec and capture response
        rec_added_grid = client.commit_add(rec)
    ```

    Parameters:
        recs: Records to be added to the database.

    Returns:
        The full tag definitions for each of the newly added records.
    """
    meta = {"commit": "add"}
    if isinstance(recs, Grid):
        recs = recs.rows
    return self.call("commit", Grid.to_grid(recs, meta))

commit_remove 

commit_remove(recs)

Removes one or more records from the database.

Commit access requires the API user to have admin permission.

Errors

An ErrorGridError is raised if any of the recs do not exist on the server.

Also, after the request Grid is successfully read by the server, the server may respond with a Grid that triggers one of the following errors to be raised:

  1. ErrorGridError if the operation fails
  2. IncompleteDataError if incomplete data is being returned

Additional info

See Haxall's Commit operation docs for more details here.

Example:

from phable import Ref, open_haxall_client

# define these settings specific to your use case
uri = "http://localhost:8080/api/demo"
username = "<username>"
password = "<password>"

with open_haxall_client(uri, username, password) as client:
    # query entire rec you want to delete to get the mod tag
    rec = client.read_by_id(Ref("2e9ab42e-c9822ff9"))

    # delete the rec
    client.commit_remove(rec)

Parameters:

Name Type Description Default
recs dict[str, typing.Any] | list[dict[str, typing.Any]] | phable.kinds.Grid

Records to be removed from the database. Each record (or row) must at minimum define id and mod columns.

 required

Returns:

Type Description
phable.kinds.Grid

An empty Grid.
Source code in phable/haxall_client.py 
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
def commit_remove(self, recs: dict[str, Any] | list[dict[str, Any]] | Grid) -> Grid:
    """Removes one or more records from the database.

    Commit access requires the API user to have admin permission.

    **Errors**

    An `ErrorGridError` is raised if any of the recs do not exist on
    the server.

    Also, after the request `Grid` is successfully read by the server, the server
    may respond with a `Grid` that triggers one of the following errors to be
    raised:

    1. `ErrorGridError` if the operation fails
    2. `IncompleteDataError` if incomplete data is being returned

    **Additional info**

    See Haxall's Commit operation docs for more details
    [here](https://haxall.io/doc/lib-hx/op~commit).

    **Example:**

    ```python
    from phable import Ref, open_haxall_client

    # define these settings specific to your use case
    uri = "http://localhost:8080/api/demo"
    username = "<username>"
    password = "<password>"

    with open_haxall_client(uri, username, password) as client:
        # query entire rec you want to delete to get the mod tag
        rec = client.read_by_id(Ref("2e9ab42e-c9822ff9"))

        # delete the rec
        client.commit_remove(rec)
    ```

    Parameters:
        recs:
            Records to be removed from the database. Each record (or row) must at
            minimum define `id` and `mod` columns.

    Returns:
        An empty `Grid`.
    """
    meta = {"commit": "remove"}
    if isinstance(recs, Grid):
        recs = recs.rows
    return self.call("commit", Grid.to_grid(recs, meta))

commit_update 

commit_update(recs)

Updates one or more existing records within the database.

Commit access requires the API user to have admin permission.

Errors

After the request Grid is successfully read by the server, the server may respond with a Grid that triggers one of the following errors to be raised:

  1. ErrorGridError if the operation fails
  2. IncompleteDataError if incomplete data is being returned

Additional info

See Haxall's Commit operation docs for more details here.

Example:

from phable import Ref, open_haxall_client

# define these settings specific to your use case
uri = "http://localhost:8080/api/demo"
username = "<username>"
password = "<password>"

with open_haxall_client(uri, username, password) as client:
    # query entire rec we want to modify to get the mod tag
    rec = client.read_by_id(Ref("2e9ab42e-c9822ff9"))

    # define new tag to add to rec
    rec["foo"] = "new tag"

    # commit update to rec and capture response
    rec_modified_grid = client.commit_update(rec)

Parameters:

Name Type Description Default
recs dict[str, typing.Any] | list[dict[str, typing.Any]] | phable.kinds.Grid

Existing records within the database to be updated. Each record (or row) must at minimum have tags for the rec's existing id and mod columns (defined by the server) and the columns being updated (defined by the client).

 required

Returns:

Type Description
phable.kinds.Grid

The latest full tag definitions for each of the updated records.
Source code in phable/haxall_client.py 
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
def commit_update(self, recs: dict[str, Any] | list[dict[str, Any]] | Grid) -> Grid:
    """Updates one or more existing records within the database.

    Commit access requires the API user to have admin permission.

    **Errors**

    After the request `Grid` is successfully read by the server, the server
    may respond with a `Grid` that triggers one of the following errors to be
    raised:

    1. `ErrorGridError` if the operation fails
    2. `IncompleteDataError` if incomplete data is being returned

    **Additional info**

    See Haxall's Commit operation docs for more details
    [here](https://haxall.io/doc/lib-hx/op~commit).

    **Example:**

    ```python
    from phable import Ref, open_haxall_client

    # define these settings specific to your use case
    uri = "http://localhost:8080/api/demo"
    username = "<username>"
    password = "<password>"

    with open_haxall_client(uri, username, password) as client:
        # query entire rec we want to modify to get the mod tag
        rec = client.read_by_id(Ref("2e9ab42e-c9822ff9"))

        # define new tag to add to rec
        rec["foo"] = "new tag"

        # commit update to rec and capture response
        rec_modified_grid = client.commit_update(rec)
    ```

    Parameters:
        recs:
            Existing records within the database to be updated. Each record (or
            row) must at minimum have tags for the rec's existing `id` and `mod`
            columns (defined by the server) and the columns being updated (defined
            by the client).

    Returns:
        The latest full tag definitions for each of the updated records.
    """
    meta = {"commit": "update"}
    if isinstance(recs, Grid):
        recs = recs.rows
    return self.call("commit", Grid.to_grid(recs, meta))

eval 

eval(expr)

Evaluates an Axon string expression.

Errors

After the request Grid is successfully read by the server, the server may respond with a Grid that triggers one of the following errors to be raised:

  1. ErrorGridError if the operation fails
  2. IncompleteDataError if incomplete data is being returned

Additional info

See Haxall's Eval operation docs for more details here.

Example:

from phable import open_haxall_client

# define these settings specific to your use case
uri = "http://localhost:8080/api/demo"
username = "<username>"
password = "<password>"

# define an axon expression to evaluate on the server
axon_expr = "read(power and point and equipRef->siteMeter).hisRead(lastMonth)"

with open_haxall_client(uri, username, password) as client:
    his_grid = client.eval(axon_expr)

his_df_meta, his_df = his_grid.to_polars_all()

Parameters:

Name Type Description Default
expr str

Axon string expression.

 required

Returns:

Type Description
phable.kinds.Grid

Grid with the server's response.
Source code in phable/haxall_client.py 
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
def eval(self, expr: str) -> Grid:
    """Evaluates an Axon string expression.

    **Errors**

    After the request `Grid` is successfully read by the server, the server
    may respond with a `Grid` that triggers one of the following errors to be
    raised:

    1. `ErrorGridError` if the operation fails
    2. `IncompleteDataError` if incomplete data is being returned

    **Additional info**

    See Haxall's Eval operation docs for more details
    [here](https://haxall.io/doc/lib-hx/op~eval).

    **Example:**

    ```python
    from phable import open_haxall_client

    # define these settings specific to your use case
    uri = "http://localhost:8080/api/demo"
    username = "<username>"
    password = "<password>"

    # define an axon expression to evaluate on the server
    axon_expr = "read(power and point and equipRef->siteMeter).hisRead(lastMonth)"

    with open_haxall_client(uri, username, password) as client:
        his_grid = client.eval(axon_expr)

    his_df_meta, his_df = his_grid.to_polars_all()
    ```

    Parameters:
        expr: Axon string expression.

    Returns:
        `Grid` with the server's response.
    """

    return self.call("eval", Grid.to_grid({"expr": expr}))