Skip to content

PyKX Configurable Behaviour

The following document outlines how users can modify the underlying behaviour of PyKX based on their specific use-case. The options presented are provided for use-case/performance tuned optimisations of the library itself.

Setting of these configuration options is supported via a configuration file or environment variables as described below. In all cases environment variable definitions will take precedence over definitions within the configuration file.

Configuration File

Users can use a configuration file .pykx-config to define configuration options for PyKX initialisation. The following provides an example of a .pykx-config file which operates according to *.toml syntax:

[default]
PYKX_IGNORE_QHOME="true"
PYKX_KEEP_LOCAL_TIMES="true"

[test]
PYKX_GC="true"
PYKX_RELEASE_GIL="true"

On import of PyKX the file .pykx-config will be searched for according to the following path ordering, the first location containing a .pykx-config file will be used for definition of the :

Order Location
1. Path('.')
2. Path(os.getenv('PYKX_CONFIGURATION_LOCATION'))
3. Path.home()

When loading this file unless otherwise specified PyKX will use the profile default. Use of non default profiles from within this file can be configured through the setting of an environment variable PYKX_PROFILE prior to loading of PyKX, for example using the above configuration file.

>>> import pykx as kx
>>> kx.config.ignore_qhome
    True
>>> import os
>>> os.environ['PYKX_PROFILE'] = "test"
>>> import pykx as kx
>>> kx.config.k_gc
True

Environment variables

For users wishing to make use of the provided options as environment variables this is also supported, for example a user can define the environment variables to use before import of PyKX as follows.

>>> import os
>>> os.environ['PYKX_RELEASE_GIL'] = '1'
>>> os.environ['PYKX_GC'] = '1'
>>> import pykx as kx
>>> kx.config.k_gc
True

Options

The options can be used to tune PyKX behavior at run time. These variables need to be set before attempting to import PyKX and will take effect for the duration of the execution of the PyKX process.

General

The following variables can be used to enable or disable advanced features of PyKX across all modes of operation:

Option Default Values Description Status
PYKX_IGNORE_QHOME False 1 or true When loading PyKX on a machine with an existing q installation (and the environment variable QHOME set to the installation folder), PyKX will look within this directory for q scripts their dependencies. It will then symlink these files to make them available to load under PyKX. This variable instructs PyKX to not perform this symlinking.
PYKX_KEEP_LOCAL_TIMES False 1 or true When converting a Python datetime object to q, PyKX will translate the Python datetime into UTC before the conversion. This variable instructs PyKX to convert the Python datetime using the local timezone.
PYKX_ALLOCATOR False 1 or true When converting a Numpy array to q, PyKX implements a full data copy in order to translate the Numpy array to q representation in memory. When this is set PyKX implements NEP-49 which allows q to handle memory allocation of all Numpy arrays so they can be converted more efficiently to q. This avoids the need to resort to a copy where possible.
PYKX_GC False 1 or true When PYKX_ALLOCATOR is enabled, PyKX can trigger q garbage collector when Numpy arrays allocated by PyKX are deallocated. This variable enables this behavior which will release q memory to the OS following deallocation of the numpy array at the cost of a small overhead.
PYKX_LOAD_PYARROW_UNSAFE False 1 or true By default, PyKX uses a subprocess to import pyarrow as it can result in a crash when the version of pyarrow is incompatible. This variable will trigger a normal import of pyarrow and importing PyKX should be slightly faster.
PYKX_MAX_ERROR_LENGTH 256 size in characters By default, PyKX reports IPC connection errors with a message buffer of size 256 characters. This allows the length of these error messages to be modified reducing the chance of excessive error messages polluting logs.
PYKX_NOQCE False 1 or true On Linux, PyKX comes with q Cloud Edition features from Insights Core (https://code.kx.com/insights/1.2/core/). This variable allows a user to skip the loading of q Cloud Edition functionality, saving some time when importing PyKX but removing access to possibly supported additional functionality.
PYKX_Q_LIB_LOCATION UNSET Path to a directory containing q libraries necessary for loading PyKX See here for detailed information. This allows a user to centralise the q libraries, q.k, read.q, libq.so etc to a managed location within their environment which is decentralised from the Python installation. This is required for some enterprise use-cases.
PYKX_RELEASE_GIL False 1 or true When PYKX_RELEASE_GIL is enabled the Python Global Interpreter Lock will not be held when calling into q.
PYKX_Q_LOCK False 1 or true When PYKX_Q_LOCK is enabled a reentrant lock is added around calls into q, this lock will stop multiple threads from calling into q at the same time. This allows embedded q to be threadsafe even when using PYKX_RELEASE_GIL.
PYKX_DEBUG_INSIGHTS_LIBRARIES False 1 or true If the insights libraries failed to load this variable can be used to print out the full error output for debugging purposes.
IGNORE_QHOME True 1 or true When loading PyKX on a machine with an existing q installation (and the environment variable QHOME set to the installation folder), PyKX will look within this directory for q scripts their dependencies. It will then symlink these files to make them available to load under PyKX. This variable instructs PyKX to not perform this symlinking. DEPRECATED, please use PYKX_IGNORE_QHOME
KEEP_LOCAL_TIMES False 1 or true When converting a Python datetime object to q, PyKX will translate the Python datetime into UTC before the conversion. This variable instructs PyKX to convert the Python datetime using the local timezone. DEPRECATED, please use PYKX_KEEP_LOCAL_TIMES

The variables below can be used to set the environment for q (embedded in PyKX, in licensed mode):

Variable Values Description
QARGS See link Command-line flags to pass to q, see here for more information.
QHOME Path to the users q installation folder See here for more information.
QLIC Path to the folder where the q license should be found See here for more information.

PyKX under q

PyKX can be loaded and used from a q session (see here for more information). The following variables are specific to this mode of operation.

Variable Values Description Status
PYKX_DEFAULT_CONVERSION py, np, pd, pa or k Default conversion to apply when passing q objects to Python. Converting to Numpy (np) by default.
PYKX_SKIP_UNDERQ 1 or true When importing PyKX from Python, PyKX will also load pykx.q under its embedded q. This variable skip this step.
PYKX_UNSET_GLOBALS 1 or true By default "PyKX under q" will load some utility functions into the global namespace (eg. print). This variable prevents this.
PYKX_PYTHON_LIB_PATH File path The path to use for loading libpython.
PYKX_PYTHON_BASE_PATH File path The path to use for the base directory of your Python installation.
PYKX_PYTHON_HOME_PATH File path The path to use for the base Python home directory (used to find site packages).
SKIP_UNDERQ 1 or true When importing PyKX from Python, PyKX will also load pykx.q under its embedded q. This variable skip this step. DEPRECATED, please use PYKX_SKIP_UNDERQ
UNSET_PYKX_GLOBALS 1 or true By default "PyKX under q" will load some utility functions into the global namespace (eg. print). This variable prevents this. DEPRECATED, please use PYKX_UNSET_GLOBALS

q Cloud Edition features with Insights Core (Linux only)

On Linux, the q Cloud Edition features, coming with Insights Core, can be used to read data from Cloud Storage (AWS S3, Google Cloud Storage, Azure Blob Storage). Credentials to access the Cloud Storage can be passed using specific environment variables. For more information, see the two following links: