`sider.sortedset` — Sorted sets¶

See also

Redis Data Types: The Redis documentation that explains about its data types: strings, lists, sets, sorted sets and hashes.

class sider.sortedset.SortedSet(session, key, value_type=<class 'sider.types.ByteString'>)¶

The Python-sider representation of Redis sorted set value. It behaves in similar way to collections.Counter object which became a part of standard library since Python 2.7.

It implements collections.MutableMapping and collections.MutableSet protocols.

Mappings of Redis commands–`SortedSet` methods¶
Redis commands	`SortedSet` methods
DEL	`SortedSet.clear()`
ZADD	`=` (`SortedSet.__setitem__()`)
ZCARD	`len()` (`SortedSet.__len__()`)
ZINCRBY	`SortedSet.add()`, `SortedSet.discard()`, `SortedSet.update()`
ZRANGE	`iter()` (`SortedSet.__iter__()`)
ZRANGE WITHSCORES	`SortedSet.items()`, `SortedSet.most_common()`, `SortedSet.least_common()`
ZREM	`del` (`SortedSet.__delitem__()`), `SortedSet.discard()`
ZSCORE	`SortedSet.__getitem__()`, `in` (`SortedSet.__contains__()`)
ZUNIONSTORE	`SortedSet.update()`
N/A	`SortedSet.setdefault()`
N/A	`SortedSet.pop()`
N/A	`SortedSet.popitem()`

__contains__(*args, **kwargs)¶

in operator. Tests whether the set contains the given operand member.

Parameters:	member – the value to test
Returns:	`True` if the sorted set contains the given operand `member`
Return type:	`bool`

Note

This method internally uses ZSCORE command.

__delitem__(member)¶

Removes the member.

Parameters:	member – the member to delete
Raises:	exceptions.TypeError – if the given `member` is not acceptable by its `value_type` exceptions.KeyError – if there’s no such `member`

Note

It is directly mapped to Redis ZREM command when it’s not on transaction. If it’s used with transaction, it internally uses ZSCORE and ZREM commands.

__getitem__(*args, **kwargs)¶

Gets the score of the given member.

Parameters:	member – the member to get its score
Returns:	the score of the `member`
Return type:	`numbers.Real`
Raises:	exceptions.TypeError – if the given `member` is not acceptable by its `value_type` exceptions.KeyError – if there’s no such `member`

Note

It is directly mapped to Redis ZSCORE command.

__len__(*args, **kwargs)¶

Gets the cardinality of the sorted set.

Returns:	the cardinality (the number of elements) of the sorted set
Return type:	`numbers.Integral`

Note

It is directly mapped to Redis ZCARD command.

__setitem__(*args, **kwargs)¶

Sets the score of the member. Adds the member if it doesn’t exist.

Parameters:	member – the member to set its `score` scorew – the score to set of the `member`
Raises:	exceptions.TypeError – if the given `member` is not acceptable by its `value_type` or the given `score` is not a `numbers.Real` object

Note

It is directly mapped to Redis ZADD command.

add(*args, **kwargs)¶

Adds a new member or increases its score (default is 1).

Parameters:	member – the member to add or increase its score score (`numbers.Real`) – the amount to increase the score. default is 1

Note

This method is directly mapped to ZINCRBY command.

clear(*args, **kwargs)¶: Removes all values from this sorted set.

Note

Under the hood it simply DEL the key.

discard(member, score=1, remove=0)¶

Opposite operation of add(). It decreases its score (default is 1). When its score get the remove number (default is 0) or less, it will be removed.

If you don’t want to remove it but only decrease its score, pass None into remove parameter.

If you want to remove member, not only decrease its score, use __delitem__() instead:

del sortedset[member]

Parameters:	member – the member to decreases its score score (`numbers.Real`) – the amount to decrease the score. default is 1 remove (`numbers.Real`) – the threshold score to be removed. if `None` is passed, it doesn’t remove the member but only decreases its score (it makes `score` argument meaningless). default is 0.

Note

This method is directly mapped to ZINCRBY command when remove is None.

