IPC

pykx.ipc

PyKX q IPC interface.

The IPC communication module provided here works differently than may be expected for users familiar with the KX IPC interfaces provided for Java and C#. Unlike these interfaces it does not directly convert the encoded data received over the q IPC protocol to an analogous type in Python, but rather stores the object within q memory space as a pykx.K object for defered conversion.

This has major benefits with regards to the flexibility of the interface. In particular, the pykx.K conversion methods (i.e. py, np, pd, and pa), use the same logic as they do when converting pykx.K objects that were created by an embedded q instance.

The IPC interface works when running with or without a q license. Refer to the modes of operation documentation for more details.

Currently functions pulled in over IPC execute locally within PyKX.

Warning

There are plans to change this behaviour so that when q is an instance of QConnection each of these examples would run on the q server.

# Executes locally
q.save('t')
q('save')('t')
# Executes on the server
q('save', 't')

QConnection

QConnection(
    host="localhost",
    port=None,
    *,
    username="",
    password="",
    timeout=0.0,
    large_messages=True,
    tls=False,
    unix=False,
    sync=None,
    wait=True
)

Bases: Q

Interface with a q process using the q IPC protocol.

Instances of this class represent an open connection to a q process, which can be sent messages synchronously or asynchronously by calling it as a function.

Parameters:

Name	Type	Description	Default
host	Union[str, bytes]	The host name to which a connection is to be established.	'localhost'
port	int	The port to which a connection is to be established.	None
username	Union[str, bytes]	Username for q connection authorization.	''
password	Union[str, bytes]	Password for q connection authorization.	''
timeout	float	Timeout for blocking socket operations in seconds. If set to 0, the socket will be non-blocking.	0.0
large_messages	bool	Whether support for messages >2GB should be enabled.	True
tls	bool	Whether TLS should be used.	False
unix	bool	Whether a Unix domain socket should be used instead of TCP. If set to True, the host parameter is ignored.	False
sync	Optional[bool]	This parameter is deprecated - use wait instead.	None
wait	bool	Whether the q server should send a response to the query (which this connection will wait to receive). Can be overridden on a per-call basis. If True, Python will wait for the q server to execute the query, and respond with the results. If False, the q server will respond immediately to every query with generic null (::), then execute them at some point in the future.	True

Examples:

Connect to a q process on localhost with a required username and password.

pykx.QConnection('localhost', 5001, 'username', 'password')

Connect to a q process at IP address 127.0.0.0, on port 5000 with a timeout of 2 seconds and TLS enabled.

pykx.QConnection('127.0.0.1', 5001, timeout=2.0, tls=True)

Connect to a q process via a Unix domain socket on port 5001

pykx.QConnection(port=5001, unix=True)

__abstractmethods__

__abstractmethods__ = frozenset()

frozenset() -> empty frozenset object frozenset(iterable) -> frozenset object

Build an immutable unordered collection of unique elements.

__module__

__module__ = 'pykx.ipc'

str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.str() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'.

__weakref__

__weakref__ = <attribute '__weakref__' of 'Q' objects>

list of weak references to the object (if defined)

_ipc_errors

_ipc_errors = {
    0: "Authentication error",
    -1: "Connection error",
    -2: "Timeout error",
    -3: "OpenSSL initialization failed",
}

dict() -> new empty dictionary dict(mapping) -> new dictionary initialized from a mapping object's (key, value) pairs dict(iterable) -> new dictionary initialized as if via: d = {} for k, v in iterable: d[k] = v dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

reserved_words

reserved_words = {
    "enlist",
    "sqrt",
    "dev",
    "var",
    "sum",
    "select",
    "avg",
    "xexp",
    "exit",
    "exec",
    "in",
    "atan",
    "max",
    "log",
    "tan",
    "asin",
    "abs",
    "insert",
    "prd",
    "while",
    "cor",
    "cov",
    "exp",
    "binr",
    "wsum",
    "ss",
    "like",
    "cos",
    "min",
    "wavg",
    "hopen",
    "setenv",
    "acos",
    "last",
    "do",
    "getenv",
    "bin",
    "sin",
    "if",
    "delete",
    "within",
    "update",
    "div",
}

set() -> new empty set object set(iterable) -> new set object

Build an unordered collection of unique elements.

__call__ method descriptor

__call__(query, args, wait=None, sync=None)

The args parameter is actually *args.

The auto-generated documentation for this function suggests that args is a single positional argument, when in reality it is *args. Multiple positional arguments may follow the query; see the examples below. We plan to resolve this documentation issue in the future.

