arkouda.core.client =================== .. py:module:: arkouda.core.client .. autoapi-nested-parse:: Client interface for connecting to and communicating with the Arkouda server. The `arkouda.core.client` module provides the core logic for managing a client-server session in Arkouda. It includes methods to connect, disconnect, send commands, check system status, and retrieve configuration details from the server. The client communicates with the server via ZMQ by default and handles both string and binary message formats. Key Responsibilities -------------------- - Establish and manage server connections via different `Channel` types (e.g., ZMQ) - Format and send commands using Arkouda’s request-response protocol - Retrieve memory and configuration metrics from the server - Provide a health check (`ruok`) and shutdown mechanism - Maintain client-side logging, verbosity, and session parameters - (Optional) Provide async-style request *sending* and an `async_connect()` helper Classes ------- Channel Abstract base class for communication between the client and the server. ZmqChannel Default implementation of `Channel` using ZeroMQ request-reply pattern. ClientMode, ShellMode, RequestMode, ChannelType Enum classes defining modes of client interaction, shell type detection, and channel selection. Functions --------- connect(...) Establish a connection to an Arkouda server. disconnect() Cleanly disconnect from the server and reset session state. shutdown() Shut down the server, delete its symbol table, and disconnect the client. get_config() Return server runtime configuration and environment settings. get_mem_used(), get_mem_avail(), get_mem_status() Retrieve memory usage and availability statistics from the server. get_server_commands() Get a mapping of available server commands and their functions. print_server_commands() Print a list of all supported server-side commands. generate_history(...) Retrieve interactive shell or notebook command history. ruok() Send a health check to the server ("ruok") and receive status. .. rubric:: Notes - This module is foundational to all Arkouda workflows. - The `generic_msg()` function handles message transmission. - Clients must call `connect()` (or `async_connect()`) before performing any operations. - The async additions are fully backward-compatible and purely opt‑in via env var. .. rubric:: Examples >>> import arkouda as ak >>> ak.connect() # doctest: +SKIP >>> ak.get_config() # doctest: +SKIP {'serverHostname': 'localhost', 'numLocales': 4, ...} >>> ak.disconnect() # doctest: +SKIP Functions --------- .. autoapisummary:: arkouda.core.client.connect arkouda.core.client.disconnect arkouda.core.client.generate_history arkouda.core.client.get_config arkouda.core.client.get_max_array_rank arkouda.core.client.get_mem_avail arkouda.core.client.get_mem_status arkouda.core.client.get_mem_used arkouda.core.client.get_registration_config arkouda.core.client.get_server_commands arkouda.core.client.print_server_commands arkouda.core.client.ruok arkouda.core.client.shutdown Module Contents --------------- .. 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: Hostname visible to the current machine. :type server: str, default "localhost" :param port: Server port. :type port: int, default 5555 :param timeout: Timeout in seconds for send/receive. If positive, also activates heartbeat monitoring (ZMQ). :type timeout: int, default 0 :param access_token: Access token for authenticated servers. :type access_token: str, optional :param connect_url: Complete URL in the form ``tcp://server:port?token=``. :type connect_url: str, optional :param access_channel: A pre-constructed channel instance to use instead of the default. :type access_channel: Channel, optional :raises ConnectionError: If there is an error connecting to the server. :raises ValueError: If `connect_url` cannot be parsed. :raises RuntimeError: If a server-side error occurs during connect. .. 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 Disconnect the client from the Arkouda server. :raises ConnectionError: If there is an error during disconnect. .. py:function:: generate_history(num_commands: Optional[int] = None, command_filter: Optional[str] = None) -> List[str] Generate a list of commands executed in the shell/notebook. :param num_commands: Number of commands to retrieve from history. :type num_commands: int, optional :param command_filter: Filter string to select a subset of commands. :type command_filter: str, optional :returns: List of command strings. :rtype: list[str] .. rubric:: Examples >>> import arkouda as ak >>> ak.get_config() # doctest: +SKIP {'arkoudaVersion': 'v2025.01.13+165.g23ccdfd6c', 'chplVersion': '2.4.0', ... 'pythonVersion': '3.13', 'ZMQVersion': '4.3.5', 'HDF5Version': '1.14.4', ... 'serverHostname': 'pop-os', 'ServerPort': 5555, 'numLocales': 1, ... 'numPUs': 8, 'maxTaskPar': 8, 'physicalMemory': 67258408960, ... 'distributionType': 'domain(1,int(64),one)', ... 'LocaleConfigs': [{'id': 0, 'name': 'pop-os', 'numPUs': 8, ... 'maxTaskPar': 8, 'physicalMemory': 67258408960}], 'authenticate': False, ... 'logLevel': 'INFO', 'logChannel': 'FILE', 'regexMaxCaptures': 20, ... 'byteorder': 'little', 'autoShutdown': False, 'serverInfoNoSplash': False, ... 'maxArrayDims': 1, 'ARROW_VERSION': '19.0.0'} >>> ak.ones(10000, dtype=int) array([1 1 1 ... 1 1 1]) >>> nums = ak.randint(0,500,10000, seed=1) >>> ak.argsort(nums) array([1984 2186 3574 ... 9298 9600 9651]) >>> ak.generate_history(num_commands=5, command_filter='ak.') # doctest: +SKIP ['ak.connect()', 'ak.get_config()', 'ak.ones(10000, dtype=int)', '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: Mapping containing selected server configuration and environment settings. Common keys include: - ``serverHostname`` : str Hostname of the Arkouda server. - ``serverPort`` : int Port number the server is listening on. - ``numLocales`` : int Number of Chapel locales (nodes) in the server deployment. - ``numPUs`` : int Number of processor units (hardware threads) per locale. - ``maxTaskPar`` : int Maximum number of tasks per locale. - ``physicalMemory`` : int Total physical memory on each locale (bytes). :rtype: Mapping[str, Union[str, int, float]] :raises RuntimeError: If the client is not connected to a server. .. py:function:: get_max_array_rank() -> int Get the maximum pdarray rank the server was compiled to support. :returns: Maximum pdarray rank. :rtype: int .. py:function:: get_mem_avail(unit: str = 'b', as_percent: bool = False) -> int Compute the amount of memory available to be used. :param unit: Unit of the return value (default 'b'). :type unit: {'b','kb','mb','gb','tb','pb'} :param as_percent: If True, return the percentage of memory that is available. :type as_percent: bool, default False :returns: Amount of memory available (scaled per `unit`) or percentage if `as_percent`. :rtype: int :raises RuntimeError: Raised if there is a server-side error in getting memory used. :raises ValueError: Raised if the returned value is not an int-formatted string. .. py:function:: get_mem_status() -> List[Mapping[str, Union[str, int, float]]] Retrieve the memory status for each locale. :returns: Each mapping contains: - ``total_mem`` : int Total physical memory on the locale host (bytes). - ``avail_mem`` : int Current available memory on the locale host (bytes). - ``arkouda_mem_alloc`` : int Memory allocated to the Arkouda Chapel process on the locale host (bytes). - ``pct_avail_mem`` : float Percentage of physical memory currently available on the locale host. - ``locale_id`` : int Locale identifier (between 0 and numLocales - 1). - ``locale_hostname`` : str Hostname of the locale. :rtype: list of mapping :raises RuntimeError: If there is a server-side error in retrieving memory status. :raises ValueError: If the returned data is not valid JSON. .. 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. :param unit: Unit of the return value (default 'b'). :type unit: {'b','kb','mb','gb','tb','pb'} :param as_percent: If True, return the percentage of available memory that is used. :type as_percent: bool, default False :returns: Amount of memory used (scaled per `unit`) or percentage if `as_percent`. :rtype: int :raises RuntimeError: Raised if there is a server-side error in getting memory used. :raises ValueError: Raised if the returned value is not an int-formatted string. .. py:function:: get_registration_config() Get the registration settings the server was built with. :returns: Snapshot of `registration-config.json` taken at server build time. :rtype: dict :raises RuntimeError: Raised if the client is not connected to a server .. py:function:: get_server_commands() -> Mapping[str, str] Return a dictionary of available server commands and their functions. :returns: Mapping of command name → function (stringified). :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 available server commands. .. py:function:: ruok() -> str Quick health check that does not require error handling. :returns: "imok" if the server is operating normally, otherwise an error string. :rtype: str .. py:function:: shutdown() -> None Send a shutdown message and disconnect. Performs: 1. Delete all objects in the server SymTable. 2. Shut down the server. 3. Disconnect the client. :raises RuntimeError: Raised if the client is not connected to the Arkouda server or there is an error in disconnecting from the server.