Package: hiredis
hiredis-pyPython extension that wraps protocol parsing code inhiredis.
It primarily speeds up parsing of multi bulk replies.How do I Redis?Learn for free at Redis UniversityBuild faster with the Redis LaunchpadTry the Redis CloudDive in developer tutorialsJoin the Redis communityWork at RedisInstallhiredis-py is available onPyPI, and can be installed via:pipinstallhiredisBuilding and TestingBuilding this repository requires a recursive checkout of submodules, and building hiredis. The following example shows how to clone, compile, and run tests. Please note - you will need the gcc installed.gitclone--recursse-submoduleshttps://github.com/redis/hiredis-py
pythonsetup.pybuild_ext--inplace
python-mpytestRequirementshiredis-py requiresPython 3.7+.Make sure Python development headers are available when installing hiredis-py.
On Ubuntu/Debian systems, install them withapt-get install python3-dev.UsageThehiredismodule contains theReaderclass. This class is responsible for
parsing replies from the stream of data that is read from a Redis connection.
It does not contain functionality to handle I/O.Reply parserTheReaderclass has two methods that are used when parsing replies from a
stream of data.Reader.feedtakes a string argument that is appended to the
internal buffer.Reader.getsreads this buffer and returns a reply when the
buffer contains a full reply. If a single call tofeedcontains multiple
replies,getsshould be called multiple times to extract all replies.Example:>>>reader=hiredis.Reader()>>>reader.feed("$5\r\nhello\r\n")>>>reader.gets()b'hello'When the buffer does not contain a full reply,getsreturnsFalse.
This means extra data is needed andfeedshould be called again before callinggetsagain. Alternatively you could provide custom sentinel object via parameter,
which is useful for RESP3 protocol where native boolean types are supported:Example:>>>reader.feed("*2\r\n$5\r\nhello\r\n")>>>reader.gets()False>>>reader.feed("$5\r\nworld\r\n")>>>reader.gets()[b'hello',b'world']>>>reader=hiredis.Reader(notEnoughData=Ellipsis)>>>reader.gets()EllipsisUnicodehiredis.Readeris able to decode bulk data to any encoding Python supports.
To do so, specify the encoding you want to use for decoding replies when
initializing it:>>>reader=hiredis.Reader(encoding="utf-8",errors="strict")>>>reader.feed(b"$3\r\n\xe2\x98\x83\r\n")>>>reader.gets()'☃'Decoding of bulk data will be attempted using the specified encoding and
error handler. If the error handler is'strict'(the default), aUnicodeDecodeErroris raised when data cannot be dedcoded. This is identical
to Python's default behavior. Other valid values toerrorsinclude'replace','ignore', and'backslashreplace'. More information on the
behavior of these error handlers can be foundhere.When the specified encoding cannot be found, aLookupErrorwill be raised
when callinggetsfor the first reply with bulk data.Error handlingWhen a protocol error occurs (because of multiple threads using the same
socket, or some other condition that causes a corrupt stream), the errorhiredis.ProtocolErroris raised. Because the buffer is read in a lazy
fashion, it will only be raised whengetsis called and the first reply in
the buffer contains an error. There is no way to recover from a faulty protocol
state, so when this happens, the I/O code feeding data toReadershould
probably reconnect.Redis can reply with error replies (-ERR ...). For these replies, the custom
error classhiredis.ReplyErroris returned,but not raised.When other error types should be used (so existing code doesn't have to change
itsexceptclauses),Readercan be initialized with theprotocolErrorandreplyErrorkeywords. These keywords should contain aclassthat is a
subclass ofException. When not provided,Readerwill use the default
error types.BenchmarksThe repository contains a benchmarking script in thebenchmarkdirectory,
which usesgeventto have non-blocking I/O and redis-py
to handle connections. These benchmarks are done with a patched version of
redis-py that uses hiredis-py when it is available.All benchmarks are done with 10 concurrent connections.SET key value + GET keyredis-py: 11.76 Kopsredis-pywithhiredis-py: 13.40 Kopsimprovement:1.1xList entries in the following tests are 5 bytes.LRANGE list 09:redis-py: 4.78 Kopsredis-pywithhiredis-py: 12.94 Kopsimprovement:2.7xLRANGE list 099:redis-py: 0.73 Kopsredis-pywithhiredis-py: 11.90 Kopsimprovement:16.3xLRANGE list 0999:redis-py: 0.07 Kopsredis-pywithhiredis-py: 5.83 Kopsimprovement:83.2xThroughput improvement for simple SET/GET is minimal, but the larger multi bulk replies
get, the larger the performance improvement is.LicenseThis code is released under the BSD license, after the license of hiredis.