Skip to content

Commit e0a1aef

Browse files
committed
update docs with how the valkey class hierarchy is structured now
1 parent d016d72 commit e0a1aef

File tree

2 files changed

+17
-12
lines changed

2 files changed

+17
-12
lines changed

docs/commands/valkey_native_commands.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ False
1212
"value1"
1313
```
1414

15-
the list of supported commands is very long, if needed you can check the methods at ``django_valkey.cache.ValkeyCache```
15+
the list of supported commands is very long, if needed you can check the methods at `django_valkey.base.BackendCommands`.
1616

1717
### Infinite timeout
1818

docs/customize.md

Lines changed: 16 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,9 @@ django-valkey comes with three base classes: `django_valkey.base.BaseValkeyCache
88

99
## BaseValkeyCache
1010

11-
`BaseValkeyCache` inherits from django's `BaseCache` class and `typing.Generic`.
12-
`BaseCache` adds basic cache functionality, such as `get()` and `set()`, and `typing.Generic` allows for a more robust type hinting.
13-
`BaseValkeyCache` adds more valkey oriented methods to BaseCache, things like `expire()` and `get_lock()`, and uses Generic to type hint two things:
11+
`BaseValkeyCache` is not a standalone class, to make use of it you need to add the actual methods, in `django-valkey` this is done by `django_valkey.base.BackendCommands` or `django_valkey.base.AsyncBackendCommands` depending if you use sync or async clients
12+
`BaseValkeyCache` contains connection methods and configures the behaviour of the cache
13+
`BaseValkeyCache` inherits from `typing.Generic` to type hint two things:
1414
1. the client, such as `django_valkey.client.default.DefaultClient`.
1515
2. the underlying backend, such as `valkey.Valkey`.
1616

@@ -19,23 +19,26 @@ to inherit from this base class you can take the example of our own cache backen
1919
```python
2020
from valkey import Valkey
2121

22-
from django_valkey.base import BaseValkeyCache
22+
from django_valkey.base import BaseValkeyCache, BackendCommands
2323
from django_valkey.client import DefaultClient
2424

25-
class ValkeyCache(BaseValkeyCache[DefaultClient, Valkey]):
25+
class ValkeyCache(BaseValkeyCache[DefaultClient, Valkey], BackendCommands):
2626
DEFAULT_CLIENT_CLASS = "django_valkey.client.DefaultClient"
2727
...
2828
```
2929

30-
the class attribute defined in the example is **mandatory**, it is so we can have imports in other modules.
30+
the `DEFAULT_CLIENT_CLASS` class attribute defined in the example is **mandatory**, it is so we can have imports in other modules.
3131

32-
`BaseValkeyCache` has both *sync* and *async* methods implemented, but there is no logic in them, most methods need to be overwritten.
32+
`BaseValkeyCache` can work with both *sync* and *async* subclasses, but it doesn't implement any of the methods, you need to inherit the command classes for this to work.
3333

3434

3535
## BaseClient
36-
`BaseClient` inherits from `typing.Generic` to make cleaner type hints.
37-
this class has all the logic necessary for a cache client (it is a copy of the old DefaultClient class), it finds the different servers and connects to them, add has all the commands that valkey supports.
36+
like `BaseValkeyCache`, `BaseClient` is not a standalone class.
37+
this class has all the logic necessary to connect to a cache server, and utility methods that helps with different operations,
38+
but it does not handle any of the operations by itself, you need one of `django_valkey.base_client.ClientCommands` or `django_valkey.base_client.AsyncClientCommands` for sync or async clients, respectively.
39+
the command classes implement the actual operations such as `get` and `set`.
3840

41+
`BaseClient` inherits from `typing.Generic` to make cleaner type hints.
3942
the `typing.Generic` needs a backend to be passed in, e.g: `valkey.Valkey`
4043

4144
the base class also needs the subclasses to have a `CONNECTION_FACTORY_PATH` class variable pointing to the connection factory class.
@@ -45,14 +48,16 @@ an example code would look like this:
4548
```python
4649
from valkey import Valkey
4750

48-
from django_valkey.base_client import BaseClient
51+
from django_valkey.base_client import BaseClient, ClientCommands
4952

50-
class DefaultClient(BaseClient[Valkey]):
53+
class DefaultClient(BaseClient[Valkey], ClientCommands[Valkey]):
5154
CONNECTION_FACTORY_PATH = "django_valkey.pool.ConnectionFactory"
5255
```
5356

5457
*note* that CONNECTION_FACTORY_PATH is only used if `DJANGO_VALKEY_CONNECTION_FACTORY` is not set.
5558

59+
`BaseClient` can work with both sync and async subclasses, you would use one of `django_valkey.base_client.ClientCommands` for sync, and `django_valkey.base_client.AsyncClientCommands` for async clients.
60+
5661

5762
## BaseConnectionFactory
5863

0 commit comments

Comments
 (0)