RedisGears Functions Runtime ¶
Python RedisGears functions are run using an embedded Python interpreter. Each function uses a separate sub-interpreter. All functions share the same environment and dependencies. The environment is imported with several defaults.
The following sections describe the runtime environment.
Python Interpreter ¶
RedisGears embeds a Python version 3.7.2+ interpreter.
All functions use this interpreter. Each call to
RG.PYEXECUTE
maintains its own globals dictionary that isolates its execution context from other calls. This means that all of the functions submitted in a given call share the same interpreter and globals dictionary.
Environment ¶
The interpreter's environment can be extended with any dependent package that can later be imported and used by functions in their respective sub-interpreters.
Further reference
For more information about installing dependencies refer to:
GearsBuilder ¶
The
GearsBuilder
class is imported to the runtime's environment by default.
It exposes the functionality of the function's context builder .
execute ¶
The
execute()
function is imported to the runtime's environment by default.
This function executes an arbitrary Redis command.
Python API
def execute(command, *args)
Arguments
- command : the command to execute
- args : the command's arguments
Examples
# Pings the server (reply should be 'PONG')
reply = execute('PING')
atomic ¶
The
atomic()
Python context is imported to the runtime's environment by default.
The context ensures that all operations in it are executed atomically by blocking the main Redis process.
Python API
class atomic()
Examples
# Increments two keys atomically
def transaction(_):
with atomic():
execute('INCR', f'{{{hashtag()}}}:foo')
execute('INCR', f'{{{hashtag()}}}:bar')
gb = GB('ShardsIDReader')
gb.foreach(transaction)
gb.run()
configGet ¶
The
configGet()
function is imported to the runtime's environment by default.
This function fetches the current value of a RedisGears configuration option.
Python API
def configGet(key)
Arguments
- key : the configuration option key
Examples
# Gets the current value for 'ProfileExecutions'
foo = configGet('ProfileExecutions')
gearsConfigGet ¶
The
gearsConfigGet()
function is imported to the runtime's environment by default.
This function fetches the current value of a RedisGears configuration option and returns a default value if that key does not exist.
Python API
def gearsConfigGet(key, default=None)
Arguments
- key : the configuration option key
- default : a default value
Examples
# Gets the 'foo' configuration option key and defaults to 'bar'
foo = gearsConfigGet('foo', default='bar')
hashtag ¶
The
hashtag()
function is imported to the runtime's environment by default.
This function returns a hashtag that maps to the lowest hash slot served by the local engine's shard. Put differently, it is useful as a hashtag for partitioning in a cluster.
Python API
def hashtag()
Examples
# Get the shard's hashtag
ht = hashtag()
log ¶
The
log()
function is imported to the runtime's environment by default.
This function prints a message to Redis' log.
Python API
def log(message, level='notice')
Arguments
- message : the message to output
-
level
: the message's log level can be one of these:
- 'debug'
- 'verbose'
- 'notice'
- 'warning'
Examples
# Dumps every datum in the DB to the log for "debug" purposes
GB().foreach(lambda x: Log(str(x), level='debug')).run()
Async Await ¶
For a full explination about async await look at Async Await Support
createFuture ¶
The
createFuture
function is imported to the runtime's environment by default.
This function returns a
gearsFuture
object, which can be waited on using
await
inside a coroutine.
Python API
def createFuture()
setFutureResults ¶
The
setFutureResults
function is imported to the runtime's environment by default.
This function allows set a result on a future object returned from createFuture
Python API
def setFutureResults(f, res)
Arguments
- f: future object to set the result on.
- res: the result to set on the future object.
setFutureException ¶
The
setFutureException
function is imported to the runtime's environment by default.
This function allows set an exception on a future object returned from createFuture
Python API
def setFutureException(f, ex)
Arguments
- f: future object to set the result on.
- ex: the exception to set on the future object.
runCoroutine ¶
The
runCoroutine
function is imported to the runtime's environment by default.
This function allows run a coroutine in a dedicated event loop.
Python API
def runCoroutine(cr, f=None, delay=0)
Arguments
- cr: coroutine to run.
- f: future object to set the coroutine result on (if none the result are ignored).
- delay: delay (in seconds) to start the coroutine.
isAsyncAllow ¶
The
isAsyncAllow
function is imported to the runtime's environment by default.
This function allows to know if async await can be used in the current execution, for more info refer to sync with multi exec .
Python API
def isAsyncAllow()
call_next ¶
The
call_next
function is imported to the runtime's environment by default.
This function allows you to call the next hook registered on the command or the original Redis command (for further reading about command hook, please refer to Commands Hook ). It is only possible to call this API when hooking a command. Any attempt to call this API in the wrong context will result in an error.
Python API
def call_next(*args)
Arguments
- args: arguments with which to invoke the next hook.
override_reply ¶
The
override_reply
function is imported to the runtime's environment by default.
This function allows to override the reply of the client linked to the execution. It is only possible to use it on
KeysReader
with combination of the
commands
argument. For further reading please refer to
key miss event
taturial.
Python API
def override_reply(reply)
Arguments
-
reply: the new reply to send to the client. If the reply starts with
-
it will be returned as error reply. If the reply starts with+
it will be returned as a status reply.
flat_error ¶
The
flat_error
function is imported to the runtime's environment by default.
This function raise a special exception type that instructs gears not to extract the error stack trace.
Python API
def flat_error(msg)
Arguments
- msg: The error msg to add as is in the execution error list.