:py:mod:`arkouda.client` ======================== .. py:module:: arkouda.client Module Contents --------------- Functions ~~~~~~~~~ .. autoapisummary:: arkouda.client.connect arkouda.client.disconnect arkouda.client.generate_history arkouda.client.get_config arkouda.client.get_mem_avail arkouda.client.get_mem_status arkouda.client.get_mem_used arkouda.client.get_server_commands arkouda.client.print_server_commands arkouda.client.ruok arkouda.client.shutdown .. py:function:: connect(server: str = 'localhost', port: int = 5555, timeout: int = 0, access_token: Optional[str] = None, connect_url: Optional[str] = None, access_channel: Optional[Channel] = None) -> None Connect to a running arkouda server. :param server: The hostname of the server (must be visible to the current machine). Defaults to `localhost`. :type server: str, optional :param port: The port of the server. Defaults to 5555. :type port: int, optional :param timeout: The timeout in seconds for client send and receive operations. Defaults to 0 seconds, whicn is interpreted as no timeout. :type timeout: int, optional :param access_token: The token used to connect to an existing socket to enable access to an Arkouda server where authentication is enabled. Defaults to None. :type access_token: str, optional :param connect_url: The complete url in the format of tcp://server:port?token= where the token is optional :type connect_url: str, optional :param access_channel: The desired Channel implementation that differs from the default ZmqChannel :type access_channel: Channel, optional :rtype: None :raises ConnectionError: Raised if there's an error in connecting to the Arkouda server :raises ValueError: Raised if there's an error in parsing the connect_url parameter :raises RuntimeError: Raised if there is a server-side error .. rubric:: Notes On success, prints the connected address, as seen by the server. If called with an existing connection, the socket will be re-initialized. .. py:function:: disconnect() -> None Disconnects the client from the Arkouda server :rtype: None :raises ConnectionError: Raised if there's an error disconnecting from the Arkouda server .. py:function:: generate_history(num_commands: Optional[int] = None, command_filter: Optional[str] = None) -> List[str] 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. :param num_commands: The number of commands from history to retrieve :type num_commands: int :param command_filter: String containing characters used to select a subset of commands. :type command_filter: str :returns: A list of commands from the Python shell, Jupyter notebook, or IPython notebook :rtype: List[str] .. rubric:: 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)'] .. py:function:: get_config() -> Mapping[str, Union[str, int, float]] 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 :rtype: Mapping[str, Union[str, int, float]] :raises RuntimeError: Raised if the client is not connected to a server .. py:function:: get_mem_avail(unit: str = 'b', as_percent: bool = False) -> int Compute the amount of memory available to be used. Parameters ---------- unit : str {'b', 'kb', 'mb', 'gb', 'tb', 'pb'} unit of return ('b' by default) as_percent : bool If True, return the percent (as an int) of the memory that's available to be used False by default Returns ------- int Indicates the amount of memory available to be used. Raises ------ 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 .. py:function:: get_mem_status() -> List[Mapping[str, Union[str, int, float]]] 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 .. py:function:: get_mem_used(unit: str = 'b', as_percent: bool = False) -> int Compute the amount of memory used by objects in the server's symbol table. Parameters ---------- unit : str {'b', 'kb', 'mb', 'gb', 'tb', 'pb'} unit of return ('b' by default) as_percent : bool If True, return the percent (as an int) of the available memory that's been used False by default Returns ------- int Indicates the amount of memory allocated to symbol table objects. Raises ------ 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 .. py:function:: get_server_commands() -> Mapping[str, str] Return a dictionary of available server commands and the functions they map to :returns: String to String mapping of available server commands to functions :rtype: dict :raises RuntimeError: Raised if there is a server-side error in retrieving and formatting the CommandMap :raises ValueError: Raised if there's an error in parsing the JSON-formatted server string .. py:function:: print_server_commands() Print the list of the available Server commands .. py:function:: ruok() -> str 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 :rtype: str .. py:function:: shutdown() -> None 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 :rtype: None :raises RuntimeError: Raised if the client is not connected to the Arkouda server or there is an error in disconnecting from the server