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 
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
54
55
56
57
58
59
60
@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 
 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
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
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}))

    def file_get(self, remote_file_uri: str) -> BufferedReader:
        """Fetches content from a file on the server and returns a buffered binary stream.

        The data in the HTTP response is not logged since a buffered reader can only be read once.

        Phable users should manually close the returned stream as shown in the example below.

        **Note:**  This method is experimental and subject to change.

        **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>"

        with open_haxall_client(uri, username, password) as client:
            stream = client.file_get("/proj/demo/io/data.txt")

            # write data from the stream to a local file called data.txt
            with open("data.txt", "wb") as file:
                file.write(stream.read())

            # don't forget to close the stream when finished!
            stream.close()
        ```

        Parameters:
            remote_file_uri:
                URI of the remote file that has content being fetched.

        Returns:
            A buffered binary stream that is readable.
        """
        remote_file_url = self.uri + "/file" + remote_file_uri

        mimetype = mimetypes.guess_type(remote_file_url)[0]
        if mimetype is None:
            raise ValueError

        headers = {
            "Authorization": f"BEARER authToken={self._auth_token}",
            "Accept": mimetype,
        }

        res = request(
            url=remote_file_url,
            headers=headers,
            context=self._context,
        )

        return BufferedReader(res)

    def file_post(self, stream: BufferedReader, remote_file_uri: str) -> dict[str, Any]:
        """Uploads a file to a project using the HTTP POST method.

        If a file with the same name already exists on the server, then the uploaded file will be renamed.

        **Note:**  This method is experimental and subject to change.

        **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>"

        with open_haxall_client(uri, username, password) as client:
            # use stream from local file data.txt to upload file on server
            with open("data.txt", "rb") as file:
                res_data = client.file_post(file, "/proj/demo/io/data.txt")
        ```

        Raises:
            ValueError:
                Server did not return a Grid with the URI that file content was written to.

        Parameters:
            stream:
                A buffered binary stream used for writing content to the remote file.
            remote_file_uri:
                URI that file content is intended to be written to.

        Returns:
            A dictionary of data containing the URI the file content was written to.
        """
        return self._upload_file(stream, remote_file_uri, "POST")

    def file_put(self, stream: BufferedReader, remote_file_uri: str) -> dict[str, Any]:
        """Uploads a file to a project using the HTTP PUT method.

        If a file with the same name already exists on the server, then the existing file will be overwritten with the uploaded file.

        **Note:**  This method is experimental and subject to change.

        **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>"

        with open_haxall_client(uri, username, password) as client:
            # use stream from local file data.txt to upload file on server
            with open("data.txt", "rb") as file:
                res_data = client.file_put(file, "/proj/demo/io/data.txt")
        ```

        Raises:
            ValueError:
                Server did not return a Grid with the URI that file content was written to.

        Parameters:
            stream:
                A buffered binary stream used for writing content to the remote file.
            remote_file_uri:
                URI of the remote file that content will be written to.

        Returns:
            A dictionary of data containing the URI the file content was written to.
        """
        return self._upload_file(stream, remote_file_uri, "PUT")

    def _upload_file(
        self, stream: BufferedReader, remote_file_uri: str, http_method: str
    ) -> dict[str, Any]:
        mimetype = mimetypes.guess_type(remote_file_uri)[0]
        if mimetype is None:
            raise ValueError

        data = stream.read()
        stream.close()

        headers = {
            "Content-Type": mimetype,
            "Authorization": f"BEARER authToken={self._auth_token}",
            "Accept": "application/json",
        }

        res = ph_request(
            self.uri + "/file" + remote_file_uri,
            headers,
            data,
            method=http_method,
            context=self._context,
        ).to_grid()

        try:
            res_data = res.rows[0]
        except IndexError:
            raise ValueError

        if isinstance(res_data.get("uri"), Uri) is False:
            raise ValueError

        return res_data

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 
 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
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 
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
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 
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
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 
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
266
267
268
269
270
271
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}))

file_get 

file_get(remote_file_uri)

Fetches content from a file on the server and returns a buffered binary stream.

The data in the HTTP response is not logged since a buffered reader can only be read once.

Phable users should manually close the returned stream as shown in the example below.

Note: This method is experimental and subject to change.

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>"

with open_haxall_client(uri, username, password) as client:
    stream = client.file_get("/proj/demo/io/data.txt")

    # write data from the stream to a local file called data.txt
    with open("data.txt", "wb") as file:
        file.write(stream.read())

    # don't forget to close the stream when finished!
    stream.close()

Parameters:

Name Type Description Default
remote_file_uri str

URI of the remote file that has content being fetched.

 required

Returns:

Type Description
io.BufferedReader

