arkouda.client#

Module Contents#

Functions#

connect(→ None)

Connect to a running arkouda server.

disconnect(→ None)

Disconnects the client from the Arkouda server

generate_history(→ List[str])

Generates list of commands executed within the the Python shell, Jupyter notebook,

get_config(→ Mapping[str, Union[str, int, float]])

Get runtime information about the server.

get_mem_avail(→ int)

Compute the amount of memory available to be used.

get_mem_status(→ List[Mapping[str, Union[str, int, ...)

Retrieves the memory status for each locale

get_mem_used(→ int)

Compute the amount of memory used by objects in the server's symbol table.

get_server_commands(→ Mapping[str, str])

Return a dictionary of available server commands and the functions they map to

print_server_commands()

Print the list of the available Server commands

ruok(→ str)

Simply sends an "ruok" message to the server and, if the return message is

shutdown(→ None)

Sends a shutdown message to the Arkouda server that does the

arkouda.client.connect(server: str = 'localhost', port: int = 5555, timeout: int = 0, access_token: str | None = None, connect_url: str | None = None, access_channel: Channel | None = None) None[source]#

Connect to a running arkouda server.

Parameters:
  • server (str, optional) – The hostname of the server (must be visible to the current machine). Defaults to localhost.

  • port (int, optional) – The port of the server. Defaults to 5555.

  • timeout (int, optional) – The timeout in seconds for client send and receive operations. Defaults to 0 seconds, whicn is interpreted as no timeout.

  • access_token (str, optional) – The token used to connect to an existing socket to enable access to an Arkouda server where authentication is enabled. Defaults to None.

  • connect_url (str, optional) – The complete url in the format of tcp://server:port?token=<token_value> where the token is optional

  • access_channel (Channel, optional) – The desired Channel implementation that differs from the default ZmqChannel

Return type:

None

Raises:
  • ConnectionError – Raised if there’s an error in connecting to the Arkouda server

  • ValueError – Raised if there’s an error in parsing the connect_url parameter

  • RuntimeError – Raised if there is a server-side error

Notes

On success, prints the connected address, as seen by the server. If called with an existing connection, the socket will be re-initialized.

arkouda.client.disconnect() None[source]#

Disconnects the client from the Arkouda server

Return type:

None

Raises:

ConnectionError – Raised if there’s an error disconnecting from the Arkouda server

arkouda.client.generate_history(num_commands: int | None = None, command_filter: str | None = None) List[str][source]#

Generates list of commands executed within the the Python shell, Jupyter notebook, or IPython notebook, with an optional cmd_filter and number of commands to return.

Parameters:
  • num_commands (int) – The number of commands from history to retrieve

  • command_filter (str) – String containing characters used to select a subset of commands.

Returns:

A list of commands from the Python shell, Jupyter notebook, or IPython notebook

Return type:

List[str]

Examples

>>> ak.connect()
connected to arkouda server tcp://*:5555
>>> ak.get_config()
>>> ak.ones(10000)
array([1 1 1 ... 1 1 1])
>>> nums = ak.randint(0,500,10000)
>>> ak.argsort(nums)
array([105 457 647 ... 9362 9602 9683])
>>> ak.generate_history(num_commands=5, command_filter='ak.')
['ak.connect()', 'ak.get_config()', 'ak.ones(10000)', 'nums = ak.randint(0,500,10000)',
'ak.argsort(nums)']
arkouda.client.get_config() Mapping[str, str | int | float][source]#

Get runtime information about the server.

Returns:

serverHostname serverPort numLocales numPUs (number of processor units per locale) maxTaskPar (maximum number of tasks per locale) physicalMemory

Return type:

Mapping[str, Union[str, int, float]]

Raises:

RuntimeError – Raised if the client is not connected to a server

arkouda.client.get_mem_avail(unit: str = 'b', as_percent: bool = False) int[source]#

Compute the amount of memory available to be used.

Parameters
unitstr {‘b’, ‘kb’, ‘mb’, ‘gb’, ‘tb’, ‘pb’}

unit of return (‘b’ by default)

as_percentbool

If True, return the percent (as an int) of the memory that’s available to be used False by default

int

Indicates the amount of memory available to be used.

RuntimeError

Raised if there is a server-side error in getting memory available

ValueError

Raised if the returned value is not an int-formatted string

arkouda.client.get_mem_status() List[Mapping[str, str | int | float]][source]#

Retrieves the memory status for each locale

Returns
List[Mapping[str, Union[str, int, float]]]

total_mem: total physical memory on locale host avail_mem: current available memory on locale host arkouda_mem_alloc: memory allocated to Arkouda chapel process on locale host pct_avail_mem: percentage of physical memory currently available on locale host locale_id: locale id which is between 0 and numLocales-1 locale_hostname: host name of locale host

Raises
RuntimeError

Raised if there is a server-side error in getting per-locale memory status information

arkouda.client.get_mem_used(unit: str = 'b', as_percent: bool = False) int[source]#

Compute the amount of memory used by objects in the server’s symbol table.

Parameters
unitstr {‘b’, ‘kb’, ‘mb’, ‘gb’, ‘tb’, ‘pb’}

unit of return (‘b’ by default)

as_percentbool

If True, return the percent (as an int) of the available memory that’s been used False by default

int

Indicates the amount of memory allocated to symbol table objects.

RuntimeError

Raised if there is a server-side error in getting memory used

ValueError

Raised if the returned value is not an int-formatted string

arkouda.client.get_server_commands() Mapping[str, str][source]#

Return a dictionary of available server commands and the functions they map to

Returns:

String to String mapping of available server commands to functions

Return type:

dict

Raises:
  • RuntimeError – Raised if there is a server-side error in retrieving and formatting the CommandMap

  • ValueError – Raised if there’s an error in parsing the JSON-formatted server string

arkouda.client.print_server_commands()[source]#

Print the list of the available Server commands

arkouda.client.ruok() str[source]#

Simply sends an “ruok” message to the server and, if the return message is “imok”, this means the arkouda_server is up and operating normally. A return message of “imnotok” indicates an error occurred or the connection timed out.

This method is basically a way to do a quick healthcheck in a way that does not require error handling.

Returns:

A string indicating if the server is operating normally (imok), if there’s an error server-side, or if ruok did not return a response (imnotok) in both of the latter cases

Return type:

str

arkouda.client.shutdown() None[source]#

Sends a shutdown message to the Arkouda server that does the following:

  1. Delete all objects in the SymTable

  2. Shuts down the Arkouda server

  3. Disconnects the client from the stopped Arkouda Server

Return type:

None

Raises:

RuntimeError – Raised if the client is not connected to the Arkouda server or there is an error in disconnecting from the server