libvalkey 3.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. libvalkey-3.0.0/LICENSE +21 -0
  2. libvalkey-3.0.0/MANIFEST.in +9 -0
  3. libvalkey-3.0.0/PKG-INFO +187 -0
  4. libvalkey-3.0.0/README.md +157 -0
  5. libvalkey-3.0.0/libvalkey/__init__.py +10 -0
  6. libvalkey-3.0.0/libvalkey/libvalkey.pyi +41 -0
  7. libvalkey-3.0.0/libvalkey/py.typed +0 -0
  8. libvalkey-3.0.0/libvalkey/version.py +1 -0
  9. libvalkey-3.0.0/libvalkey.egg-info/PKG-INFO +187 -0
  10. libvalkey-3.0.0/libvalkey.egg-info/SOURCES.txt +46 -0
  11. libvalkey-3.0.0/libvalkey.egg-info/dependency_links.txt +1 -0
  12. libvalkey-3.0.0/libvalkey.egg-info/top_level.txt +1 -0
  13. libvalkey-3.0.0/setup.cfg +7 -0
  14. libvalkey-3.0.0/setup.py +89 -0
  15. libvalkey-3.0.0/src/libvalkey.c +83 -0
  16. libvalkey-3.0.0/src/libvalkey.h +29 -0
  17. libvalkey-3.0.0/src/pack.c +122 -0
  18. libvalkey-3.0.0/src/pack.h +8 -0
  19. libvalkey-3.0.0/src/reader.c +557 -0
  20. libvalkey-3.0.0/src/reader.h +33 -0
  21. libvalkey-3.0.0/tests/test_gc.py +17 -0
  22. libvalkey-3.0.0/tests/test_pack.py +47 -0
  23. libvalkey-3.0.0/tests/test_reader.py +374 -0
  24. libvalkey-3.0.0/vendor/libvalkey/src/adlist.c +331 -0
  25. libvalkey-3.0.0/vendor/libvalkey/src/adlist.h +94 -0
  26. libvalkey-3.0.0/vendor/libvalkey/src/alloc.c +90 -0
  27. libvalkey-3.0.0/vendor/libvalkey/src/async.c +1034 -0
  28. libvalkey-3.0.0/vendor/libvalkey/src/async_private.h +75 -0
  29. libvalkey-3.0.0/vendor/libvalkey/src/cmddef.h +379 -0
  30. libvalkey-3.0.0/vendor/libvalkey/src/command.c +385 -0
  31. libvalkey-3.0.0/vendor/libvalkey/src/command.h +87 -0
  32. libvalkey-3.0.0/vendor/libvalkey/src/crc16.c +83 -0
  33. libvalkey-3.0.0/vendor/libvalkey/src/dict.c +343 -0
  34. libvalkey-3.0.0/vendor/libvalkey/src/fmacros.h +14 -0
  35. libvalkey-3.0.0/vendor/libvalkey/src/net.c +632 -0
  36. libvalkey-3.0.0/vendor/libvalkey/src/read.c +793 -0
  37. libvalkey-3.0.0/vendor/libvalkey/src/sds.c +1292 -0
  38. libvalkey-3.0.0/vendor/libvalkey/src/sdsalloc.h +44 -0
  39. libvalkey-3.0.0/vendor/libvalkey/src/sockcompat.c +280 -0
  40. libvalkey-3.0.0/vendor/libvalkey/src/ssl.c +619 -0
  41. libvalkey-3.0.0/vendor/libvalkey/src/valkey.c +1224 -0
  42. libvalkey-3.0.0/vendor/libvalkey/src/valkey_private.h +125 -0
  43. libvalkey-3.0.0/vendor/libvalkey/src/valkeycluster.c +3702 -0
  44. libvalkey-3.0.0/vendor/libvalkey/src/valkeycluster_ssl.c +46 -0
  45. libvalkey-3.0.0/vendor/libvalkey/src/vkutil.c +91 -0
  46. libvalkey-3.0.0/vendor/libvalkey/src/vkutil.h +55 -0
  47. libvalkey-3.0.0/vendor/libvalkey/src/win32.h +103 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2022-2023, the maintainers of this library.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,9 @@
