Remote Python execution

This page documents the API for generation and management of remote Python function execution.

`session`

session(
    host="localhost",
    port=None,
    libraries=None,
    *,
    username="",
    password="",
    timeout=0.0,
    large_messages=True,
    tls=False,
    reconnection_attempts=-1
)

Initialise a session object, opening a connection to the specified remote q process. Users can specify the Python libraries to load into the remote process. Once the connection is successful, pykx will be loaded if it is not, then the requested libraries will be imported.

Parameters:

Name	Type	Description	Default
`host`	`Union[str, bytes]`	The host name running the remote process.	`'localhost'`
`port`	`int`	The port of the remote process.	`None`
`libraries`	`dict`	A dictionary mapping the desired name of the imported Python library to its library which is being imported	`None`
`username`	`Union[str, bytes]`	Username for q connection authorization.	`''`
`password`	`Union[str, bytes]`	Password for q connection authorization.	`''`
`timeout`	`float`	Number of seconds to set the timeout for blocking socket operations. Input 0 to set the socket to non-blocking.	`0.0`
`large_messages`	`bool`	Boolean flag to enable/disable messages >2GB in size.	`True`
`tls`	`bool`	Boolean flag to enable/disable TLS.	`False`
`reconnection_attempts`	`int`	The number of attempts to reconnect to the q server when there is a disconnect. Input a negative value to disable reconnect attempts. A value of 0 indicates no limit on reconnect attempts, with each attempt applying an exponential backoff on the time between successive attempts. Input a positive number to specify the maximum number of reconnect attempts. Hitting the maximum without a successful reconnect will throw an error.	`-1`

Examples:

Generate a session connecting to a process running locally

>>> import pykx as kx
>>> remote_session = kx.remote.session(port=5050)

Generate a session connecting to a remote q process, providing required Python libraries, a username and password

>>> import pykx as kx
>>> remote_session = kx.remote.session(
...     port = 5050,
...     username = 'user',
...     password = 'pass',
...     libraries = {'kx': 'pykx', 'np': 'numpy'})

libraries

libraries(libs=None)

Send a list of libraries to the remote process and load them into that process.

Parameters:

Name	Type	Description	Default
`libs`	`dict`	A dictionary mapping the desired name of the imported Python library to its library which is being imported	`None`

Returns:

Type	Description
`None`	`None` if successful.

>>> import pykx as kx
>>> remote_session = kx.remote.session(port=5050)
>>> remote_session.libraries({'np': 'numpy', 'pd': 'pandas', 'kx': 'pykx'})

close

close()

Close the connection.

Example:

>>> from pykx.remote import session
>>> remote_session = session(port=5050)
>>> remote_session.close()

function

function(remote_session, *args)

This decorator allows users to tag functions which will be executed on a remote server defined by a kx.remote.session instance.

Parameters:

Name	Type	Description	Default
`remote_session`	`session`	Valid `kx.remote.session` object used to interact with external	required
`*args`		Arguments that will be passed to the decorated function when it is invoked	`()`

Returns:

Type	Description
`None`	A PyKX converted type of the result returned from the execution of the decorated function
`None`	on the remote process

Examples:

Call a basic decorated function on a remote process

>>> import pykx as kx
>>> session = kx.remote.session(port=5050)
>>> @kx.remote.function(session)
... def func(x):
...    return x+1
>>> func(1)
pykx.LongAtom(pykx.q('2'))

Initialize a remote session object with a named library then decorate a function which uses that session to call functions from that library

>>> import pykx as kx
>>> session = kx.remote.session(port=5050, libraries={'np': 'numpy'})
>>> @kx.remote.function(session)
... def func(start, stop, count):
...     return numpy.linspace(start, stop, count)
>>> func(0, 10, 5)
pykx.FloatVector(pykx.q('0 2.5 5 7.5 10'))

Initialize a remote session object. Once created have that session import a new library.

>>> import pykx as kx
>>> session = kx.remote.session(port=5050)
>>> session.libraries({'kx': 'pykx'})
>>> @kx.remote.function(session)
... def func(start, stop):
...     return start + kx.q.til(stop)
>>> func(10, 5)
pykx.LongVector(pykx.q('10 11 12 13 14'))