Skip to content

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.

Further reference

For more information refer to:

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.

Further reference

For more information about Redis commands refer to:

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.