You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/topics/caching/cache.txt
+13-9Lines changed: 13 additions & 9 deletions
Original file line number
Diff line number
Diff line change
@@ -4,10 +4,10 @@
4
4
"Ram Rachum at ram.rachum.com" including link. The license may be obtained
5
5
at http://creativecommons.org/licenses/by-sa/3.0/
6
6
7
-
.. _topics-index:
7
+
.. _topics-caching-cache:
8
8
9
-
`caching.cache`
10
-
===============
9
+
:func:`caching.cache`
10
+
====================
11
11
12
12
A caching decorator that understands arguments
13
13
----------------------------------------------
@@ -16,10 +16,14 @@ The idea of a caching decorator is very cool. You decorate your function with a
16
16
caching decorator:
17
17
18
18
>>> from python_toolbox import caching
19
+
>>>
19
20
>>> @caching.cache
20
21
... def f(x):
21
22
... print('Calculating...')
22
23
... return x ** x # Some long expensive computation
24
+
25
+
And then, every time you call it, it'll cache the results for next time:
26
+
23
27
>>> f(4)
24
28
Calculating...
25
29
256
@@ -29,21 +33,21 @@ caching decorator:
29
33
>>> f(5)
30
34
3125
31
35
>>> f(5)
32
-
3125<
36
+
3125
33
37
34
38
As you can see, after the first time we calculate ``f(5)`` the result gets
35
39
saved to a cache and every time we'll call ``f(5)`` Python will return the
36
40
result from the cache instead of calculating it again. This prevents making
37
41
redundant performance-expensive calculations.
38
42
39
-
Now, depending on the function, there can be many different ways to make the same call. Example, if you have a function defined like this:
43
+
Now, depending on the function, there can be many different ways to make the same call. For example, if you have a function defined like this::
40
44
41
45
def g(a, b=2, **kwargs):
42
46
return whatever
43
47
44
48
Then ``g(1)``, ``g(1, 2)``, ``g(b=2, a=1)`` and even ``g(1, 2, **{})`` are all equivalent. They give the exact same arguments, just in different ways. Most caching decorators out there don't understand that. If you call ``g(1)`` and then ``g(1, 2)``, they will calculate the function again, because they don't understand that it's exactly the same call and they could use the cached result.
45
49
46
-
Enter `caching.cache`:
50
+
Enter :func:`caching.cache`:
47
51
48
52
>>> @caching.cache()
49
53
... def g(a, b=2, **kwargs):
@@ -63,15 +67,15 @@ Enter `caching.cache`:
63
67
Calculating
64
68
('something_else', 2, {})
65
69
66
-
As you can see above, `caching.cache` analyzes the function and understands
70
+
As you can see above, :func:`caching.cache` analyzes the function and understands
67
71
that calls like ``g(1)`` and ``g(1, 2)`` are identical and therefore should be
68
72
cached together.
69
73
70
74
71
75
Both limited and unlimited cache
72
76
--------------------------------
73
77
74
-
By default, the cache size will be unlimited. If you want to limit the cache size, pass in the `max_size` argument:
78
+
By default, the cache size will be unlimited. If you want to limit the cache size, pass in the ``max_size`` argument:
75
79
76
80
>>> @caching.cache(max_size=7)
77
81
... def f(): pass
@@ -84,7 +88,7 @@ get thrown away according to a `LRU order`_.
84
88
Sleekrefs
85
89
----------
86
90
87
-
`caching.cache` arguments with sleekrefs. Sleekrefs are a more robust variation of `weakrefs`_. They are basically a gracefully-degrading version of weakrefs, so you can use them on un-weakreff-able objects like ``int``\s, and they will just use regular references.
91
+
:func:`caching.cache` arguments with sleekrefs. Sleekrefs are a more robust variation of `weakrefs`_. They are basically a gracefully-degrading version of weakrefs, so you can use them on un-weakreff-able objects like :class:`int`\, and they will just use regular references.
88
92
89
93
The usage of sleekrefs prevents memory leaks when using potentially-heavy arguments.
0 commit comments