Fake implementation of redis API for testing purposes.
Project description
fakeredis: A fake version of a redis-py
- fakeredis: A fake version of a redis-py
- How to Use
- Other limitations
- Support for redis-py <4.2 with aioredis
- Running the Tests
- Contributing
- Alternatives
fakeredis is a pure-Python implementation of the redis-py python client that simulates talking to a redis server. This was created for a single purpose: to write unittests. Setting up redis is not hard, but many times you want to write unittests that do not talk to an external server (such as redis). This module now allows tests to simply use this module as a reasonable substitute for redis.
Although fakeredis is pure Python, you will need lupa if you want to run Lua
scripts (this includes features like redis.lock.Lock, which are implemented
in Lua). If you install fakeredis with pip install fakeredis[lua] it will
be automatically installed.
For a list of supported/unsupported redis commands, see REDIS_COMMANDS.md
How to Use
FakeRedis can imitate Redis server version 6.x or 7.x - There are a few minor behavior differences. If you do not specify the version, version 7 is used by default.
The intent is for fakeredis to act as though you're talking to a real redis server. It does this by storing state internally. For example:
>>> import fakeredis
>>> r = fakeredis.FakeStrictRedis(version=6)
>>> r.set('foo', 'bar')
True
>>> r.get('foo')
'bar'
>>> r.lpush('bar', 1)
1
>>> r.lpush('bar', 2)
2
>>> r.lrange('bar', 0, -1)
[2, 1]
The state is stored in an instance of FakeServer. If one is not provided at
construction, a new instance is automatically created for you, but you can
explicitly create one to share state:
>>> import fakeredis
>>> server = fakeredis.FakeServer()
>>> r1 = fakeredis.FakeStrictRedis(server=server)
>>> r1.set('foo', 'bar')
True
>>> r2 = fakeredis.FakeStrictRedis(server=server)
>>> r2.get('foo')
'bar'
>>> r2.set('bar', 'baz')
True
>>> r1.get('bar')
'baz'
>>> r2.get('bar')
'baz'
It is also possible to mock connection errors so you can effectively test
your error handling. Simply set the connected attribute of the server to
False after initialization.
>>> import fakeredis
>>> server = fakeredis.FakeServer()
>>> server.connected = False
>>> r = fakeredis.FakeStrictRedis(server=server)
>>> r.set('foo', 'bar')
ConnectionError: FakeRedis is emulating a connection error.
>>> server.connected = True
>>> r.set('foo', 'bar')
True
Fakeredis implements the same interface as redis-py, the
popular redis client for python, and models the responses
of redis 6.2 (although most new features are not supported).
Use to test django-rq
There is a need to override django_rq.queues.get_redis_connection with
a method returning the same connection.
from fakeredis import FakeRedisConnSingleton
django_rq.queues.get_redis_connection = FakeRedisConnSingleton()
Other limitations
Apart from unimplemented commands, there are a number of cases where fakeredis won't give identical results to real redis. The following are differences that are unlikely to ever be fixed; there are also differences that are fixable (such as commands that do not support all features) which should be filed as bugs in Github.
-
Hyperloglogs are implemented using sets underneath. This means that the
typecommand will return the wrong answer, you can't usegetto retrieve the encoded value, and counts will be slightly different (they will in fact be exact). -
When a command has multiple error conditions, such as operating on a key of the wrong type and an integer argument is not well-formed, the choice of error to return may not match redis.
-
The
incrbyfloatandhincrbyfloatcommands in redis use the Clong doubletype, which typically has more precision than Python'sfloattype. -
Redis makes guarantees about the order in which clients blocked on blocking commands are woken up. Fakeredis does not honour these guarantees.
-
Where redis contains bugs, fakeredis generally does not try to provide exact bug-compatibility. It's not practical for fakeredis to try to match the set of bugs in your specific version of redis.
-
There are a number of cases where the behaviour of redis is undefined, such as the order of elements returned by set and hash commands. Fakeredis will generally not produce the same results, and in Python versions before 3.6 may produce different results each time the process is re-run.
-
SCAN/ZSCAN/HSCAN/SSCAN will not necessarily iterate all items if items are deleted or renamed during iteration. They also won't necessarily iterate in the same chunk sizes or the same order as redis.
-
DUMP/RESTORE will not return or expect data in the RDB format. Instead the
picklemodule is used to mimic an opaque and non-standard format. WARNING: Do not use RESTORE with untrusted data, as a malicious pickle can execute arbitrary code.
Support for redis-py <4.2 with aioredis
Aioredis is now in redis-py 4.2.0. But support is maintained until fakeredis 2 for older version of redis-py.
You can also use fakeredis to mock out aioredis. This is a much newer addition to fakeredis (added in 1.4.0) with less testing, so your mileage may vary. Both version 1 and version 2 (which have very different APIs) are supported. The API provided by fakeredis depends on the version of aioredis that is installed.
aioredis 1.x
Example:
>>> import fakeredis.aioredis
>>> r = await fakeredis.aioredis.create_redis_pool()
>>> await r.set('foo', 'bar')
True
>>> await r.get('foo')
b'bar'
You can pass a FakeServer as the first argument to create_redis or
create_redis_pool to share state (you can even share state with a
fakeredis.FakeRedis). It should even be safe to do this state sharing between
threads (as long as each connection/pool is only used in one thread).
It is highly recommended that you only use the aioredis support with Python 3.5.3 or higher. Earlier versions will not work correctly with non-default event loops.
aioredis 2.x
Example:
>>> import fakeredis.aioredis
>>> r = fakeredis.aioredis.FakeRedis()
>>> await r.set('foo', 'bar')
True
>>> await r.get('foo')
b'bar'
The support is essentially the same as for redis-py e.g., you can pass a
server keyword argument to the FakeRedis constructor.
Running the Tests
To ensure parity with the real redis, there are a set of integration tests that mirror the unittests. For every unittest that is written, the same test is run against a real redis instance using a real redis-py client instance. In order to run these tests you must have a redis server running on localhost, port 6379 (the default settings). WARNING: the tests will completely wipe your database!
First install poetry if you don't have it, and then install all the dependencies:
pip install poetry
poetry install
To run all the tests:
poetry run pytest -v
If you only want to run tests against fake redis, without a real redis::
poetry run pytest -m fake
Because this module is attempting to provide the same interface as redis-py,
the python bindings to redis, a reasonable way to test this to to take each
unittest and run it against a real redis server. fakeredis and the real redis
server should give the same result. To run tests against a real redis instance
instead::
poetry run pytest -m real
If redis is not running and you try to run tests against a real redis server, these tests will have a result of 's' for skipped.
There are some tests that test redis blocking operations that are somewhat slow. If you want to skip these tests during day to day development, they have all been tagged as 'slow' so you can skip them by running::
poetry run pytest -m "not slow"
Contributing
Contributions are welcome. Please see the contributing guide for more details. The maintainer generally has very little time to work on fakeredis, so the best way to get a bug fixed is to contribute a pull request.
If you'd like to help out, you can start with any of the issues
labeled with Help wanted.
Alternatives
Consider using redislite instead of fakeredis. It runs a real redis server and connects to it over a UNIX domain socket, so it will behave just like a real server. Another alternative is birdisle, which runs the redis code as a Python extension (no separate process), but which is currently unmaintained.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file fakeredis-1.9.3.tar.gz.
File metadata
- Download URL: fakeredis-1.9.3.tar.gz
- Upload date:
- Size: 39.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | ea7e4ed076def2eea36188662586a9f2271946ae56ebc2de6a998c82b33df776 |
|
| MD5 | 33c865fb1befe6f039fe9cfcf60e3031 |
|
| BLAKE2b-256 | c7d125fd683fa252a2307a1677366ee215661ac2e888efef6624ebc3fc86d948 |
File details
Details for the file fakeredis-1.9.3-py3-none-any.whl.
File metadata
- Download URL: fakeredis-1.9.3-py3-none-any.whl
- Upload date:
- Size: 39.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.1 CPython/3.9.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 74a2f1e5e8781014418fe734b156808d5d1a2d15edec982fada3d6e7603f8536 |
|
| MD5 | cb5e1025f344c1ec1337dd8c92939691 |
|
| BLAKE2b-256 | a55a16580815cc666a1f4e970f8af864f539403d1d9f04df7f076d2153dd5a9d |