1
+ include LICENSE
2
+ include MANIFEST.in
3
+ include README.md
4
+ include src/*.[ch]
5
+ include vendor/libvalkey/COPYING
6
+ include vendor/libvalkey/src/*.[ch]
7
+ graft tests
8
+ global-exclude __pycache__
9
+ global-exclude *.py[co]
@@ -0,0 +1,187 @@
1
+ Metadata-Version: 2.1
2
+ Name: libvalkey
3
+ Version: 3.0.0
4
+ Summary: Python wrapper for libvalkey
5
+ Home-page: https://github.com/valkey-io/libvalkey-py
6
+ Author: libvalkey-py authors
7
+ Author-email: libvalkey-py@lists.valkey.io
8
+ License: MIT
9
+ Project-URL: Changes, https://github.com/valkey-io/libvalkey-py/releases
10
+ Project-URL: Issue tracker, https://github.com/valkey-io/libvalkey-py/issues
11
+ Keywords: Valkey
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Operating System :: MacOS
16
+ Classifier: Operating System :: POSIX
17
+ Classifier: Programming Language :: C
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3 :: Only
20
+ Classifier: Programming Language :: Python :: 3.8
21
+ Classifier: Programming Language :: Python :: 3.9
22
+ Classifier: Programming Language :: Python :: 3.10
23
+ Classifier: Programming Language :: Python :: 3.11
24
+ Classifier: Programming Language :: Python :: 3.12
25
+ Classifier: Programming Language :: Python :: Implementation :: CPython
26
+ Classifier: Topic :: Software Development
27
+ Requires-Python: >=3.8
28
+ Description-Content-Type: text/markdown
29
+ License-File: LICENSE
30
+
31
+ # libvalkey-py
32
+
33
+ [![Build Status](https://github.com/valkey-io/libvalkey-py/actions/workflows/integration.yaml/badge.svg)](https://github.com/valkey-io/libvalkey-py/actions/workflows/integration.yaml)
34
+ [![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
35
+ [![pypi](https://badge.fury.io/py/libvalkey.svg)](https://pypi.org/project/libvalkey/)
36
+
37
+ Python extension that wraps protocol parsing code in [libvalkey][libvalkey].
38
+ It primarily speeds up parsing of multi bulk replies.
39
+
40
+ [libvalkey]: http://github.com/valkey-io/libvalkey
41
+
42
+ ## Install
43
+
44
+ libvalkey-py is available on [PyPI](https://pypi.org/project/libvalkey/), and can be installed via:
45
+
46
+ ```bash
47
+ pip install libvalkey
48
+ ```
49
+ ## Building and Testing
50
+
51
+ Building this repository requires a recursive checkout of submodules, and building libvalkey. The following example shows how to clone, compile, and run tests. Please note - you will need the gcc installed.
52
+
53
+ ```bash
54
+ git clone --recurse-submodules https://github.com/valkey-io/libvalkey-py
55
+ python setup.py build_ext --inplace
56
+ python -m pytest
57
+ ```
58
+
59
+ ### Requirements
60
+
61
+ libvalkey-py requires **Python 3.8+**.
62
+
63
+ Make sure Python development headers are available when installing libvalkey-py.
64
+ On Ubuntu/Debian systems, install them with `apt-get install python3-dev`.
65
+
66
+ ## Usage
67
+
68
+ The `libvalkey` module contains the `Reader` class. This class is responsible for
69
+ parsing replies from the stream of data that is read from a Redis connection.
70
+ It does not contain functionality to handle I/O.
71
+
72
+ ### Reply parser
73
+
74
+ The `Reader` class has two methods that are used when parsing replies from a
75
+ stream of data. `Reader.feed` takes a string argument that is appended to the
76
+ internal buffer. `Reader.gets` reads this buffer and returns a reply when the
77
+ buffer contains a full reply. If a single call to `feed` contains multiple
78
+ replies, `gets` should be called multiple times to extract all replies.
79
+
80
+ Example:
81
+
82
+ ```python
83
+ >>> reader = libvalkey.Reader()
84
+ >>> reader.feed("$5\r\nhello\r\n")
85
+ >>> reader.gets()
86
+ b'hello'
87
+ ```
88
+
89
+ When the buffer does not contain a full reply, `gets` returns `False`.
90
+ This means extra data is needed and `feed` should be called again before calling
91
+ `gets` again. Alternatively you could provide custom sentinel object via parameter,
92
+ which is useful for RESP3 protocol where native boolean types are supported:
93
+
94
+ Example:
95
+
96
+ ```python
97
+ >>> reader.feed("*2\r\n$5\r\nhello\r\n")
98
+ >>> reader.gets()
99
+ False
100
+ >>> reader.feed("$5\r\nworld\r\n")
101
+ >>> reader.gets()
102
+ [b'hello', b'world']
103
+ >>> reader = libvalkey.Reader(notEnoughData=Ellipsis)
104
+ >>> reader.gets()
105
+ Ellipsis
106
+ ```
107
+
108
+ #### Unicode
109
+
110
+ `libvalkey.Reader` is able to decode bulk data to any encoding Python supports.
111
+ To do so, specify the encoding you want to use for decoding replies when
112
+ initializing it:
113
+
114
+ ```python
115
+ >>> reader = libvalkey.Reader(encoding="utf-8", errors="strict")
116
+ >>> reader.feed(b"$3\r\n\xe2\x98\x83\r\n")
117
+ >>> reader.gets()
118
+ '☃'
119
+ ```
120
+
121
+ Decoding of bulk data will be attempted using the specified encoding and
122
+ error handler. If the error handler is `'strict'` (the default), a
123
+ `UnicodeDecodeError` is raised when data cannot be dedcoded. This is identical
124
+ to Python's default behavior. Other valid values to `errors` include
125
+ `'replace'`, `'ignore'`, and `'backslashreplace'`. More information on the
126
+ behavior of these error handlers can be found
127
+ [here](https://docs.python.org/3/howto/unicode.html#the-string-type).
128
+
129
+
130
+ When the specified encoding cannot be found, a `LookupError` will be raised
131
+ when calling `gets` for the first reply with bulk data.
132
+
133
+ #### Error handling
134
+
135
+ When a protocol error occurs (because of multiple threads using the same
136
+ socket, or some other condition that causes a corrupt stream), the error
137
+ `libvalkey.ProtocolError` is raised. Because the buffer is read in a lazy
138
+ fashion, it will only be raised when `gets` is called and the first reply in
139
+ the buffer contains an error. There is no way to recover from a faulty protocol
140
+ state, so when this happens, the I/O code feeding data to `Reader` should
141
+ probably reconnect.
142
+
143
+ The server can reply with error replies (`-ERR ...`). For these replies, the
144
+ custom error class `libvalkey.ReplyError` is returned, **but not raised**.
145
+
146
+ When other error types should be used (so existing code doesn't have to change
147
+ its `except` clauses), `Reader` can be initialized with the `protocolError` and
148
+ `replyError` keywords. These keywords should contain a *class* that is a
149
+ subclass of `Exception`. When not provided, `Reader` will use the default
150
+ error types.
151
+
152
+ ## Benchmarks
153
+
154
+ The repository contains a benchmarking script in the `benchmark` directory,
155
+ which uses [gevent](http://gevent.org/) to have non-blocking I/O and valkey-py
156
+ to handle connections. These benchmarks are done with a patched version of
157
+ valkey-py that uses libvalkey-py when it is available.
158
+
159
+ All benchmarks are done with 10 concurrent connections.
160
+
161
+ * SET key value + GET key
162
+ * valkey-py: 11.76 Kops
163
+ * valkey-py *with* libvalkey-py: 13.40 Kops
164
+ * improvement: **1.1x**
165
+
166
+ List entries in the following tests are 5 bytes.
167
+
168
+ * LRANGE list 0 **9**:
169
+ * valkey-py: 4.78 Kops
170
+ * valkey-py *with* libvalkey-py: 12.94 Kops
171
+ * improvement: **2.7x**
172
+ * LRANGE list 0 **99**:
173
+ * valkey-py: 0.73 Kops
174
+ * valkey-py *with* libvalkey-py: 11.90 Kops
175
+ * improvement: **16.3x**
176
+ * LRANGE list 0 **999**:
177
+ * valkey-py: 0.07 Kops
178
+ * valkey-py *with* libvalkey-py: 5.83 Kops
179
+ * improvement: **83.2x**
180
+
181
+ Throughput improvement for simple SET/GET is minimal, but the larger multi bulk replies
182
+ get, the larger the performance improvement is.
183
+
184
+ ## License
185
+
186
+ This code is released under the BSD license, as the license of hiredis-py at
187
+ the time of fork.
@@ -0,0 +1,157 @@
1
+ # libvalkey-py
2
+
3
+ [![Build Status](https://github.com/valkey-io/libvalkey-py/actions/workflows/integration.yaml/badge.svg)](https://github.com/valkey-io/libvalkey-py/actions/workflows/integration.yaml)
4
+ [![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
5
+ [![pypi](https://badge.fury.io/py/libvalkey.svg)](https://pypi.org/project/libvalkey/)
6
+
7
+ Python extension that wraps protocol parsing code in [libvalkey][libvalkey].
8
+ It primarily speeds up parsing of multi bulk replies.
9
+
10
+ [libvalkey]: http://github.com/valkey-io/libvalkey
11
+
12
+ ## Install
13
+
14
+ libvalkey-py is available on [PyPI](https://pypi.org/project/libvalkey/), and can be installed via:
15
+
16
+ ```bash
17
+ pip install libvalkey
18
+ ```
19
+ ## Building and Testing
20
+
21
+ Building this repository requires a recursive checkout of submodules, and building libvalkey. The following example shows how to clone, compile, and run tests. Please note - you will need the gcc installed.
22
+
23
+ ```bash
24
+ git clone --recurse-submodules https://github.com/valkey-io/libvalkey-py
25
+ python setup.py build_ext --inplace
26
+ python -m pytest
27
+ ```
28
+
29
+ ### Requirements
30
+
31
+ libvalkey-py requires **Python 3.8+**.
32
+
33
+ Make sure Python development headers are available when installing libvalkey-py.
34
+ On Ubuntu/Debian systems, install them with `apt-get install python3-dev`.
35
+
36
+ ## Usage
37
+
38
+ The `libvalkey` module contains the `Reader` class. This class is responsible for
39
+ parsing replies from the stream of data that is read from a Redis connection.
40
+ It does not contain functionality to handle I/O.
41
+
42
+ ### Reply parser
43
+
44
+ The `Reader` class has two methods that are used when parsing replies from a
45
+ stream of data. `Reader.feed` takes a string argument that is appended to the
46
+ internal buffer. `Reader.gets` reads this buffer and returns a reply when the
47
+ buffer contains a full reply. If a single call to `feed` contains multiple
48
+ replies, `gets` should be called multiple times to extract all replies.
49
+
50
+ Example:
51
+
52
+ ```python
53
+ >>> reader = libvalkey.Reader()
54
+ >>> reader.feed("$5\r\nhello\r\n")
55
+ >>> reader.gets()
56
+ b'hello'
57
+ ```
58
+
59
+ When the buffer does not contain a full reply, `gets` returns `False`.
60
+ This means extra data is needed and `feed` should be called again before calling
61
+ `gets` again. Alternatively you could provide custom sentinel object via parameter,
62
+ which is useful for RESP3 protocol where native boolean types are supported:
63
+
64
+ Example:
65
+
66
+ ```python
67
+ >>> reader.feed("*2\r\n$5\r\nhello\r\n")
68
+ >>> reader.gets()
69
+ False
70
+ >>> reader.feed("$5\r\nworld\r\n")
71
+ >>> reader.gets()
72
+ [b'hello', b'world']
73
+ >>> reader = libvalkey.Reader(notEnoughData=Ellipsis)
74
+ >>> reader.gets()
75
+ Ellipsis
76
+ ```
77
+
78
+ #### Unicode
79
+
80
+ `libvalkey.Reader` is able to decode bulk data to any encoding Python supports.
81
+ To do so, specify the encoding you want to use for decoding replies when
82
+ initializing it:
83
+
84
+ ```python
85
+ >>> reader = libvalkey.Reader(encoding="utf-8", errors="strict")
86
+ >>> reader.feed(b"$3\r\n\xe2\x98\x83\r\n")
87
+ >>> reader.gets()
88
+ '☃'
89
+ ```
90
+
91
+ Decoding of bulk data will be attempted using the specified encoding and
92
+ error handler. If the error handler is `'strict'` (the default), a
93
+ `UnicodeDecodeError` is raised when data cannot be dedcoded. This is identical
94
+ to Python's default behavior. Other valid values to `errors` include
95
+ `'replace'`, `'ignore'`, and `'backslashreplace'`. More information on the
96
+ behavior of these error handlers can be found
97
+ [here](https://docs.python.org/3/howto/unicode.html#the-string-type).
98
+
99
+
100
+ When the specified encoding cannot be found, a `LookupError` will be raised
101
+ when calling `gets` for the first reply with bulk data.
102
+
103
+ #### Error handling
104
+
105
+ When a protocol error occurs (because of multiple threads using the same
106
+ socket, or some other condition that causes a corrupt stream), the error
107
+ `libvalkey.ProtocolError` is raised. Because the buffer is read in a lazy
108
+ fashion, it will only be raised when `gets` is called and the first reply in
109
+ the buffer contains an error. There is no way to recover from a faulty protocol
110
+ state, so when this happens, the I/O code feeding data to `Reader` should
111
+ probably reconnect.
112
+
113
+ The server can reply with error replies (`-ERR ...`). For these replies, the
114
+ custom error class `libvalkey.ReplyError` is returned, **but not raised**.
115
+
116
+ When other error types should be used (so existing code doesn't have to change
117
+ its `except` clauses), `Reader` can be initialized with the `protocolError` and
118
+ `replyError` keywords. These keywords should contain a *class* that is a
119
+ subclass of `Exception`. When not provided, `Reader` will use the default
120
+ error types.
121
+
122
+ ## Benchmarks
123
+
124
+ The repository contains a benchmarking script in the `benchmark` directory,
125
+ which uses [gevent](http://gevent.org/) to have non-blocking I/O and valkey-py
126
+ to handle connections. These benchmarks are done with a patched version of
127
+ valkey-py that uses libvalkey-py when it is available.
128
+
129
+ All benchmarks are done with 10 concurrent connections.
130
+
131
+ * SET key value + GET key
132
+ * valkey-py: 11.76 Kops
133
+ * valkey-py *with* libvalkey-py: 13.40 Kops
134
+ * improvement: **1.1x**
135
+
136
+ List entries in the following tests are 5 bytes.
137
+
138
+ * LRANGE list 0 **9**:
139
+ * valkey-py: 4.78 Kops
140
+ * valkey-py *with* libvalkey-py: 12.94 Kops
141
+ * improvement: **2.7x**
142
+ * LRANGE list 0 **99**:
143
+ * valkey-py: 0.73 Kops
144
+ * valkey-py *with* libvalkey-py: 11.90 Kops
145
+ * improvement: **16.3x**
146
+ * LRANGE list 0 **999**:
147
+ * valkey-py: 0.07 Kops
148
+ * valkey-py *with* libvalkey-py: 5.83 Kops
149
+ * improvement: **83.2x**
150
+
151
+ Throughput improvement for simple SET/GET is minimal, but the larger multi bulk replies
152
+ get, the larger the performance improvement is.
153
+
154
+ ## License
155
+
156
+ This code is released under the BSD license, as the license of hiredis-py at
157
+ the time of fork.
@@ -0,0 +1,10 @@
1
+ from libvalkey.libvalkey import Reader, LibvalkeyError, pack_command, ProtocolError, ReplyError
2
+ from libvalkey.version import __version__
3
+
4
+ __all__ = [
5
+ "Reader",
6
+ "LibvalkeyError",
7
+ "pack_command",
8
+ "ProtocolError",
9
+ "ReplyError",
10
+ "__version__"]
@@ -0,0 +1,41 @@
1
+ from typing import Any, Callable, Optional, Union, Tuple
2
+
3
+
4
+ class LibvalkeyError(Exception):
5
+ ...
6
+
7
+
8
+ class ProtocolError(LibvalkeyError):
9
+ ...
10
+
11
+
12
+ class ReplyError(LibvalkeyError):
13
+ ...
14
+
15
+
16
+ class Reader:
17
+ def __init__(
18
+ self,
19
+ protocolError: Callable[[str], Exception] = ...,
20
+ replyError: Callable[[str], Exception] = ...,
21
+ encoding: Optional[str] = ...,
22
+ errors: Optional[str] = ...,
23
+ notEnoughData: Any = ...,
24
+ listOnly: bool = ...,
25
+ ) -> None: ...
26
+
27
+ def feed(
28
+ self, __buf: Union[str, bytes], __off: int = ..., __len: int = ...
29
+ ) -> None: ...
30
+ def gets(self, __shouldDecode: bool = ...) -> Any: ...
31
+ def setmaxbuf(self, __maxbuf: Optional[int]) -> None: ...
32
+ def getmaxbuf(self) -> int: ...
33
+ def len(self) -> int: ...
34
+ def has_data(self) -> bool: ...
35
+
36
+ def set_encoding(
37
+ self, encoding: Optional[str] = ..., errors: Optional[str] = ...
38
+ ) -> None: ...
39
+
40
+
41
+ def pack_command(cmd: Tuple[str | int | float | bytes | memoryview]): ...
File without changes
@@ -0,0 +1 @@
1
+ __version__ = "3.0.0"
@@ -0,0 +1,187 @@
1
+ Metadata-Version: 2.1
2
+ Name: libvalkey
3
+ Version: 3.0.0
4
+ Summary: Python wrapper for libvalkey
5
+ Home-page: https://github.com/valkey-io/libvalkey-py
6
+ Author: libvalkey-py authors
7
+ Author-email: libvalkey-py@lists.valkey.io
8
+ License: MIT
9
+ Project-URL: Changes, https://github.com/valkey-io/libvalkey-py/releases
10
+ Project-URL: Issue tracker, https://github.com/valkey-io/libvalkey-py/issues
11
+ Keywords: Valkey
12
+ Classifier: Development Status :: 5 - Production/Stable
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Operating System :: MacOS
16
+ Classifier: Operating System :: POSIX
17
+ Classifier: Programming Language :: C
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3 :: Only
20
+ Classifier: Programming Language :: Python :: 3.8
21
+ Classifier: Programming Language :: Python :: 3.9
22
+ Classifier: Programming Language :: Python :: 3.10
23
+ Classifier: Programming Language :: Python :: 3.11
24
+ Classifier: Programming Language :: Python :: 3.12
25
+ Classifier: Programming Language :: Python :: Implementation :: CPython
26
+ Classifier: Topic :: Software Development
27
+ Requires-Python: >=3.8
28
+ Description-Content-Type: text/markdown
29
+ License-File: LICENSE
30
+
31
+ # libvalkey-py
32
+
33
+ [![Build Status](https://github.com/valkey-io/libvalkey-py/actions/workflows/integration.yaml/badge.svg)](https://github.com/valkey-io/libvalkey-py/actions/workflows/integration.yaml)
34
+ [![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
35
+ [![pypi](https://badge.fury.io/py/libvalkey.svg)](https://pypi.org/project/libvalkey/)
36
+
37
+ Python extension that wraps protocol parsing code in [libvalkey][libvalkey].
38
+ It primarily speeds up parsing of multi bulk replies.
39
+
40
+ [libvalkey]: http://github.com/valkey-io/libvalkey
41
+
42
+ ## Install
43
+
44
+ libvalkey-py is available on [PyPI](https://pypi.org/project/libvalkey/), and can be installed via:
45
+
46
+ ```bash
47
+ pip install libvalkey
48
+ ```
49
+ ## Building and Testing
50
+
51
+ Building this repository requires a recursive checkout of submodules, and building libvalkey. The following example shows how to clone, compile, and run tests. Please note - you will need the gcc installed.
52
+
53
+ ```bash
54
+ git clone --recurse-submodules https://github.com/valkey-io/libvalkey-py
55
+ python setup.py build_ext --inplace
56
+ python -m pytest
57
+ ```
58
+
59
+ ### Requirements
60
+
61
+ libvalkey-py requires **Python 3.8+**.
62
+
63
+ Make sure Python development headers are available when installing libvalkey-py.
64
+ On Ubuntu/Debian systems, install them with `apt-get install python3-dev`.
65
+
66
+ ## Usage
67
+
68
+ The `libvalkey` module contains the `Reader` class. This class is responsible for
69
+ parsing replies from the stream of data that is read from a Redis connection.
70
+ It does not contain functionality to handle I/O.
71
+
72
+ ### Reply parser
73
+
74
+ The `Reader` class has two methods that are used when parsing replies from a
75
+ stream of data. `Reader.feed` takes a string argument that is appended to the
76
+ internal buffer. `Reader.gets` reads this buffer and returns a reply when the
77
+ buffer contains a full reply. If a single call to `feed` contains multiple
78
+ replies, `gets` should be called multiple times to extract all replies.
79
+
80
+ Example:
81
+
82
+ ```python
83
+ >>> reader = libvalkey.Reader()
84
+ >>> reader.feed("$5\r\nhello\r\n")
85
+ >>> reader.gets()
86
+ b'hello'
87
+ ```
88
+
89
+ When the buffer does not contain a full reply, `gets` returns `False`.
90
+ This means extra data is needed and `feed` should be called again before calling
91
+ `gets` again. Alternatively you could provide custom sentinel object via parameter,
92
+ which is useful for RESP3 protocol where native boolean types are supported:
93
+
94
+ Example:
95
+
96
+ ```python
97
+ >>> reader.feed("*2\r\n$5\r\nhello\r\n")
98
+ >>> reader.gets()
99
+ False
100
+ >>> reader.feed("$5\r\nworld\r\n")
101
+ >>> reader.gets()
102
+ [b'hello', b'world']
103
+ >>> reader = libvalkey.Reader(notEnoughData=Ellipsis)
104
+ >>> reader.gets()
105
+ Ellipsis
106
+ ```
107
+
108
+ #### Unicode
109
+
110
+ `libvalkey.Reader` is able to decode bulk data to any encoding Python supports.
111
+ To do so, specify the encoding you want to use for decoding replies when
112
+ initializing it:
113
+
114
+ ```python
115
+ >>> reader = libvalkey.Reader(encoding="utf-8", errors="strict")
116
+ >>> reader.feed(b"$3\r\n\xe2\x98\x83\r\n")
117
+ >>> reader.gets()
118
+ '☃'
119
+ ```
120
+
121
+ Decoding of bulk data will be attempted using the specified encoding and
122
+ error handler. If the error handler is `'strict'` (the default), a
123
+ `UnicodeDecodeError` is raised when data cannot be dedcoded. This is identical
124
+ to Python's default behavior. Other valid values to `errors` include
125
+ `'replace'`, `'ignore'`, and `'backslashreplace'`. More information on the
126
+ behavior of these error handlers can be found
127
+ [here](https://docs.python.org/3/howto/unicode.html#the-string-type).
128
+
129
+
130
+ When the specified encoding cannot be found, a `LookupError` will be raised
131
+ when calling `gets` for the first reply with bulk data.
132
+
133
+ #### Error handling
134
+
135
+ When a protocol error occurs (because of multiple threads using the same
136
+ socket, or some other condition that causes a corrupt stream), the error
137
+ `libvalkey.ProtocolError` is raised. Because the buffer is read in a lazy
138
+ fashion, it will only be raised when `gets` is called and the first reply in
139
+ the buffer contains an error. There is no way to recover from a faulty protocol
140
+ state, so when this happens, the I/O code feeding data to `Reader` should
141
+ probably reconnect.
142
+
143
+ The server can reply with error replies (`-ERR ...`). For these replies, the
144
+ custom error class `libvalkey.ReplyError` is returned, **but not raised**.
145
+
146
+ When other error types should be used (so existing code doesn't have to change
147
+ its `except` clauses), `Reader` can be initialized with the `protocolError` and
148
+ `replyError` keywords. These keywords should contain a *class* that is a
149
+ subclass of `Exception`. When not provided, `Reader` will use the default
150
+ error types.
151
+
152
+ ## Benchmarks
153
+
154
+ The repository contains a benchmarking script in the `benchmark` directory,
155
+ which uses [gevent](http://gevent.org/) to have non-blocking I/O and valkey-py
156
+ to handle connections. These benchmarks are done with a patched version of
157
+ valkey-py that uses libvalkey-py when it is available.
158
+
159
+ All benchmarks are done with 10 concurrent connections.
160
+
161
+ * SET key value + GET key
162
+ * valkey-py: 11.76 Kops
163
+ * valkey-py *with* libvalkey-py: 13.40 Kops
164
+ * improvement: **1.1x**
165
+
166
+ List entries in the following tests are 5 bytes.
167
+
168
+ * LRANGE list 0 **9**:
169
+ * valkey-py: 4.78 Kops
170
+ * valkey-py *with* libvalkey-py: 12.94 Kops
171
+ * improvement: **2.7x**
172
+ * LRANGE list 0 **99**:
173
+ * valkey-py: 0.73 Kops
174
+ * valkey-py *with* libvalkey-py: 11.90 Kops
175
+ * improvement: **16.3x**
176
+ * LRANGE list 0 **999**:
177
+ * valkey-py: 0.07 Kops
178
+ * valkey-py *with* libvalkey-py: 5.83 Kops
179
+ * improvement: **83.2x**
180
+
181
+ Throughput improvement for simple SET/GET is minimal, but the larger multi bulk replies
182
+ get, the larger the performance improvement is.
183
+
184
+ ## License
185
+
186
+ This code is released under the BSD license, as the license of hiredis-py at
187
+ the time of fork.
@@ -0,0 +1,46 @@
1
+ LICENSE
2
+ MANIFEST.in
3
+ README.md
4
+ setup.cfg
5
+ setup.py
6
+ libvalkey/__init__.py
7
+ libvalkey/libvalkey.pyi
8
+ libvalkey/py.typed
9
+ libvalkey/version.py
10
+ libvalkey.egg-info/PKG-INFO
11
+ libvalkey.egg-info/SOURCES.txt
12
+ libvalkey.egg-info/dependency_links.txt
13
+ libvalkey.egg-info/top_level.txt
14
+ src/libvalkey.c
15
+ src/libvalkey.h
16
+ src/pack.c
17
+ src/pack.h
18
+ src/reader.c
19
+ src/reader.h
20
+ tests/test_gc.py
21
+ tests/test_pack.py
22
+ tests/test_reader.py
23
+ vendor/libvalkey/src/adlist.c
24
+ vendor/libvalkey/src/adlist.h
25
+ vendor/libvalkey/src/alloc.c
26
+ vendor/libvalkey/src/async.c
27
+ vendor/libvalkey/src/async_private.h
28
+ vendor/libvalkey/src/cmddef.h
29
+ vendor/libvalkey/src/command.c
30
+ vendor/libvalkey/src/command.h
31
+ vendor/libvalkey/src/crc16.c
32
+ vendor/libvalkey/src/dict.c
33
+ vendor/libvalkey/src/fmacros.h
34
+ vendor/libvalkey/src/net.c
35
+ vendor/libvalkey/src/read.c
36
+ vendor/libvalkey/src/sds.c
37
+ vendor/libvalkey/src/sdsalloc.h
38
+ vendor/libvalkey/src/sockcompat.c
39
+ vendor/libvalkey/src/ssl.c
40
+ vendor/libvalkey/src/valkey.c
41
+ vendor/libvalkey/src/valkey_private.h
42
+ vendor/libvalkey/src/valkeycluster.c
43
+ vendor/libvalkey/src/valkeycluster_ssl.c
44
+ vendor/libvalkey/src/vkutil.c
45
+ vendor/libvalkey/src/vkutil.h
46
+ vendor/libvalkey/src/win32.h
@@ -0,0 +1 @@
1
+ libvalkey
@@ -0,0 +1,7 @@
1
+ [metadata]
2
+ description_file = README.md
3
+
4
+ [egg_info]
5
+ tag_build =
6
+ tag_date = 0
7
+