Evaluate a query on the connected q process over IPC.

Parameters:

Name	Type	Description	Default
query	Union[str, bytes]	A q expression to be evaluated.	required
args	Any	Arguments to the q query. Each argument will be converted into a pykx.K object. Up to 8 arguments can be provided, as that is the maximum supported by q.	required
sync	Optional[bool]	This parameter is deprecated - use wait instead.	None
wait	Optional[bool]	Whether the q server should execute the query before responding. If True, Python will wait for the q server to execute the query, and respond with the results. If False, the q server will respond immediately to the query with generic null (::), then execute them at some point in the future. Defaults to whatever the wait keyword argument was for the QConnection instance (i.e. this keyword argument overrides the instance-level default).	None

Raises:

Type	Description
RuntimeError	a closed IPC connection was used.
TypeError	Too many arguments were provided - q queries cannot have more than 8 parameters.
ValueError	Attempted to send a Python function over IPC.

Examples:

q = pykx.QConnection(host='localhost', port=5002)

Call an anonymous function with 2 parameters

q('{y+til x}', 10, 5)

Execute a q query with no parameters

q('til 10')

Call an anonymous function asynchronously with 3 parameters

q('{x set y+til z}', 'async_query', 10, 5, wait=False)

Call an anonymous function asynchronously by default with 3 parameters

q = pykx.QConnection(host='localhost', port=5002, wait=False)
# Because `wait=False`, all calls on this q instance are async by default:
q('{x set y+til z}', 'async_query', 10, 5)
# But we can issue sync calls by overriding the `wait` option on a per-call basis:
q('{x set y+til z}', 'async_query', 10, 5, wait=True)

__delattr__ method descriptor

__delattr__(/, name)

Implement delattr(self, name).

__eq__ method descriptor

__eq__(/, value)

Return self==value.

__format__ method descriptor

__format__(/, format_spec)

Default object formatter.

__ge__ method descriptor

__ge__(/, value)

Return self>=value.

__getattr__ method descriptor

__getattr__(/, name)

Return getattr(self, name).

__getattribute__ method descriptor

__getattribute__(/, name)

Return getattr(self, name).

__gt__ method descriptor

__gt__(/, value)

Return self>value.

__hash__ method descriptor

__hash__()

Return hash(self).

__init_subclass__ builtin

__init_subclass__()

This method is called when a class is subclassed.

The default implementation does nothing. It may be overridden to extend subclasses.

__le__ method descriptor

__le__(/, value)

Return self<=value.

__lt__ method descriptor

__lt__(/, value)

Return self<value.

__ne__ method descriptor

__ne__(/, value)

Return self!=value.

__new__ builtin

__new__(args, kwargs)

Create and return a new object. See help(type) for accurate signature.

__reduce__ method descriptor

__reduce__()

Helper for pickle.

__reduce_ex__ method descriptor

__reduce_ex__(/, protocol)

Helper for pickle.

__setattr__ method descriptor

__setattr__(/, name, value)

Implement setattr(self, name, value).

__sizeof__ method descriptor

__sizeof__()

Size of object in memory, in bytes.

__str__ method descriptor

__str__()

Return str(self).

__subclasshook__ builtin

__subclasshook__()

Abstract classes can override this to customize issubclass().

This is invoked early on by abc.ABCMeta.subclasscheck(). It should return True, False or NotImplemented. If it returns NotImplemented, the normal algorithm is used. Otherwise, it overrides the normal algorithm (and the outcome is cached).

close method descriptor

close()

Close the connection.

Examples:

Open and subsequently close a connection to a q process on localhost:

q = pykx.QConnection('localhost', 5001)
q.close()

Using this class with a with-statement should be preferred:

with QConnection('localhost', 5001) as q:
    # do stuff with q
    pass
# q is closed automatically

fileno method descriptor

fileno()

The file descriptor or handle of the connection.

max_num_threads property

max_num_threads()

The maximum number of secondary threads available to q.

This value can be set using the -s command-line flag, provided to q via the $QARGS environment variable. For example: QARGS='-s 8' python, or QARGS='-s 0' python.

num_threads property

num_threads()

The current number of secondary threads being used by q.

Computations in q will automatically be parallelized across this number of threads as q deems appropriate.

paths property

paths()

List of locations for the context interface to find q scripts in.

Defaults to the current working directory and $QHOME.

If you change directories, the current working directory stored in this list will automatically reflect that change.