1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
|
Getting started!
================
A comprehensive, fast, pure-Python memcached client library.
Basic Usage
------------
.. code-block:: python
from pymemcache.client.base import Client
client = Client(('localhost', 11211))
client.set('some_key', 'some_value')
result = client.get('some_key')
Using UNIX domain sockets
-------------------------
You can also connect to a local memcached server over a UNIX domain socket by
passing the socket's path to the client's ``server`` parameter:
.. code-block:: python
from pymemcache.client.base import Client
client = Client('/var/run/memcached/memcached.sock')
Using a memcached cluster
-------------------------
This will use a consistent hashing algorithm to choose which server to
set/get the values from. It will also automatically rebalance depending
on if a server goes down.
.. code-block:: python
from pymemcache.client.hash import HashClient
client = HashClient([
('127.0.0.1', 11211),
('127.0.0.1', 11212)
])
client.set('some_key', 'some value')
result = client.get('some_key')
Using TLS
---------
**Memcached** `supports <https://github.com/memcached/memcached/wiki/TLS>`_
authentication and encryption via TLS since version **1.5.13**.
A Memcached server running with TLS enabled will only accept TLS connections.
To enable TLS in pymemcache, pass a valid TLS context to the client's
``tls_context`` parameter:
.. code-block:: python
import ssl
from pymemcache.client.base import Client
context = ssl.create_default_context(
cafile="my-ca-root.crt",
)
client = Client(('localhost', 11211), tls_context=context)
client.set('some_key', 'some_value')
result = client.get('some_key')
Serialization
--------------
.. code-block:: python
import json
from pymemcache.client.base import Client
class JsonSerde(object):
def serialize(self, key, value):
if isinstance(value, str):
return value, 1
return json.dumps(value), 2
def deserialize(self, key, value, flags):
if flags == 1:
return value
if flags == 2:
return json.loads(value)
raise Exception("Unknown serialization format")
client = Client(('localhost', 11211), serde=JsonSerde())
client.set('key', {'a':'b', 'c':'d'})
result = client.get('key')
pymemcache provides a default
`pickle <https://docs.python.org/3/library/pickle.html>`_-based serializer:
.. code-block:: python
from pymemcache.client.base import Client
from pymemcache import serde
class Foo(object):
pass
client = Client(('localhost', 11211), serde=serde.pickle_serde)
client.set('key', Foo())
result client.get('key')
The serializer uses the highest pickle protocol available. In order to make
sure multiple versions of Python can read the protocol version, you can specify
the version by explicitly instantiating :class:`pymemcache.serde.PickleSerde`:
.. code-block:: python
client = Client(
('localhost', 11211),
serde=serde.PickleSerde(pickle_version=2)
)
Deserialization with Python 3
-----------------------------
Values passed to the `serde.deserialize()` method will be bytestrings. It is
therefore necessary to encode and decode them correctly. Here's a version of
the `JsonSerde` from above which is more careful with encodings:
.. code-block:: python
class JsonSerde(object):
def serialize(self, key, value):
if isinstance(value, str):
return value.encode('utf-8'), 1
return json.dumps(value).encode('utf-8'), 2
def deserialize(self, key, value, flags):
if flags == 1:
return value.decode('utf-8')
if flags == 2:
return json.loads(value.decode('utf-8'))
raise Exception("Unknown serialization format")
Key Constraints
---------------
This client implements the ASCII protocol of memcached. This means keys should not
contain any of the following illegal characters:
Keys cannot have spaces, new lines, carriage returns, or null characters.
We suggest that if you have unicode characters, or long keys, you use an
effective hashing mechanism before calling this client.
At Pinterest, we have found that murmur3 hash is a great candidate for this.
Alternatively you can set `allow_unicode_keys` to support unicode keys, but
beware of what unicode encoding you use to make sure multiple clients can find
the same key.
Best Practices
---------------
- Always set the ``connect_timeout`` and ``timeout`` arguments in the
:py:class:`pymemcache.client.base.Client` constructor to avoid blocking
your process when memcached is slow. You might also want to enable the
``no_delay`` option, which sets the TCP_NODELAY flag on the connection's
socket.
- Use the ``noreply`` flag for a significant performance boost. The ``noreply``
flag is enabled by default for "set", "add", "replace", "append", "prepend",
and "delete". It is disabled by default for "cas", "incr" and "decr". It
obviously doesn't apply to any get calls.
- Use :func:`pymemcache.client.base.Client.get_many` and
:func:`pymemcache.client.base.Client.gets_many` whenever possible, as they
result in fewer round trip times for fetching multiple keys.
- Use the ``ignore_exc`` flag to treat memcache/network errors as cache misses
on calls to the get* methods. This prevents failures in memcache, or network
errors, from killing your web requests. Do not use this flag if you need to
know about errors from memcache, and make sure you have some other way to
detect memcache server failures.
- Unless you have a known reason to do otherwise, use the provided serializer
in `pymemcache.serde.pickle_serde` for any de/serialization of objects.
.. WARNING::
``noreply`` will not read errors returned from the memcached server.
If a function with ``noreply=True`` causes an error on the server, it will
still succeed and your next call which reads a response from memcached may
fail unexpectedly.
``pymemcached`` will try to catch and stop you from sending malformed
inputs to memcached, but if you are having unexplained errors, setting
``noreply=False`` may help you troubleshoot the issue.
|