Otherwise, it internally uses ZSCORE plus ZINCRBY or :redis:`ZREM (total two commands) within a transaction.

items(*args, **kwargs)¶

Returns an ordered of pairs of elements and these scores.

Parameters:	reverse (`bool`) – order result descendingly if it’s `True`. default is `False` which means ascending order
Returns:	an ordered list of pairs. every pair looks like (element, score)
Return type:	`collections.Sequence`

Note

This method is directly mapped to ZRANGE command and WITHSCORES option.

keys(reverse=False)¶

Gets its all elements. Equivalent to __iter__() except it returns an ordered Sequence instead of iterable.

Parameters:	reverse (`bool`) – order result descendingly if it’s `True`. default is `False` which means ascending order
Returns:	the ordered list of its all keys
Return type:	`collections.Sequence`

Note

This method is directly mapped to Redis ZRANGE command.

least_common(*args, **kwargs)¶

Returns a list of the n least common (exactly, lowly scored) members and their counts (scores) from the least common to the most. If n is not specified, it returns all members in the set. Members with equal scores are ordered arbitarily.

Parameters:	n (`numbers.Integral`) – the number of members to get
Returns:	an ordered list of pairs. every pair looks like (element, score)
Return type:	`collections.Sequence`

Note

This method is directly mapped to ZREVRANGE command and WITHSCORES option.

most_common(n=None, reverse=False)¶

Returns a list of the n most common (exactly, highly scored) members and their counts (scores) from the most common to the least. If n is not specified, it returns all members in the set. Members with equal scores are ordered arbitarily.

Parameters:	n (`numbers.Integral`) – the number of members to get
Returns:	an ordered list of pairs. every pair looks like (element, score)
Return type:	`collections.Sequence`

Note

This method is directly mapped to ZRANGE command and WITHSCORES option.

pop(*args, **kwargs)¶

Populates a member of the set.

If key keyword argument or one or more positional arguments have present, it behaves like dict.pop() method:

Parameters:	key – the member to populate. it will be removed if it exists default – the default value returned instead of the member (`key`) when it doesn’t exist. default is `None`
Returns:	the score of the member before the operation has been committed
Return type:	`numbers.Real`

Note

It internally uses ZSCORE, ZREM or ZINCRBY (total 2 commands) in a transaction.

If no positional arguments or no key keyword argument, it behaves like set.pop() method. Basically it does the same thing with popitem() except it returns just a popped value (while popitem() returns a pair of popped value and its score).

Parameters:	desc (`bool`) – keyword only. by default, it populates the member of the lowest score, but if you pass `True` to this it will populates the highest instead. default is `False`
Returns:	the populated member. it will be the lowest scored member or the highest scored member if `desc` is `True`
Raises:	exceptions.KeyError – when the set is empty

Note

It internally uses ZRANGE or ZREVRANGE, ZREM or ZINCRBY (total 2 commands) in a transaction.

See also

Method pop()

setdefault(key, default=1)¶

Gets the score of the given key if it exists or adds key with default score.

Parameters:	key – the member to get its score default (`numbers.Real`) – the score to be set if the `key` doesn’t exist. default is 1
Returns:	the score of the `key` after the operation has been committed
Return type:	`numbers.Real`

Note

It internally uses one or two commands. At first it sends ZSCORE command to check whether the key exists and get its score if it exists. If it doesn’t exist yet, it sends one more command: ZADD. It is atomically committed in a transaction.

update(*sets, **keywords)¶

Merge with passed sets and keywords. It’s behavior is almost equivalent to dict.update() and set.update() except it’s aware of scores.

For example, assume the initial elements and their scores of the set is (in notation of dictionary):

{'c': 1, 'a': 2, 'b': 3}

and you has updated it:

sortedset.update(set('acd'))

then it becomes (in notation of dictionary):

{'d': 1, 'c': 2, 'a': 3, 'b': 3}

You can pass mapping objects or keywords instead to specify scores to increment:

sortedset.update({'a': 1, 'b': 2})
sortedset.update(a=1, b=2)
sortedset.update(set('ab'), set('cd'),
                 {'a': 1, 'b': 2}, {'c': 1, 'd': 2},
                 a=1, b=2, c=1, d=2)

Parameters:	sets – sets or mapping objects to merge with. mapping objects can specify scores by values *keywords – if `value_type` takes byte strings you can specify elements and its scores by keyword arguments

Note

There’s an incompatibility with dict.update(). It always treats iterable of pairs as set of pairs, not mapping pairs, unlike dict.update(). It is for resolving ambiguity (remember value_type can take tuples or such things).

Note

Under the hood it uses multiple ZINCRBY commands and ZUNIONSTORE if there are one or more SortedSet objects in operands.

value_type = None¶: (sider.types.Bulk) The type of set elements.

values(*args, **kwargs)¶

Returns an ordered list of scores.

Parameters:	reverse (`bool`) – order result descendingly if it’s `True`. default is `False` which means ascending order
Returns:	an ordered list of scores
Return type:	`collections.Sequence`

Note

This method internally uses ZRANGE command and WITHSCORES option.

`sider.sortedset` — Sorted sets¶

Previous topic

Next topic

This Page

Parameters:	desc (`bool`) – by default, it populates the member of the lowest score, but if you pass `True` to this parameter it will populates the highest instead. default is `False` score (`numbers.Real`) – the amount to decrease the score. default is 1 remove (`numbers.Real`) – the threshold score to be removed. if `None` is passed, it doesn’t remove the member but only decreases its score (it makes `score` argument meaningless). default is 0.
Returns:	a pair of the populated member and its score. the first part of a pair will be the lowest scored member or the highest scored member if `desc` is `True`. the second part of a pair will be the score before the operation has been committed
Return type:	`tuple`
Raises:	exceptions.KeyError – when the set is empty

sider.sortedset — Sorted sets¶

`sider.sortedset` — Sorted sets¶