pykx.q Library Reference Card
This page documents the functions found in the pykx.q
q library that are available.
This library can be installed by calling a helper function within PyKX
, this function will move
all the required files and libraries into your QHOME
directory.
import pykx as kx
kx.install_into_QHOME()
or equivalently using only command line
python -c "import pykx as kx; kx.install_into_QHOME()"
.pykx.eval
Evaluates a string
as python code and return the result as a wrapped foreign
type.
.pykx.eval[pythonCode]
Parameters:
name | type | description |
---|---|---|
pythonCode |
string | A string of Python code to be executed returning the result as a wrapped foreign object. |
Return:
type | description |
---|---|
composition |
A wrapped foreign object which can be converted to q or Python objects |
// Evaluate the code and return as a wrapped foreign object
q).pykx.eval"1+1"
{[f;x].pykx.i.pykx[f;x]}[foreign]enlist
// Evaluate the code and convert to Python foreign
q).pykx.eval["1+1"]`.
foreign
// Evaluate the code and convert to a q object
q).pykx.eval["lambda x: x + 1"][5]`
6
.pykx.pyeval
Evaluates a CharVector
as python code and return the result as a q
foreign.
.pykx.pyeval[pythonCode]
Parameters:
name | type | description |
---|---|---|
pythonCode |
string | A string of Python code to be evaluated returning the result as a q foreign object. |
Return:
type | description |
---|---|
foreign |
The return of the Python string evaluation returned as a q foreign. |
// evaluate a Python string
q).pykx.pyeval"1+1"
foreign
// Use a function defined in Python taking a single argument
q).pykx.pyeval["lambda x: x + 1"][5]
foreign
// Use a function defined in Python taking multiple arguments
q).pykx.pyeval["lambda x, y: x + y"][4;5]
foreign
.pykx.pyexec
Executes a CharVector
as python code in Python memory.
.pykx.pyexec[pythonCode]
Parameters:
name | type | description |
---|---|---|
pythonCode |
string | A string of Python code to be executed. |
Return:
type | description |
---|---|
:: |
Returns generic null on successful execution, will return an error if execution of Python code is unsuccessful. |
// Execute valid Python code
q).pykx.pyexec"1+1"
q).pykx.pyexec"a = 1+1"
// Evaluate the Python code returning the result to q
q).pykx.qeval"a"
2
// Attempt to execute invalid Python code
q).pykx.pyexec"1+'test'"
'TypeError("unsupported operand type(s) for +: 'int' and 'str'")
[0] .pykx.pyexec["1+'test'"]
^
.pykx.qeval
Evaluates a CharVector
in Python returning the result as a q object.
.pykx.qeval[pythonCode]
Parameters:
name | type | description |
---|---|---|
pythonCode |
string | A string of Python code to be evaluated returning the result as a q object. |
Return:
type | description |
---|---|
any |
The return of the Python string evaluation returned as a q object. |
// evaluate a Python string
q).pykx.qeval"1+1"
2
// Use a function defined in Python taking a single argument
q).pykx.qeval["lambda x: x + 1"][5]
6
// Use a function defined in Python taking multiple arguments
q).pykx.pyeval["lambda x, y: x + y"][4;5]
9
.pykx.get
Retrieve a named item from the Python memory
.pykx.get[objectName]
Parameters:
name | type | description |
---|---|---|
objectName |
symbol | A named entity to retrieve from Python memory as a wrapped q foreign object. |
Return:
type | description |
---|---|
composition |
A wrapped foreign object which can be converted to q or Python objects |
// Set an item in Python memory and retrieve using .pykx.get
q).pykx.set[`test;til 10]
q).pykx.get[`test]
{[f;x].pykx.i.pykx[f;x]}[foreign]enlist
// Convert to q and Python objects
q).pykx.get[`test]`
0 1 2 3 4 5 6 7 8 9
// Retrieve an item defined entirely using Python
q).pykx.pyexec"import numpy as np"
q).pykx.pyexec"a = np.array([1, 2, 3])"
q).pykx.get[`a]`
1 2 3
.pykx.set
Set a q object to a named and type specified object in Python memory
.pykx.set[objectName;qObject]
Parameters:
name | type | description |
---|---|---|
objectName |
symbol | The name to be associated with the q object being persisted to Python memory |
qObject |
any | The q/Python entity that is to be stored to Python memory |
Return:
type | description |
---|---|
:: |
Returns null on successful execution |
// Set a q array of guids using default behaviour
q).pykx.set[`test;3?0Ng]
q)print .pykx.get`test
[UUID('3d13cc9e-f7f1-c0ee-782c-5346f5f7b90e')
UUID('c6868d41-fa85-233b-245f-55160cb8391a')
UUID('e1e5fadd-dc8e-54ba-e30b-ab292df03fb0')]
// Set a q table as pandas dataframe
q).pykx.set[`test;.pykx.topd ([]5?1f;5?1f)]
q)print .pykx.get`test
x x1
0 0.301772 0.392752
1 0.785033 0.517091
2 0.534710 0.515980
3 0.711172 0.406664
4 0.411597 0.178084
// Set a q table as pyarrow table
q).pykx.set[`test;.pykx.topa ([]2?0p;2?`a`b`c;2?1f;2?0t)]
q)print .pykx.get`test
pyarrow.Table
x: timestamp[ns]
x1: string
x2: double
x3: duration[ns]
----
x: [[2002-06-11 11:57:24.452442976,2001-12-28 01:34:14.199305176]]
x1: [["c","a"]]
x2: [[0.7043314231559634,0.9441670505329967]]
x3: [[2068887000000,41876091000000]]
.pykx.import
Import a Python library and store as a wrapped foreign object to allow use in q projections/evaluation.
.pykx.import[libName]
Parameters:
name | type | description |
---|---|---|
libName |
symbol | The name of the Python library/module to imported for use |
Return:
type | description |
---|---|
composition |
Returns a wrapped foreign object associated with an imported library on success, otherwise will error if library/module cannot be imported. |
// Import numpy for use as a q object named numpy
q)np:.pykx.import`numpy
q).pykx.print np
<module 'numpy' from '/usr/local/lib64/python3.9/site-packages/numpy/__init__.py'>
// Use a function from within the numpy library using attribute retrieval
q).pykx.print np[`:arange]
<built-in function arange>
q)np[`:arange][10]`
0 1 2 3 4 5 6 7 8 9
.pykx.console
Open an interactive python REPL from within a q session similar to launching python
from the command line.
.pykx.console[null]
Parameters:
name | type | description |
---|---|---|
null |
null | Activation of the .pykx.console does not require any input |
Return:
type | description |
---|---|
:: |
This function has no explicit return but execution of the function will initialise a Python repl. |
// Enter PyKX console and evaluate Python code
q).pykx.console[]
>>> 1+1
2
>>> list(range(10))
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> quit()
q)
// Enter PyKX console setting q objects using PyKX
q).pykx.console[]
>>> import pykx as kx
>>> kx.q['table'] = kx.q('([]2?1f;2?0Ng;2?`3)'
>>> quit()
q)table
x x1 x2
--------------------------------------------------
0.439081 49f2404d-5aec-f7c8-abba-e2885a580fb6 mil
0.5759051 656b5e69-d445-417e-bfe7-1994ddb87915 igf
.pykx.wrap
Convert a foreign object generated from Python execution to a callable q
object.
.pykx.wrap[pyForeign]
Parameters:
name | type | description |
---|---|---|
pyForeign |
foreign | A Python object which is to be converted to a callable q object. |
Returns:
type | description |
---|---|
composition |
The Python object wrapped such that it can be called using q |
// Create a q foreign object in Python
q)a:.pykx.pyeval"pykx.Foreign([1, 2, 3])"
q)a
foreign
q).pykx.print a
[1, 2, 3]
// Wrap the foreign object and convert to q
q)b:.pykx.wrap a
q)b
{[f;x].pykx.i.pykx[f;x]}[foreign]enlist
q)b`
1 2 3
.pykx.unwrap
Convert a wrapped foreign object generated from this interface into a python foreign.
.pykx.unwrap[wrapObj]
Parameters:
name | type | description |
---|---|---|
wrapObj |
composition/foreign | A (un)wrapped Python foreign object. |
Returns:
type | description |
---|---|
foreign |
The unwrapped representation of the Python foreign object. |
// Generate an object which returns a wrapped Python foreign
q).pykx.set[`test;.pykx.topd ([]2?0p;2?`a`b`c;2?1f;2?0t)]
q)a:.pykx.get`test
q)show a
{[f;x].pykx.i.pykx[f;x]}[foreign]enlist
// Unwrap the wrapped object
q).pykx.unwrap a
foreign
.pykx.getattr
Retrieve an attribute or property form a foreign Python object returning another foreign.
.pykx.getattr[pythonObject;attrName]
Parameters:
name | type | description |
---|---|---|
pythonObject |
foreign/composition | The Python object from which the defined attribute is to be retrieved |
attrName |
symbol | The name of the attribute to be retrieved. |
Returns:
type | description |
---|---|
foreign |
An unwrapped foreign object containing the retrieved |
Note
Application of this function is equivalent to calling Python's getattr(f, 'x')
function.
The wrapped foreign objects provide a shorthand version of calling .pykx.getattr
. Through the use of the `:x
syntax for attribute/property retrieval
// Define a class object from which to retrieve Python attributes
q).pykx.pyexec"aclass = type('TestClass', (object,), {'x': pykx.LongAtom(3), 'y': pykx.toq('hello')})";
// Retrieve the class object from Python as a q foreign
q)show a:.pykx.get[`aclass]`.
foreign
// Retrieve an attribute from the Python foreign
q).pykx.getattr[a;`y]
foreign
// Print the Python representation of the foreign object
q)print .pykx.getattr[a;`y]
hello
// Retrieve the attribute from a Python foreign and convert to q
q).pykx.wrap[.pykx.getattr[a;`y]]`
`hello
.pykx.setattr
Set an attribute of a Python object, this is equivalent to calling Python's setattr(f, a, x)
function
.pykx.setattr[pythonObject;attrName;attrObj]
Parameters:
name | type | description |
---|---|---|
pythonObject |
foreign/composition | The Python object on which the defined attribute is to be set |
attrName |
symbol | The name to be associated with the set attribute |
attrObject |
any | The object which is to be set as an attribute associated with pythonObject |
Returns:
type | description |
---|---|
:: |
Returns generic null on successful execution otherwise returns the error message raised |
// Define a Python object to which attributes can be set
q).pykx.pyexec"aclass = type('TestClass', (object,), {'x': pykx.LongAtom(3), 'y': pykx.toq('hello')})";
q)a:.pykx.get`aclass
// Retrieve an existing attribute to show defined behaviour
q)a[`:x]`
3
// Retrieve a named attribute that doesn't exist
q)a[`:r]`
// Set an attribute 'r' and retrieve the return
q).pykx.setattr[a; `r; til 4]
q)a[`:r]`
0 1 2 3
q).pykx.print a[`:r]
[0 1 2 3]
// Set an attribute 'k' to be a Pandas type
q).pykx.setattr[a;`k;.pykx.topd ([]2?1f;2?0Ng;2?`2)]
q)a[`:k]`
x x1 x2
-------------------------------------------------
0.4931835 0a3e1784-0125-1b68-5ae7-962d49f2404d mi
0.5785203 5aecf7c8-abba-e288-5a58-0fb6656b5e69 ig
q).pykx.print a[`:k]
x x1 x2
0 0.493183 0a3e1784-0125-1b68-5ae7-962d49f2404d mi
1 0.578520 5aecf7c8-abba-e288-5a58-0fb6656b5e69 ig
// Attempt to set an attribute against an object which does not support this behaviour
q)arr:.pykx.eval"[1, 2, 3]"
q).pykx.setattr[arr;`test;5]
'AttributeError("'list' object has no attribute 'test'")
[1] /opt/kx/pykx.q:218: .pykx.i.setattr:
cx:count x;
i.load[(`set_attr;4)][unwrap x 0;x 1;;x 2]
^
$[cx>4;
.pykx.setdefault
Define the default conversion type for KX objects when converting from q to Python
.pykx.setdefault[conversionFormat]
Parameters:
name | type | description |
---|---|---|
conversionFormat |
string | The Python data format to which all q objects when passed to Python will be converted. |
Returns:
type | description |
---|---|
:: |
Returns generic null on successful execution and updates variable .pykx.i.defaultConv |
Supported Options
The following outline the supported conversion types and the associated values which can be passed to set these values
Conversion Format | Accepted inputs |
---|---|
Numpy | "np", "numpy", "Numpy" |
Pandas | "pd", "pandas", "Pandas" |
Python | "py", "python", "Python" |
PyArrow | "pa", "pyarrow", "PyArrow" |
K | "k", "q" |
// Default value on startup is `"np"`
q).pykx.i.defaultConv
"np"
// Set default value to Pandas
q).pykx.setdefault["Pandas"]
q).pykx.i.defaultConv
"pd"
.pykx.print
Print a python object directly to stdout. This is equivalent to calling print()
on the object in Python.
.pykx.print[pythonObject]
print[pythonObject]
Parameters:
name | type | description |
---|---|---|
pythonObject |
(wrapped) foreign | A Python object retrieved from the Python memory space, if passed a q object this will be 'shown' |
Return:
type | description |
---|---|
:: |
Will print the output to stdout but return null |
Note
For back compatibility with embedPy this function is also supported in the shorthand form print
which uses the .q
namespace. To not overwrite print
in your q session and allow use only of the longhand form .pykx.print
set the environment variable UNSET_PYKX_GLOBALS
to any value.
// Use a wrapped foreign object
q)a: .pykx.eval"1+1"
q).pykx.print a
2
// Use a foreign object
q)a: .pykx.eval"'hello world'"
q).pykx.print a`.
hello world
// Use a q object
q).pykx.print til 5
0 1 2 3 4
// Use the shorthand "print" function
q)a:.pykx.eval"'hello world'"
q)print a
hello world
.pykx.repr
Evaluate the python function repr()
on an object retrieved from Python memory
.pykx.repr[pythonObject]
Parameters:
name | type | description |
---|---|---|
pythonObject |
(wrapped) foreign | A Python object retrieved from the Python memory space, if passed a q object this will retrieved using .Q.s1 . |
Return:
type | description |
---|---|
string |
The string representation of the Python/q object |
// Use a wrapped foreign object
q)a: .pykx.eval"1+1"
q).pykx.repr a
,"2"
// Use a foreign object
q)a: .pykx.eval"'hello world'"
q).pykx.repr a`.
"hello world"
// Use a q object
q).pykx.repr til 5
"0 1 2 3 4"
.pykx.toq
Convert an (un)wrapped PyKX
foreign object into an analogous q type.
.pykx.toq[pythonObject]
Parameters:
name | type | description |
---|---|---|
pythonObject |
foreign/composition | A foreign Python object or composition containing a Python foreign to be converted to q |
Return:
type | description |
---|---|
any |
A q object converted from Python |
// Convert a wrapped PyKX foreign object to q
q)show a:.pykx.eval["1+1"]
{[f;x].pykx.i.pykx[f;x]}[foreign]enlist
q).pykx.toq a
2
// Convert an unwrapped PyKX foreign object to q
q)show b:a`.
foreign
q).pykx.toq b
2
.pykx.tok
Tag a q object to be indicate conversion to a Pythonic PyKX object when called in Python
.pykx.tok[qObject]
Parameters:
name | type | description |
---|---|---|
qObject |
any |
A q object which is to be defined as a PyKX object in Python. |
Return:
type | description |
---|---|
projection |
A projection which is used to indicate that once the q object is passed to Python for evaluation is should be treated as a PyKX type object. |
// Denote that a q object once passed to Python should be managed as a PyKX object
q).pykx.tok til 10
enlist[`..k;;][0 1 2 3 4 5 6 7 8 9]
// Pass a q object to Python with default conversions and return type
q).pykx.print .pykx.eval["lambda x: type(x)"]til 10
<class 'numpy.ndarray'>
// Pass a q object to Python treating the Python object as a PyKX object
q).pykx.print .pykx.eval["lambda x: type(x)"] .pykx.tok til 10
<class 'pykx.wrappers.LongVector'>
.pykx.topd
Tag a q object to be indicate conversion to a Pandas object when called in Python
.pykx.topd[qObject]
Parameters:
name | type | description |
---|---|---|
qObject |
any |
A q object which is to be defined as a Pandas object in Python. |
Return:
type | description |
---|---|
projection |
A projection which is used to indicate that once the q object is passed to Python for evaluation is should be treated as a Pandas type object. |
// Denote that a q object once passed to Python should be managed as a Pandas object
q).pykx.topd til 10
enlist[`..pandas;;][0 1 2 3 4 5 6 7 8 9]
// Pass a q object to Python with default conversions and return type
q).pykx.print .pykx.eval["lambda x: type(x)"]til 10
<class 'numpy.ndarray'>
// Pass a q object to Python treating the Python object as a Pandas Object
q).pykx.print .pykx.eval["lambda x: type(x)"] .pykx.topd til 10
<class 'pandas.core.series.Series'>
.pykx.topa
Tag a q object to be indicate conversion to a PyArrow object when called in Python
.pykx.topa[qObject]
Parameters:
name | type | description |
---|---|---|
qObject |
any |
A q object which is to be defined as a PyArrrow object in Python. |
Return:
type | description |
---|---|
projection |
A projection which is used to indicate that once the q object is passed to Python for evaluation is should be treated as a PyArrow type object. |
// Denote that a q object once passed to Python should be managed as a PyArrow object
q).pykx.topa til 10
enlist[`..pyarrow;;][0 1 2 3 4 5 6 7 8 9]
// Pass a q object to Python with default conversions and return type
q).pykx.print .pykx.eval["lambda x: type(x)"]til 10
<class 'numpy.ndarray'>
// Pass a q object to Python treating the Python object as a PyArrow Object
q).pykx.print .pykx.eval["lambda x: type(x)"] .pykx.topa til 10
<class 'pyarrow.lib.Int64Array'>
.pykx.topy
Tag a q object to be indicate conversion to a Python object when called in Python
.pykx.topa[qObject]
Parameters:
name | type | description |
---|---|---|
qObject |
any |
A q object which is to be defined as a Python object in Python. |
Return:
type | description |
---|---|
projection |
A projection which is used to indicate that once the q object is passed to Python for evaluation is should be treated as a Python type object. |
// Denote that a q object once passed to Python should be managed as a Python object
q).pykx.topy til 10
enlist[`..python;;][0 1 2 3 4 5 6 7 8 9]
// Pass a q object to Python with default conversions and return type
q).pykx.print .pykx.eval["lambda x: type(x)"]til 10
<class 'numpy.ndarray'>
// Pass a q object to Python treating the Python object as a Python Object
q).pykx.print .pykx.eval["lambda x: type(x)"] .pykx.topy til 10
<class 'list'>
.pykx.tonp
Tag a q object to be indicate conversion to a Numpy object when called in Python
.pykx.tonp[qObject]
Parameters:
name | type | description |
---|---|---|
qObject |
any |
A q object which is to be defined as a Numpy object in Python. |
Return:
type | description |
---|---|
projection |
A projection which is used to indicate that once the q object is passed to Python for evaluation is should be treated as a Numpy type object. |
// Denote that a q object once passed to Python should be managed as a Numpy object
q).pykx.tonp til 10
enlist[`..numpy;;][0 1 2 3 4 5 6 7 8 9]
// Update the default conversion type to be non numpy
q).pykx.i.defaultConv:"py"
// Pass a q object to Python with default conversions and return type
q).pykx.print .pykx.eval["lambda x: type(x)"]til 10
<class 'list'>
// Pass a q object to Python treating the Python object as a Numpy Object
q).pykx.print .pykx.eval["lambda x: type(x)"] .pykx.tonp til 10
<class 'numpy.ndarray'>