A buffered binary stream that is readable.
Source code in phable/haxall_client.py 
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
def file_get(self, remote_file_uri: str) -> BufferedReader:
    """Fetches content from a file on the server and returns a buffered binary stream.

    The data in the HTTP response is not logged since a buffered reader can only be read once.

    Phable users should manually close the returned stream as shown in the example below.

    **Note:**  This method is experimental and subject to change.

    **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>"

    with open_haxall_client(uri, username, password) as client:
        stream = client.file_get("/proj/demo/io/data.txt")

        # write data from the stream to a local file called data.txt
        with open("data.txt", "wb") as file:
            file.write(stream.read())

        # don't forget to close the stream when finished!
        stream.close()
    ```

    Parameters:
        remote_file_uri:
            URI of the remote file that has content being fetched.

    Returns:
        A buffered binary stream that is readable.
    """
    remote_file_url = self.uri + "/file" + remote_file_uri

    mimetype = mimetypes.guess_type(remote_file_url)[0]
    if mimetype is None:
        raise ValueError

    headers = {
        "Authorization": f"BEARER authToken={self._auth_token}",
        "Accept": mimetype,
    }

    res = request(
        url=remote_file_url,
        headers=headers,
        context=self._context,
    )

    return BufferedReader(res)

file_post 

file_post(stream, remote_file_uri)

Uploads a file to a project using the HTTP POST method.

If a file with the same name already exists on the server, then the uploaded file will be renamed.

Note: This method is experimental and subject to change.

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>"

with open_haxall_client(uri, username, password) as client:
    # use stream from local file data.txt to upload file on server
    with open("data.txt", "rb") as file:
        res_data = client.file_post(file, "/proj/demo/io/data.txt")

Raises:

Type Description
ValueError

Server did not return a Grid with the URI that file content was written to.

Parameters:

Name Type Description Default
stream io.BufferedReader

A buffered binary stream used for writing content to the remote file.

 required
remote_file_uri str

URI that file content is intended to be written to.

 required

Returns:

Type Description
dict[str, typing.Any]

A dictionary of data containing the URI the file content was written to.
Source code in phable/haxall_client.py 
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
def file_post(self, stream: BufferedReader, remote_file_uri: str) -> dict[str, Any]:
    """Uploads a file to a project using the HTTP POST method.

    If a file with the same name already exists on the server, then the uploaded file will be renamed.

    **Note:**  This method is experimental and subject to change.

    **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>"

    with open_haxall_client(uri, username, password) as client:
        # use stream from local file data.txt to upload file on server
        with open("data.txt", "rb") as file:
            res_data = client.file_post(file, "/proj/demo/io/data.txt")
    ```

    Raises:
        ValueError:
            Server did not return a Grid with the URI that file content was written to.

    Parameters:
        stream:
            A buffered binary stream used for writing content to the remote file.
        remote_file_uri:
            URI that file content is intended to be written to.

    Returns:
        A dictionary of data containing the URI the file content was written to.
    """
    return self._upload_file(stream, remote_file_uri, "POST")

file_put 

file_put(stream, remote_file_uri)

Uploads a file to a project using the HTTP PUT method.

If a file with the same name already exists on the server, then the existing file will be overwritten with the uploaded file.

Note: This method is experimental and subject to change.

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>"

with open_haxall_client(uri, username, password) as client:
    # use stream from local file data.txt to upload file on server
    with open("data.txt", "rb") as file:
        res_data = client.file_put(file, "/proj/demo/io/data.txt")

Raises:

Type Description
ValueError

Server did not return a Grid with the URI that file content was written to.

Parameters:

Name Type Description Default
stream io.BufferedReader

A buffered binary stream used for writing content to the remote file.

 required
remote_file_uri str

URI of the remote file that content will be written to.

 required

Returns:

Type Description
dict[str, typing.Any]

A dictionary of data containing the URI the file content was written to.
Source code in phable/haxall_client.py 
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
def file_put(self, stream: BufferedReader, remote_file_uri: str) -> dict[str, Any]:
    """Uploads a file to a project using the HTTP PUT method.

    If a file with the same name already exists on the server, then the existing file will be overwritten with the uploaded file.

    **Note:**  This method is experimental and subject to change.

    **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>"

    with open_haxall_client(uri, username, password) as client:
        # use stream from local file data.txt to upload file on server
        with open("data.txt", "rb") as file:
            res_data = client.file_put(file, "/proj/demo/io/data.txt")
    ```

    Raises:
        ValueError:
            Server did not return a Grid with the URI that file content was written to.

    Parameters:
        stream:
            A buffered binary stream used for writing content to the remote file.
        remote_file_uri:
            URI of the remote file that content will be written to.

    Returns:
        A dictionary of data containing the URI the file content was written to.
    """
    return self._upload_file(stream, remote_file_uri, "PUT")