Script Development / Simple Cache `DFF.CACHE`

DFF.CACHE is a Redis-based temporary cache with the structure scope + key -> value, suitable for counters, queues, sets, and lightweight message publishing.

When you need to preserve JSON types or persistently store small-scale application state, use DFF.STORE.

Key Differences

Scalar values read out are usually strings; call int(...), float(...), or json.loads(...) according to the business type.
The default scope is the current Script ID; when sharing data across Scripts, you must explicitly pass the same scope.
Every Key and publish Topic is isolated by Scope; returned Key names do not include the internal Scope prefix.
hstrlenall(...) returns {field: byte length of value}; the length unit is bytes, not Unicode characters.

API Quick Reference

Key

Method	Description
`type(key, scope=None)`	Returns the data type of the Key
`keys(pattern='*', scope=None)`	Returns matching Keys
`exists(key, scope=None)`	Checks whether the Key exists
`expire(key, expires, scope=None)`	Sets the remaining expiration time in seconds
`expireat(key, timestamp, scope=None)`	Sets the expiration time as a UNIX timestamp in seconds
`ttl(key, scope=None)` / `pttl(key, scope=None)`	Returns the remaining expiration time, in seconds and milliseconds respectively
`rename(key, new_key, scope=None)`	Renames the Key
`renamenx(key, new_key, scope=None)`	Renames the Key only when the target does not exist
`delete(key, scope=None)`	Deletes a single Key, or pass a list / tuple for batch deletion
`delete_pattern(pattern, scope=None)`	Deletes matching Keys; `pattern` is required

String

Method	Description
`set(key, value, expires=None, not_exists=False, exists=False, scope=None)`	Writes a value, optionally restricting Key existence state and expiration seconds
`mset(key_values, scope=None)`	Writes in batch; setting an expiration time at the same time is not supported
`get(key, scope=None)` / `DFF.CACHE(key, scope=None)`	Reads a single value
`mget(keys, scope=None)`	Reads in batch
`get_pattern(pattern, scope=None)`	Returns matching `{key: value}`
`getset(key, value, scope=None)`	Writes a new value and returns the old value
`incr(key, step=1, scope=None)` / `incrby(key, step, scope=None)`	Increments an integer value

Hash

Method	Description
`hkeys(key, pattern='*', with_values=False, scope=None)`	Returns matching fields; when `with_values=True`, also returns values
`hset(key, field, value, not_exists=False, scope=None)`	Writes a field
`hsetnx(key, field, value, scope=None)`	Writes only when the field does not exist
`hmset(key, field_values, scope=None)`	Writes fields in batch
`hget(key, field, scope=None)`	Reads a field
`hstrlen(key, field, scope=None)` / `hstrlenall(key, scope=None)`	Returns the byte length of one or all field values
`hmget(key, fields, scope=None)`	Reads fields in batch
`hgetall(key, scope=None)`	Reads all fields and values
`hincr(key, field, step=1, scope=None)` / `hincrby(key, field, step, scope=None)`	Increments an integer field value
`hdel(key, field, scope=None)`	Deletes a single field, or pass a list / tuple for batch deletion

List

Method	Description
`lpush(key, value, scope=None)` / `rpush(key, value, scope=None)`	Pushes a value or a list of values from the left / right
`lpop(key, count=None, scope=None)` / `rpop(key, count=None, scope=None)`	Pops one or more values from the left / right
`blpop(key, timeout=0, scope=None)` / `brpop(key, timeout=0, scope=None)`	Blocking pop
`rpoplpush(key, dest_key=None, scope=None, dest_scope=None)`	Pops from the right side of the source list and pushes to the left side of the destination list
`brpoplpush(key, dest_key=None, timeout=0, scope=None, dest_scope=None)`	Blocking pop and push
`llen(key, scope=None)`	Returns the length of the list
`lrange(key, start=0, stop=-1, scope=None)`	Returns the specified range
`ltrim(key, start, stop, scope=None)`	Keeps only the specified range

blpop(...) and brpop(...) return [original Key, value], and return [None, None] on timeout. rpoplpush(...) and brpoplpush(...) use the source Key when the destination Key is omitted; dest_scope can be used for explicit cross-Scope moves.

Set

Method	Description
`sadd(key, member, scope=None)` / `srem(key, member, scope=None)`	Adds / removes a member or a list of members
`scard(key, scope=None)`	Returns the number of members
`smembers(key, scope=None)`	Returns all members
`sismember(key, member, scope=None)`	Checks whether a member exists

ZSet

Method	Description
`zadd(key, member_scores, scope=None)` / `zrem(key, member, scope=None)`	Adds / removes members
`zcard(key, scope=None)`	Returns the number of members
`zrange(key, start=0, stop=-1, with_scores=False, scope=None)`	Returns members by position
`zrangebyscore(key, min_score='-inf', max_score='+inf', with_scores=False, scope=None)`	Returns members by score
`zpop_below_all(key, score, scope=None)` / `zpop_above_all(key, score, scope=None)`	Pops all members whose scores are not higher than / not lower than the specified score
`zpop_below_lpush_all(key, dest_key, score, scope=None)` / `zpop_above_lpush_all(key, dest_key, score, scope=None)`	Pops members matching the score condition and pushes them to the destination list

Before executing the ZSet pop or move extension, confirm the source Key, destination Key, and score boundaries.

Publishing and Dynamic References

Method	Description
`publish(topic, message, scope=None)`	Publishes a message to a Topic prefixed with Scope
`ref(key, scope=None, default=None)`	Creates a lazy reference for `DFF.API` parameters that support dynamic values

When scope is omitted, ref(...) uses a dedicated REF Scope. String, List, Hash, Set, and ZSet use their respective read operations to resolve references. References are used only for the delayed_cron_job, timeout, expires, and queue parameters of DFF.API.

Example

Common Data Structures
import json

DFF.CACHE.set('count', 1, expires=60, scope='job')
count = int(DFF.CACHE.get('count', scope='job') or 0)

DFF.CACHE.hmset('user:001', {'name': 'Tom', 'age': 20}, scope='users')
age = int(DFF.CACHE.hget('user:001', 'age', scope='users') or 0)

DFF.CACHE.rpush('queue', json.dumps({'id': 1}), scope='jobs')
item = json.loads(DFF.CACHE.lpop('queue', scope='jobs'))

Usage Notes

Blocking operations should set a reasonable timeout to avoid Func timeout.
Before executing delete_pattern(...), first use keys(...) to check for matching entries.
Avoid calling hstrlenall(...) on very large Hashes to prevent blocking the shared cache service.
publish(...) Topics have a Scope prefix; subscribers must use a consistent Scope convention.
When multiple Scripts share data, explicitly pass scope.

Script Development / Simple Cache DFF.CACHE